Free Obsidian Sync using GitHub that actually works

Why Obsidian?

One of the advantages of using Obsidian[01] for your notes is that they are just plain text files sitting in a folder on your computer. Nothing locking your writing inside a service you don’t control. Every note is a Markdown (.md) file, so you can open it in any text editor. All Obsidian is providing is the editing and visual layer for you to read and edit your notes.

The fact that your notes aren’t locked away is a major reason to consider Obsidian as your note-taking tool.

The down side of “local files” is that syncing them across your devices requires some effort or cost. Obsidian offers its own sync service for $4 a month[02], and if you want it to just work with minimal effort, it’s a fair price (with one minor downside we’ll discuss later). But you can replicate it for free using a private GitHub repository, which will not only sync your notes across devices, but also provide you with a backup of your notes.

One thing I’ve found that improved this setup from other guides out there, is using the community Obsidian Git plugin[03] on desktop, and the GitSync[04] app on your phone. If this is all sounding a little confusing, it will hopefully make more sense once we’ve gone through the steps.

Obsidian Git on desktop, GitSync on mobile. That split is what makes this setup reliable.

If you’re already across GitHub and Obsidian, here’s the short version:

1. Download Obsidian and create a local vault (a folder on your computer).
2. Download GitHub Desktop to create a private repository and push your vault to it.
3. Install the Obsidian Git plugin on desktop and configure auto-sync.
4. Download the Obsidian mobile app.
5. Install GitSync on your phone, authenticate with GitHub, and clone the repository. Open the Obsidian mobile app and point it at the cloned folder as your vault.

Step 1: Install Obsidian and create a vault

If you don’t have Obsidian yet, download it and install it. We’ll then create a vault, which is just a folder. Every note you write becomes a .md (plain text) file inside it.

1. Create a new folder on your computer that you’ll use for all your notes.
2. Download and install Obsidian.
3. Open Obsidian and select the folder you created in step 1 as your vault.

Step 2: Create your GitHub repository

Create a GitHub account

If you haven’t already, set up a GitHub account.

1. Navigate to https://github.com/.
2. Click Sign up, or click on Continue with Google to sign up using social login.
3. Follow the prompts.

Now we’ll do some preparation before syncing your vault to a git repository (repo).

Create a .gitignore file

Obsidian constantly updates workspace files in the background just by you opening the app. Think of these like settings or preferences for the app. If you include these files to your repo, you’ll have trouble syncing between your computer and your phone.

To solve this, create a plain text file in your vault folder named exactly .gitignore (no filename extension) and add the following lines to it:

.obsidian/workspace.json
.obsidian/workspace-mobile.json
.obsidian/workspace*.json

All this file does is stop any of the files referenced inside it from being synced to your repo.

Creating a private repo

Next, you need to create a private repo on GitHub. The easiest way to do this is using GitHub Desktop, which lets you push the vault folder to GitHub without touching the command line (i.e. no need to use Terminal).

1. Download GitHub Desktop and install it.
2. Open GitHub Desktop and go to File > Add Local Repository
3. Browse to and select your local vault folder.
4. GitHub Desktop will warn you that this folder isn’t a Git repository yet. Click the prompt to create a repository here.
5. Give the repo a name you’ll recognise, such as my-obsidian-vault, and click Create Repository.
6. Click Publish repository in the top toolbar. Make sure the “Keep this code private” box is checked, and hit Publish.

Set up your GitHub Personal Access Token (optional)

This is only needed if you decide to use the command line to create your private git repo, or as a backup if regular authentication doesn’t work when you set up GitSync on your mobile.

Using the command line (optional)

If you prefer using the command line (accessing git via Terminal), install git CLI. Then we can make sure your Git user details are configured.

git config user.name "Your GitHub Username"
git config user.email "your-github-email@example.com"

# Then we'll create the repository, commit your files, and push them to GitHub:

git init
git remote add origin https://github.com/yourusername/your-vault.git
git add .
git commit -m "initial vault"
git branch -M main
git push -u origin main

Step 3: Configure Obsidian Git on desktop

