HowTo: Set up a github repository for your VCV patches

my patches folder has been a git repo for ages => fearless patching + free offsite backups to github JIC. @TroubledMind, git also provides convenient place to document my patches/changes via commit messages


shure you can do that, but my way to name the patches saves me one or two mouse clicks :stuck_out_tongue_winking_eye:

could you explain a bit for a noob how to set this up?

Do you do all your ‘gittting’ in the terminal, or do you use a gui? Just wondering how your workflow looks.

Is your repo on GitHub public? I’d like to see how it pans out.

if new to git, start with some vids/tuts to get comfortable the basics – tons of great stuff out there a search away. for the particulars, just navigate to your Rack installation folder, then to projects and execute git init from your preferred terminal/command line/shell prompt. you’ll find the following most useful: git status, git commit, git stash – again, tons of helpful references online to get familiar with the particulars

1 Like

two typical workflows: 1) typical scenario is I’ll commit my projects repo when I make meaningful changes to a particular patch (or hack something I like), and 2) live patching where I trigger automatic commits for each save during an extended patching session

in the later scenario, I use a file watcher and assign a git commit with a meaningful commit message. sometimes I’ll add custom text to the message by assigning a set of message fragments to midi events I trigger through a controller prior to saving so the commit includes the generic message fragment plus the triggered fragment, then I reset the custom fragment until triggered again. there are lots of free file watcher tools out there (I pick based on the programming language I’m hacking with). I also like to trigger save via midi controller instead of having to do it manually to keep that from interrupting my creative flow

one more fun tidbit – since I have my session history via my git repo, later I can iterate through my commit history and execute my session file changes by reloading the appropriate version – either manually or programmatically … fun times!


Nice. I’m going to look in to setting this up for myself pronto…

1 Like

Hi @dirkleas

I’m doing a crash course on Git this afternoon thanks to YouTube … So i have two questions for you:

  1. Are you doing all that only locally, or also on Github?

  2. Could you please expand on what follows (the app/tool you use, how do you connect it to vcv rack save command, etc.)? … I’m on Mac, but if you name some windows apps/tools, i will look for Mac equivalents.

Thanks in advance! :+1:

Sorry, but I’m gonna have to pick your brains again: is each new (ie fresh, from scratch) patch a separate branch?
I’m a bit new to the git game, and not yet sure of it’s capabilities and quirks.

Ignore this - I’m working it out…

Works brilliantly btw!

If you don’t like command-line, you can always use Github Desktop :wink:

If you are reading this thread and, like me, you found interesting the proposal of @dirkleas on the use of ‘git’ to manage the different versions of your patches, and it turns out that you are in Mac OS X 10.11 or later, you will have some problem when trying to use ‘git’ after installation, due to Apple System Integrity Protection (SIP) … So here are two solutions i’ve found in the Net (1) (2) to solve that (personally i used the second):

Solution 1:

1. Open the terminal
2. Type nano .bash_profile to open the bash_profile in nano (a terminal editor)
3. Copy/Paste this code: export PATH="/usr/local/bin:$PATH"
4. Exit and Save the bash_profile: Ctrl + X, and type `Y’ to save file change.
5. Refresh the bash shell environment: source ~/.bash_profile

Solution 2:

1. Open the terminal
2. Type nano .bash_profile to open the bash_profile in nano (a terminal editor)
3. Copy/Paste this code: export alias git='/usr/local/bin/git'
4. Exit and Save the bash_profile: Ctrl + X, and type `Y’ to save file change.
5. Refresh the bash shell environment: source ~/.bash_profile

Hope this helps somehow

Branches are used mainly to try code modifications or develop parallel versions of an already working code without efecting the master branch (i.e.: code) of the project … Once those modifications are working as expected we can merge the modified code to the master branch … So any new fresh patch is suposed to be a new project/repository.

  1. I’m generally doing this locally, then later git push if sharing/archiving on github
  2. tooling depends on what else I have going on – typically hack a few lines of code/script to automate (e.g. node.js + node-watch + child_process, golang + fsnotify + os.exec, etc.) – then I midi trigger via keyboard maestro on macos, et’al to map midi-to-keystrokes in rack (many keyboard macro apps support midi on rack supported platforms)

a minor constraint is git timestamps precision only supports down the second – if I need more precision, I add a guid to my commit message and store related detail elsewhere (e.g. sqlite3, file system, etc.) – most of the time, second-level precision is more than reasonable, especially when I’m triggering save based on performance touchpoints

I’m almost always working with the master branch (default) when doing this performance capture

1 Like

What are the ramifications/consequences of using a single (empty) MASTER with each branch containing versions of one patch?
The advantage is that Rack only has to look in one place for patches.
It’s not the way it’s used in code projects - but this isn’t a code project…

