Git/Github for revision control of max patches/projects?

    Jul 30 2013 | 7:06 pm
    Anyone using git or github for revision control?
    Like basic one thread development. From what I've been told it does not handle branches/merging well at all, so nothing crazy/robust.
    Or more specifically, anyone using it to handle Max Projects?
    I'm wanting to get into git for max, but the lack of talk about it on the forum is a little worrisome.

    • Jul 31 2013 | 12:29 am
      well i'm planning to try soon-ish, but i'm not sure what it will give... the only sure thing is that Github is more awesome for text-based programmation languages. You can sort of understand some things reading a max patch as text, but....
    • Jul 31 2013 | 12:32 am
      Yeah, not ideal, particularly as the visual diffs, I would imagine, would be presented that way (as text).
      If nothing else, it would be super convenient to make a big change to my code and know that I have a bunch of safety blankets to roll back to.
    • Jul 31 2013 | 3:31 am
      I've been using git for my Max stuff for some time now. Text diffs are pretty much impossible because a minor change to a patcher can change the order in which the objects are stored so it looks like everything has changed. However, detailed comments when you commit stuff makes it reasonably easy to regress if you need. The branching system is also extremely handy as it lets you easily do some experiments (and keeping history) without risking your production code.
      The free SourceTree app from Atlassian is (in my opinion) the best GUI client for git out there.
    • Jul 31 2013 | 9:26 am
      Do you do branching with max/git? As in different branches which you later merge? Or do you mean just having an experimental branch that you don't commit to the main code until you're happy?
    • Jul 31 2013 | 2:19 pm
      I do branching but I wouldn't even dare to try and merge stuff, it would be a disaster. But I will have several branches so that I can try experiments and once I'm happy with something in a branch, I will just copy the changed patchers (very carefully) back into the main tree
    • Jul 31 2013 | 2:58 pm
      what is in merge function that is not suitable here ? if you use github, but you can't merge, it kinda loses some of its interests...
    • Jul 31 2013 | 9:07 pm
      So you merge whole files, and not individual?
      I've not set a git up yet, but I'll have a look at .gitattributes.
    • Aug 01 2013 | 8:44 am
      When i am using git with max i try to use many abstractions so it is easier to merge only specific edited parts of the patch. But this is also sometimes a pain in the ass.
    • Aug 01 2013 | 11:07 am
      For me, the merge is much less relevant than having a history of changes. What I care about is the ability to create temporary branches so I can try some things out (and still leverage history to revert) without impacting production. Once I'm happy with a particular change and have tested it sufficiently, I just overwrite the original with the changed object.
    • Aug 07 2013 | 8:15 am
      Ok, so I finally sat down and made a git and had a git-ty friend help me with some of the particulars. Worked pretty well I must say. Even managed some merge stuff without much incident.
      Graned it was a small-ish project, and I did lots of mini edits just to test the revision/branch/merging stuff.
      We did run into some peculiarities, so I figured I'd ask here to see if anyone has run into similar.
      1) A couple revisions in I had a bunch of entries for 'dependency cache' (using "bootpath") that used absolute links. This may be just a maxproject problem, but those will always get changed when the patch/project is shared. From my understanding, absolute paths are not ideal.
      2) It kept doing this patcher name thing where it would change the length of a string looking like this: "[1][1][2][3][1][etc]" It would become one character longer/shorter in some edits seemingly for no reason.
      3) An inlet switched ID from "signal" to "" with no changes to the patch.
      Lastly, has anyone tried creating static/absolute "id" values to see if that prevents Max from willy-nilly changing the assigned ids around with git-ting?
    • Dec 09 2013 | 4:46 pm
      There is a solution for the automatic reordering of the patch file contents, described in This should significantly reduce the number of changes you see when merging or simply comparing.
      You can send a new message to Max like this (or put it in an init file): ;max sortpatcherdictonsave 1
      This makes it so that the JSON files that are used by Max for saving patches will keep the dictionary in the same order (alphabetized) every time you save. If you are keeping your patches in version control then this should make your diffs a lot more usable.
    • Dec 09 2013 | 7:03 pm
      Hah, very useful information, thanks ! do you use that btw ?
    • Dec 09 2013 | 10:53 pm
      Yes, I do have this setting enabled. However, you still have to compare the textual representation of the patches, which can be quite painful.
      I'm wondering if the community would support the creation of a graphical Max patch comparison tool. I have done stuff like that before, albeit with other types of diagrams. Any love for the MaxDiff?
    • Dec 10 2013 | 3:01 am
      I'd love the pants off that...
    • Dec 10 2013 | 11:06 am
      Great to hear that! I have found a more fitting topic for continuing this discussion: Diff for .maxpat
      It would be great if more experienced Max programmers like yourself would chime in, and help me with figuring out the most common use cases.
    • Dec 10 2013 | 11:08 am
      All of the Jamoma project is versioned using Git and GitHub:
    • Dec 10 2013 | 1:21 pm
      Common use cases would be difficult to figure given the different programming styles. I've been ok without diffs for now as I'm mainly using abstractions, but a couple years ago I had more of a 'single big patch' kind of thing, where diffs would be hard to visualize/manage anyways.
    • Dec 10 2013 | 1:58 pm
      Of course the use of abstractions reduces the size of diffs, and it's a good approach in general.
      In terms of visualization, once an approximate rendering of the patch diagram is shown on the screen, it could be as simple as marking objects with different colors:
      • added = green
      • deleted = red
      • changed = yellow
      Regarding the connections between objects, marking them as added or deleted is all we can do.
      Initially, the tool would be read-only. If it catches on, then the merge functionality can be added as well.
    • Dec 10 2013 | 2:02 pm
      Ah right, yeah that would be great. And connections as text would be more than enough I think.
    • Dec 10 2013 | 2:17 pm
      What do you mean by "connections as text"?
    • Dec 10 2013 | 3:00 pm
      I meant your reference to connections between objects being rendered as text.
    • Dec 10 2013 | 3:45 pm
      Oh, I might not have been clear enough on that.
      What I meant was that added connections would be drawn in green, and deleted connections in red. Since they have no unique ID, the only way to identify them is by the inlet and outlet they connect. Because of this, marking a connection as changed does not make sense.
      I will create a couple of UI mockups to illustrate my ideas.
    • Dec 10 2013 | 5:32 pm
      Ah right. That's even better!
    • Dec 10 2013 | 6:25 pm
      But... Are you confident you can create diagrams out of max patcher text files ??
    • Dec 11 2013 | 9:21 am
      But… Are you confident you can create diagrams out of max patcher text files ??
      The patchers are stored in JSON format, which makes them very easy to read and process. From what I've seen, all the required graphical information is in there, so it shouldn't be a big deal. I'm not necessarily aiming for a 100% perfect replication of how it looks in Max, I just want to make it look close enough.
    • Dec 11 2013 | 10:05 am
      For what it's worth, generally when merging branches etc. in Jamoma, merges of patches work out well. If we get conflicts, the best way of resolving them is to open both original versions (local and remote), and visually inspect what the difference might be. It of course helps a lot to keep patches tidy and limit their size. Additionally, encapsulations also is really useful.
      C74 has put a lot of effort into formatting the JSON files in a way that simplifies git versioning. This works well enough for us in the Jamoma project currently that I personally don't feel the need for a solution that visually displays what objects and patch chords have been altered, added or deleted.
    • Dec 11 2013 | 12:33 pm
      My experience with Max patches and GIT was significantly more problematic than what Trond reports.
      Basically, in the project where we were using GIT, we found GIT's merging of different versions of a Max patch never worked at all. The result was invariably a file Max couldn't parse due to multitudes of errors. We always had to do a manual update based on visual comparison of different versions, a process that was easily prone to error. In the end we tried, as much as possible, to only have any one developer at a time making changes to any one Max patch, and keep those changes always in the main branch. (And, yes, I do know about the sortpatcherdictonsave incantation. It helps a little. Sometimes.)
      It was these difficulties with GIT and .maxpat that provided the primary incentive for starting the thread on a "diff for Max patches." I'm absolutely sure this is an achievable goal (it's more straightforward than resdiff, for those who've been around long enough to recall what that was), and I'm very excited that Sequadion is considering taking that on.
      Also, sure, the .maxpat files contain all the information needed to make a visual rendition of a Max patch, even for someone without access to the Max code base. Maybe not a down-to-the-last-pixel exact replica of what Max does, but good enough to make comparisons. For example, rendering GUI objects would be sort of a PitA to get going, because the basic look is stored in a .SVG file located somewhere deepish under the /Applications/Max [version number]/ file hierarchy, and the final look may be tweaked by code known only to the external object (.mxo or .mxe file). But a labeled box with inlets and outlets would be more than sufficient for understanding where changes have been made to a patch.
    • Dec 11 2013 | 5:37 pm
      Would love to see this but while you're at, a tool that would allow patches pasted into forums to be visualized would be wonderful. Consider how much more easy it would be to respond to questions about patchers if one didn't have to actually run Max first (or accessing forums from computers without max installed, iPads, for example)
    • Dec 11 2013 | 8:08 pm
      hahaha Nicolas, this is really nice (though it says "no tablet support yet" :) ) how did you find this ?
    • Dec 12 2013 | 3:47 pm
      Nice. I never saw that before. Would be nice if this was integrated into the main forum system (and worked on an iPad -:)
    • Dec 12 2013 | 4:46 pm
      Nice. As I said, not pixel-for-pixel identical. What surprised me were the differences in back-to-front order.
      But, hey! good enough for jazz.-)
      It looks like most of the work is done with JavaScript, but the heavy-lifting is probably done server side. So it could be anything (Sequadion had been musing about what language to use in the other thread).
    • Dec 12 2013 | 6:10 pm
      Great to see this topic come back to life, I appreciate everyone's input.
      For example, rendering GUI objects would be sort of a PitA to get going, because the basic look is stored in a .SVG file located somewhere deepish under the /Applications/Max [version number]/ file hierarchy, and the final look may be tweaked by code known only to the external object (.mxo or .mxe file).
      Well, if the custom graphical elements are SVG files, I could try and get permission from C74 to use them. This would probably get the tool quite close to the original rendering without having to write too much custom code. But I'm getting ahead of myself; the proof-of-concept implementation could simply draw boxes instead, like you suggested.
      Would love to see this but while you’re at, a tool that would allow patches pasted into forums to be visualized would be wonderful.
      It looks like most of the work is done with JavaScript, but the heavy-lifting is probably done server side. So it could be anything (Sequadion had been musing about what language to use in the other thread).
      My intention is to split this into two, independently usable parts: the diff engine and the patch rendering. The existing JavaScript renderer looks pretty good, I will get in touch with the author to see how much of that I can reuse. I've been playing with JavaScript for a while now, I guess it's time to use it in a proper project.
      This brings up the important question how people would want to use this tool: as a desktop application or as a web application? A web application is probably OK for open-source projects, but that might not be the case for proprietary stuff. There is a way to support both types of deployments though: there are a couple of tools out there for packaging a Node.js backend and an HTML/CSS/JavaScript based UI into a standalone desktop application.
    • Dec 14 2013 | 1:08 am
      Just wanted to mention that I sent a pull request to the github linguist ( to have better support for max patches. I changed the primary extension from mxt to maxpat, this means more of your projects should show up as Max and it should make searching for Max related stuff easier ! It seems to works as a lot of my projects that were tagged JavaScript or had no languages are now tagged Max !
    • Feb 27 2015 | 3:21 pm
      I don’t suppose this project ever made any progress? The various issues using Max and git together are annoying, and a tailored diff visualiser would be super helpful. I’m still using GitHub for Max projects, but once you reach collaboration, things get a little tricky, because merging can be very messy.
      Regarding the desktop vs web app question, I wonder whether a web app that plugs in via OAuth to GitHub and permits the comparison of forks or branches might be the most helpful?
      One can only dream that something along those lines might be added to GitHub itself or a GUI one day.
    • Feb 27 2015 | 5:11 pm
      I've been git-ing since this thread was originally made, and would totally love to be able to use the diff view. Even without that, in a non-collab (non-merge) environment it works fine, but it would be great if it was fully git-able that way.
    • Sep 06 2016 | 1:34 pm
      This is a bump in lieu of a request to the Cycling team to improve GIT support... I get Diffs in Max7 even just opening a patch and saving it open... I could even imagine myself dreaming about merges one day ;-)
    • Sep 06 2016 | 2:26 pm
      Bump, bump.
      A bit of loving attention to the .maxpat structure might go a long way. I'm guessing that the cacheing of local absolute file paths in patcher files provided some speed benefits at some point but I can't help but feel these ought really to be either generated on the fly or at least stored as a separate file that could then be git-ignored. As far as I can tell they don't hold any information that can't be generated from the rest of the patcher file.
    • Sep 06 2016 | 2:39 pm
      Big +1 here!
    • Aug 31 2017 | 2:53 pm
      Thanks for the info in this thread. DHJDHJDH recommended SourceTree as GUI client on Mac. Is it still the best option to use git with Max? Other good options?
    • Aug 31 2017 | 6:11 pm
      GitHub also have their own desktop client, which I use when I’m not using the command line:
    • Aug 31 2017 | 8:44 pm
      Thanks. Well, I also tried GitUp, for which you don't need any online account. But working in the Terminal seems like the best thing to do to get to know the tool, so I'll stick with that as a first step.