Ditch the Subscription: A Free Obsidian Sync Setup for Linux & Mac

Problem

I recently shifted my daily workflow to Linux, deciding to turn my laptop into the central hub for storing all my ideas, code snippets, and project documentation. However, I still retain a MacBook for specific tasks.

I needed my notes to synchronize perfectly between both computers. I was looking for a solution that wouldn’t require purchasing the official Obsidian Sync subscription, giving me full control over my data using tools I’m already comfortable with.

Analysis

The biggest pain was the OS incompatibility. While iCloud works natively on my Mac, it’s a total no-go on Linux, so my old sync method was basically broken. I needed something that works everywhere.

After a quick googling, I found the Obsidian Git plugin

https://github.com/Vinzent03/obsidian-git

Solution

Here is how I set everything up to get the sync working smoothly:

Stage 1: Installing Obsidian Git

I needed to get the plugin installed and active within Obsidian.

1. Disable Restricted Mode: I went to Settings > Community plugins and turned off Restricted mode to allow third-party add-ons.

2. Access the Marketplace: I clicked the Browse button to open the community plugins list.

3. Find the Git Integration: I searched for “git” in the search bar.

4. Install the Plugin: I clicked the Install button.

5. Enable the plugin: After installation, I immediately flipped the toggle to Enable to make sure the plugin was actually running.

Stage 2: GitHub Configuration

Next, I needed to set up the remote storage and get the credentials ready.

1. Create a New Repository: — I went to github.com/new. — I gave the repository a name obsidian-notes and set the visibility to Private. — I checked the box for Add README. This is necessary so the repository isn’t empty from the start.

2. Generate a Personal Access Token: To let Obsidian connect to my account, I needed a specific token, not my standard password.

— I went to Settings on GitHub, scrolled down to Developer settings, and selected Personal access tokens > Tokens (classic).

• I clicked Generate new token (classic).

• Expiration: I set this to No expiration so I don’t have to renew it constantly.
• Scopes: I checked the box for repo (Full control of private repositories). This is the most important setting.

• I clicked Generate token and copied it immediately because it’s never shown again.

3. Prepare the Connection URL: Although I paste this into Obsidian later, I constructed the URL now while I had the token handy. It requires this specific format:

https://YOUR_TOKEN@github.com/YOUR_USERNAME/REPO_NAME.git

Stage 3: Syncing with Obsidian Git

1. Run the Clone Command: I fired up the Command Palette with Ctrl + P and searched for “clone”. I selected the option Git: Clone an existing remote repo.

2. Enter the Magic URL: In the “Remote URL” field, I pasted the long string I prepared earlier:

https://YOUR_TOKEN@github.com/YOUR_USERNAME/REPO_NAME.git

3. Select the Destination: It asked for a “Directory for clone”. I typed the name of the folder where I wanted my notes to have.

4. Restart and Load: I restarted Obsidian to apply the changes. Once it reloaded, I saw the README.md file from my repo appearing in my file list. Success!

Settings I made in my Obsidian Git

To access these settings:

1. Press Ctrl + , (Settings).
2. Go to Community plugins and click the gear icon next to the Git plugin.

1. Automatic Backup (Push)

This is the most important setting that ensures your notes are automatically sent to GitHub.

• Setting: Vault backup interval (minutes)
• What it does: Every X minutes, the plugin will automatically perform: — git add (stage files) — git commit (save changes) — git push (upload to server)
• Result: You don’t have to remember to click “backup” manually.

2. Automatic Update (Pull)

This setting is crucial if you plan to use Obsidian on more than one device (e.g., a desktop and a laptop) to avoid file conflicts.

• Setting: Pull updates on startup
• What it does: Every time you open Obsidian, the plugin will first check GitHub for any new versions of your notes and download them before you start writing.

3. Disable notifications

I have set the backup interval to 1 minute, Obsidian will show a notification bubble saying “Git: Pushed X files” every single minute. This can get annoying.

• Setting: Disable notifications.
• My recommendation: Consider turning this ON once you verify that the automation is working correctly, so the pop-ups don’t distract you while writing.

Verification

Here is how I tested it:

1. I created a new note called linux_test.md.

2. To verify the sync, I simply waited a moment to force the sync cycle to kick in.
3. I opened my browser and checked the repository on GitHub.
4. Result: The file Linux_Test.md appeared on the website.

The sync was alive!