In fact IT IS a code project … If you open any .vcv file with a text editor (notepad (win), textedit (mac)) you’ll see that it is a code file that includes all the info about all the modules and its parameters + other info in the patch (i think its a .json file)

So let’s staaaaaart! … Hey guuuuuuuuuuyssssssss! (and gals) :sweat_smile::joy:


So the normal git process to use it with VCV Rack is:

  1. Create a working directory for your patch and go there with the command line terminal or GUI
  2. Create a local repo using git init in the terminal
  3. Start a new patch in VCV Rack and save it in your working directory
  4. Use git status command to check that git has knowledge of the new file
  5. Add the new file to the staging (intermediate) area using git add <filename.vcv>
  6. Use git status to check that git already has some file to commit to the repo
  7. Use git commit -m <"useful_msg"> (ex.: git commit -m "Initial Patch") to commit the file to the repo
  8. Use git log to check the commits

So you have already your initial patch in the git repo of your working directory.


Now if you want to work all the time with the same file (i.e.: no separate versions) you continue (1) working with your patch, (2) save it from time to time, (3) use steps 5. and 7. above (with appropiate msg to each commit) to commit your file to the repo, work again in it, and so on until you finish your project. And if for some reason you want to revert to some previous commit (kind of version):

  1. Use git log to see the list of all your commits and its asociated commit_number (the long line of numbers and letters right to the word ‘commit’)
  2. Copy the commit_number of the commit you want to go back to, and use git checkout <commit_number>

Now if you reload your patch you’ll see that the patch is in the state you save it in that commit … And if you use git log you’ll see that any later commits have dissapeared … BUT DON’T WORRY, because they are still there in the repo … So to go back to your latest commit use git checkout master (use git log to check that it is so) … So if you now reload the patch you’ll see that it is the last commit you made (i.e.: the last “version”).


Now let’s say that you want to keep your initial patch as it is, but want to check some new things, or new modules without “corrupting” the actual patch … Then you’ll need to create a new branch:

  1. Use git brach <branch_name> (ex.: git branch test) to create a new branch
  2. Use git branch to check that the new branch has been created

After that you have an exact copy of the master branch in the new branch

  1. Use git checkout <branch_name> to go to the new branch

Now you are in the new branch and any changes you do to the patch will effect only this branch … BUT NOTE that it seems that nothing has changed in the working folder: i.e.: the initial file is there and no sign of new folders with a .vcv file in it … WHAT’S HAPPENING?! :scream:

Don’t worry and do this:

  1. Make some changes to the patch and save it (again no changes in the working directory - the same file and no new folders)
  2. Use git add <filename.vcv> followed by a git commit -m <"useful_msg"> to commit the file to the repo
  3. Use the New File command in VCV Rack to clear the current patch
  4. Load the file in the working folder … you’ll see that it is the same patch you just saved … No problem!

Now do this:

  1. Use git checkout master to return to the master branch
  2. Use git branch to be sure you are in the master branch (there will be an asterisk beside the name)
  3. Again use the New File command in VCV Rack to clear the current patch
  4. Load the file in the working folder AND … TACHAAAAN!! … The GIT MIRACLE!!! :crazy_face:


Let’s say that you’re satisfied with the changes you’ve made in your new branch and you want them to be added to the patch in the master branch (let’s assume that the new branch is called “test”):

  1. Use git branch to be sure that you’re in the master branch, if not use git checkout master to go there
  2. Use git merge test to merge the changes you’ve made in the test branch with the patch in the master branch
  3. Clear the patch and load the file in the working folder … TACHAAAAAAN!!! … More Git Miracles!!!

NOTE: Don’t forget that you can always go back in commit history with git checkout <commit_number> … And keep in mind that any branch you’ve created will be there until you remove it with git -D <branch_name>

Isn’t Git wonderfull?!! :heart_eyes:
So THANKS A LOT @dirkleas for introducing Git to the VCV Rack Realm!! :clap:

Hope this can be of help to someone :pray:

P.S.: Next Chapter: Automating the Process!

1 Like


@zero, you can branch as much as you like. There is no negative effect :slightly_smiling_face:

Branching in git can be a complex subject, even among software professionals. It doesn’t have to complicated at all for this application.

If you like having a “one branch per patch” workflow, go for it! You’ll have good isolation between projects. If you decide to bring those branches into master at any point your options are open.

If you like the idea of keeping it very simple and only using the master branch, great! Your patches will be well looked after, and you have the option to branch at will.

1 Like

Thanks. I’m still learning git basics, and wanted to be sure I wasn’t transgressing on ‘good practice’!

It might be code, but we ain’t writing code. You might as well call an MS Word .doc file a ‘code’ project…