Using Git to sync Sublime Text settings

I felt the time had come to improve one thing, that bothered me a lot: being forced to make the same changes in the user preferences as often as the number of different systems, I am using the Sublime Text editor on.

I am a fan of dark themes. Wherever possible, I’m using a bright font on a dark background. Opera, Chrome and Edge as well as Thunderbird. I even activated the (at the moment) hidden dark theme for some universal apps in Windows 10. And of course: Sublime Text! Especially when it comes to coding, it’s essential for me not to be blinded by a bright shining ultra-wide monitor. So I’m using dark themes.

Recently I stumbled upon Flatland, a modification of the well known Soda theme, where you can e.g. configure the height of the sidebar tree entries. Cool! So I changed the theme, set the configuration and was able to see now even more entries in the sidebar tree. Some days later on another device, I opened Sublime Text and felt immediately unpleasant: ah right, I changed to a better theme. So I hit CTRL+SHIFT+P, began to type “install”, hit ENTER, began to type “flatland”, hit ENTER and my theme package was installed. But wait, something was missing… Wasn’t there a possibility to adjust the height of the sidebar entries?

This is just one single example, where it would have been nice to have a possibility to synchronize settings, that I’ve already configured on another system. So what about sharing the settings file with the help of common clouds? That should be possible, if you replace the user settings directory with a system link, that points to a shared location. Paul Redman gives an example in his blog of how to do that with OneDrive. That’s not bad, but what if I just want to sync some specific files and not the whole user settings directory? And what if I want to undo some changes to a settings file or don’t want to automatically sync all files?

That was when I thought about version control — in my case, that’s Git. And that’s how it worked for me to sync my Sublime Text settings with Git:

> Create the repository

I’m assuming, you have Git installed on every device you’re running Sublime Text on. First create the repository on GitHub (of course you can take your own server — this is only an example) and get the URL of your new repository. You can directly create a .gitignore file with the following content:

# Ignore everything...
# ... except preferences

With the help of the asterisk only those files are watched, that are explicitly listed with a preceding exclamation mark. If you also want to sync your packages, you can just add the following line (assuming you are using Package Control):

!Package Control.sublime-settings

This file contains a list of installed packages. If that list has changed and Sublime Text is restarted, Package Control will automatically install missing packages, as described here. It’s even possible to sync modified theme files. You only have to copy them into the user directory, add them to the .gitignore file with exclamation mark and change the path to the theme files in the user settings.

> Set up the first device

First you will have to push your current Sublime Text settings to the remote repository. Navigate to the user directory (you can find it with Preferences > Browse Packages) of Sublime Text and use the following Git commands, assuming you have created a Git repository on a server:

$ git init
$ git remote add origin <repository url>
$ git fetch
$ git commit -am "added: settings and packages"
$ git push

> Set up all other devices

Now you can create the repository in the existing user directory of all other Sublime Text devices:

$ git init
$ git remote add origin <repository url>
$ git fetch
$ git reset --hard origin/master

With the last line, the existing setting files will be overwritten by those from the repository. If you want your local files to be committed, just make a backup before and copy the files back to the created repository to commit the changes. Or remove the “hard” flag of the reset instruction and merge all changes manually.

> Synchronize settings manually

Now you just have to pull the git repository to sync current settings. Here are two examples with Sublime Text 3 in a Git shell.

Windows 10:

$ git -C ~/AppData/Roaming/Sublime\ Text\ 3/Packages/User/ pull


$ git -C ~/.config/sublime-text-3/Packages/User pull

It occurs, that the settings files differ right after pulling the current versions from the repository (especially when Package Control loads missing packages) e.g. because of a different order of entries in the packages list or the settings elements. In that case you can just use the hard-reset instruction to overwrite your unwanted local changes.

> Synchronize settings with Git Package

It’s even easier to sync the settings with the Git Package for Sublime Text. Here you don’t have to switch to a Git Shell to pull or push the changes but you can do it right in Sublime Text.

Git Package on Sublime Text 3

Simply open your settings file and you will see any changes in the status bar. If you have to pull or push something just hit CTRL+SHIFT+P to open the command palette and start typing “git”. Now you can see all options to pull, push or reset your current working directory.

So that’s all it takes to sync Sublime Text settings using Git. If you are already familiar with Git anyway, give it a try — for me, it saved a lot of time.

If you like this article and want to give some love back, feel free to buy me a coffee :)

Edited: 3rd October 2016 (differentiate between first and other devices)
Edited: 5th July 2016 (added Git Package)
Published: 29th September 2015