Now back to Obsidian on your desktop.

1. Go to Settings > Community Plugins and turn off restricted mode.
2. Browse for Obsidian Git and install it.
3. Open the plugin settings and configure the following:

• Split timers for automatic commit and sync: On
• Auto commit-and-sync (minutes): 4. The plugin commits and pushes your changes every 4 minutes. If you close Obsidian before the timer fires, it runs the commit on the next startup instead.
• Auto commit after stopping file edits: On. This will commit changes to git when it detects that you’ve stopped editing a file.
• Auto pull interval (minutes): 5. The plugin pulls updates from git every 5 minutes.
• Pull on startup: On. This pulls the latest changes from GitHub each time you open Obsidian, so your desktop always starts with the most current version of your vault.
• Author name for commit / Author email for commit: Enter name (or nickname) and your email address matching your GitHub account.
• Disable informative notifications (optional): You may eventually want to switch this off as the notifications may get a little distracting.

After saving, we can test that it’s all working as expected. Open the Obsidian command palette (Cmd/Ctrl + P, then search “Obsidian Git: Create backup”) to confirm it commits and pushes (syncs) successfully. If it does, the desktop side is done.

Step 4: Download Obsidian on mobile

If you haven’t already, download Obsidian from the App Store on iOS or Google Play on Android. We’ll open and set it up later. Just make sure you’ve downloaded it.

Step 5: Set up GitSync on mobile

1. Download GitSync from the App Store on iOS or Google Play on Android.
2. Sign in with GitHub when prompted.

Clone your repository

In the GitSync app:

1. Tap Add Repository, paste in your repository’s HTTPS URL (the format is https://github.com/yourusername/your-vault.git)
2. Choose where to save it on your device. On iOS, the On My iPhone > Obsidian folder is a reliable location. On Android, a folder inside Documents works well. GitSync will clone the repository to your device. Once it finishes;
3. Open the Obsidian mobile app, tap Open folder as vault, and navigate to the folder GitSync created. Select it and your notes will appear.

Important: As soon as your vault opens, go into Obsidian Git settings on your mobile device and turn on the Disable on this device option. This makes sure that you don’t have the Git plugin trying to sync alongside the GitSync app. Alternatively, you can configure Obsidian to use a separate configuration folder on mobile, such as .obsidian-mobile, but this is a little more advanced.

Configure GitSync settings

• Sync on App Open: On. GitSync pulls the latest changes from GitHub whenever you launch the app.
• Sync on App Close: On. GitSync commits and pushes any local changes whenever you leave the app.
• Author Name and Email: Set these to the same values you entered in the Obsidian Git plugin on desktop.

Platform-specific optimisations:

• Android Accessibility Service: For the automatic syncing features to function on Android, GitSync requires the device’s Accessibility Service permission to be enabled (this allows it to detect when Obsidian opens and closes).
• Battery Optimisation: To ensure GitSync can reliably push your commits to GitHub the moment you close Obsidian, set GitSync to “Unrestricted” battery usage (Android) or ensure “Background App Refresh” is enabled (iOS).

If you’re having any issues with the setup on mobile, take a look at these detailed setup instructions.

Bonus: edit from your web browser

Because your vault lives in a GitHub repository, pressing the period key (.) on any GitHub repo page opens the github.dev web editor in your browser. It’s essentially a full text editor that allows you to edit your notes in your web browser, without the need to install any applications.

This is useful if you are on a work computer where you can’t install Obsidian. It’s also something you won’t be able to do with Obsidian Sync, as it still requires the Obsidian app to work.

If you want a less cluttered editor than github.dev, you can also try StackEdit. It connects to your GitHub repo and gives you a more focused writing experience in the browser.

The real value

The real value of this setup is not just the free sync, it’s having your notes in a format and location that any tool can reach. Once your vault is a GitHub repo, you can write from your phone, your browser, or your laptop.

This also opens the door to doing more interesting things with your notes. In an upcoming article, I will walk through using AI to help take the effort out of organising your notes, and help surface what’s important.