DEV Community

Cover image for I Built a Git Sync Tool for My Obsidian Vault
Sijan Bhusal
Sijan Bhusal

Posted on

I Built a Git Sync Tool for My Obsidian Vault

#archlinux #linux #git #obsidian

I Built a Git Sync Tool for My Obsidian Vault

You write notes, you save them, you forget to push to GitHub. Then your laptop dies, and your notes are gone. I built a single Bash script that automates the entire sync workflow, and it works with any Git repo.

If you use Obsidian (or any plain-text note-taking system) and sync via Git, you know the drill: write notes, stage changes, commit, fetch, check status, pull, push. Every time. It's 6 repetitive commands that you will inevitably skip until disaster strikes.

I got tired of this and built git-sync, a single Bash script that does everything in one go.

What It Does

git-sync is a terminal-based Git sync tool that:

  1. Auto-commits all changes with a timestamp
  2. Fetches remote state
  3. Detects divergence (ahead/behind)
  4. Shows you only the relevant sync options
  5. Executes your choice with safety guard rails

How It Works

Run it from inside any Git repo:

./git-sync
Enter fullscreen mode Exit fullscreen mode

Phase 1 - Auto-commit: Staged or unstaged changes are committed automatically with a message like "Last Sync: Jun-12 (Arch)". The device name is configurable.

Phase 2 - Fetch & Detect: It fetches from remote, counts how many commits ahead and behind you are, and categorises the state: ahead, behind, diverged, or in-sync.

Phase 3 - Smart Menu: Only relevant options are shown:

State Options
Ahead only Upload, Sync, Force push, Cancel
Behind only Download, Sync, Hard reset, Cancel
Diverged All six options

Phase 4 - Execute: The chosen action runs with a spinner and status messages. Destructive operations (force push, hard reset) require explicit confirmation.

Why It's Useful for Notes Syncing

Obsidian + Git is a powerful combo. Your notes are plain markdown, version-controlled, accessible from any device. The friction is the sync ritual. git-sync removes it.

Multi-device workflows: I run this on my Arch desktop (DEVICE_NAME="Arch") and my work laptop (DEVICE_NAME="Laptop"). The auto-commit message tells me exactly which machine made each sync, so I can trace conflicts back to the source.

Zero cognitive overhead: One command replaces git add -A && git commit -m "..." && git fetch && git pull --rebase && git push. You don't have to think about Git state. The script handles edge cases (diverged branches, force-push scenarios, no remote configured).

Installation 

# Clone the repo
git clone https://github.com/Sijan-Bhusal/git-sync.git
cd note-sync

# Install gum (the terminal UI library)
sudo pacman -S gum          # Arch
brew install gum            # macOS
# Or grab a .deb from the releases page

# Make it executable
chmod +x git-sync

# (Optional) Edit DEVICE_NAME in the script
nano git-sync
Enter fullscreen mode Exit fullscreen mode

Key Design Decisions

  • gum for UI: Colours, spinners, confirm dialogs make it approachable even if you're not comfortable with raw Git CLI
  • One file, zero deps (except gum): No npm install, no Python, no config files: just a Bash script you can read and modify
  • Safety first: Force push and hard reset are guarded by explicit confirmation prompts
  • DEVICE_NAME tracking: Know which machine synced when, invaluable for multi-machine vaults

Top comments (0)