obsidian-git-livesync

Bridge git pushes to Obsidian via CouchDB and the Self-hosted LiveSync plugin.

Problem

Obsidian's Self-hosted LiveSync plugin syncs notes between devices via CouchDB replication. But it only works when Obsidian is running. If you edit markdown files in a headless environment (CI, server, scripts, git hooks), there is no way to push those changes into the LiveSync network. Your phone and other devices never see the update.

There is no CLI bridge between git and LiveSync. This tool fills that gap.

Solution

obsidian-git-livesync writes markdown files directly to CouchDB in LiveSync's document format, so all connected LiveSync clients replicate the changes instantly -- no Obsidian desktop needed.

Architecture

git push --> post-receive hook
          --> obsidian-git-livesync sync
          --> reads changed .md files from disk
          --> writes to CouchDB (LiveSync document format)
          --> all LiveSync clients replicate via CouchDB
          <-- phone sees changes in seconds

Quick Start

1. Start CouchDB

Clone this repo and start CouchDB using the included Docker Compose file:

git clone https://github.com/ecstatic-pirate/obsidian-git-livesync
cd obsidian-git-livesync
docker compose up -d
bash scripts/setup-couchdb.sh

The Docker defaults are admin / password. Edit docker-compose.yml before running if you want different credentials.

2. Init and configure

npx obsidian-git-livesync init
# Edit .obsidian-git-livesync.json — fill in couchdbUser and couchdbPassword
# Docker defaults: admin / password

3. Validate the connection

npx obsidian-git-livesync validate
# Should print: [OK] Connected to http://localhost:5984/obsidian-livesync

4. Sync

# Sync all markdown files in the current directory
npx obsidian-git-livesync sync --all

# Sync files changed in the last git commit
npx obsidian-git-livesync sync --git

# Watch for changes in real time
npx obsidian-git-livesync watch .

CLI Reference

Global Options

| Flag | Description | |------|-------------| | --version | Show version number | | --config <path> | Path to config file (default: .obsidian-git-livesync.json) | | --verbose | Log each file as it syncs | | --dry-run | Show what would be synced without writing to CouchDB |

Commands

| Command | Description | |---------|-------------| | sync [files...] | Sync specific files to CouchDB | | sync --git | Sync files changed in the last git commit | | sync --all | Sync all files in the vault directory | | watch [dir] | Watch a directory and sync changes in real time | | validate | Test connection to CouchDB | | init | Create a template config file |

Sync Options

| Flag | Description | Default | |------|-------------|---------| | --git | Sync files from last git commit | - | | --all | Sync entire vault directory | - | | --delete | Delete files from CouchDB that no longer exist on disk | false | | --extensions <exts> | Comma-separated file extensions | .md | | --debounce <ms> | Debounce interval in milliseconds | 200 |

Watch Options

| Flag | Description | Default | |------|-------------|---------| | --extensions <exts> | Comma-separated file extensions to watch | .md | | --debounce <ms> | Debounce interval in milliseconds | 200 |

Git Hook Setup

A post-receive hook is included for bare git repos. When you push to the repo, it automatically syncs changed markdown files to CouchDB.

Installation

# If you cloned this repo:
cp hooks/post-receive.sh /path/to/repo.git/hooks/post-receive

# Or if installed via npm (npx or local install):
cp node_modules/obsidian-git-livesync/hooks/post-receive.sh /path/to/repo.git/hooks/post-receive

chmod +x /path/to/repo.git/hooks/post-receive

The hook:

• Only triggers on pushes to main or master
• Detects changed .md files between the old and new revisions
• Calls npx obsidian-git-livesync sync with those files
• Handles initial pushes (empty repo) correctly

To sync additional file types, edit the EXTENSIONS variable at the top of the hook script.

Docker Compose

The included docker-compose.yml runs CouchDB 3 locally:

services:
  couchdb:
    image: couchdb:3
    ports:
      - "5984:5984"
    environment:
      COUCHDB_USER: admin
      COUCHDB_PASSWORD: password
    volumes:
      - couchdb_data:/opt/couchdb/data

After starting the container, run bash scripts/setup-couchdb.sh to:

• Configure single-node cluster mode
• Create the obsidian-livesync database
• Enable CORS for Obsidian
• Set request and document size limits
• Require authenticated access

Configuration

Configuration is loaded in this priority order: environment variables > config file > defaults.

Config File

Created by obsidian-git-livesync init at .obsidian-git-livesync.json:

{
  "couchdbUrl": "http://localhost:5984",
  "couchdbUser": "admin",
  "couchdbPassword": "password",
  "couchdbDatabase": "obsidian-livesync",
  "vaultRoot": ".",
  "extensions": [".md"],
  "debounce": 200
}

Environment Variables

| Variable | Description | Default | |----------|-------------|---------| | COUCHDB_URL | CouchDB server URL | http://localhost:5984 | | COUCHDB_USER | CouchDB username | (required) | | COUCHDB_PASSWORD | CouchDB password | (required) | | COUCHDB_DATABASE | Database name | obsidian-livesync | | VAULT_ROOT | Root directory for vault files | current directory | | PASSPHRASE | Encryption passphrase (if LiveSync uses one) | (none) |

Environment variables override values in the config file.

How It Works

Obsidian's Self-hosted LiveSync plugin stores files in CouchDB using a specific document format:

1. Metadata document (_id = file path, e.g. notes/hello.md)

   • type: "plain"
   • children: array of chunk IDs
   • ctime, mtime, size: file timestamps and size

2. Leaf (chunk) document (_id = h: + SHA-256 hash)

   • type: "leaf"
   • data: file content (plain text for text files)

This tool writes files in that exact format. When a file is synced:

• Content is hashed to produce a chunk ID (content-addressable)
• A leaf document is created (or reused if the same content already exists)
• A metadata document is created or updated with the leaf reference

Once written to CouchDB, all LiveSync clients connected to the same database replicate the change automatically via CouchDB's replication protocol.

Note on livesync-commonlib: The official DirectFileManipulator API lives in vrtmrz/livesync-commonlib but is Deno-first and not installable via npm. This project uses a direct CouchDB REST API client that speaks the same document format. See src/couchdb-client.ts.

Limitations

• Text files only. Binary files (images, PDFs, etc.) are not synced. Only text-based extensions are supported (.md, .txt, .canvas, .csv, .svg, .html, .css, .js, .xml).
• Requires CouchDB + LiveSync plugin. You need a running CouchDB instance and Obsidian's Self-hosted LiveSync plugin configured to use it.
• Schema coupling. The document format is reverse-engineered from LiveSync's internal storage. If LiveSync changes its format in a future update, this tool may need corresponding updates.
• No conflict resolution. If the same file is edited both via this tool and via Obsidian simultaneously, CouchDB will create a conflict. LiveSync's conflict resolution in Obsidian will handle it, but the behavior depends on your LiveSync settings.
• Single-chunk storage. Currently stores each file as a single chunk. Very large files (>1MB) may benefit from multi-chunk splitting in the future, matching LiveSync's chunking behavior.

License

MIT