Skip to content
Get packs

Guide · Open source

How to use obsidian-git: setup, auto-sync and tips

Updated · written with AI from the project's own documentation and checked against our catalogue data

obsidian-git is a community plugin for the Obsidian note-taking app that connects your vault, the folder holding your notes, to a Git repository. This guide explains what you need installed, how to run commit-and-sync and the main views, and where the plugin is limited. By the end you will know how to version your notes, back them up to a remote and review or resolve changes inside Obsidian.

Git Plugin for ObsidianVinzent03/obsidian-git · ★ 12.2k · MIT

Quick start

  1. 1Confirm prerequisites. Install the Obsidian desktop app and Git on your system.
  2. 2Get the source. Clone the repository with the git clone command from the README if you want the code.
  3. 3Set up authentication. Follow the Authentication Guide in the documentation if your Git service needs HTTPS or SSH setup.
  4. 4Run Commit-and-sync. Open the Command Palette and run Commit-and-sync to commit, pull and push your vault.
  5. 5Review with the Source Control View. Open the Source control view command to stage, unstage and diff files before committing.
  6. 6Resolve conflicts if they occur. Use the editor's conflict buttons, mark the file as resolved in Source Control, then commit.

What you need before you start

The plugin is for the Obsidian desktop app. You also need Git installed on your system, because on desktop the plugin runs your installed Git. Mobile is covered separately below and is not recommended by the author.

The README points to a full documentation site for setup instructions, including Linux installation details and authentication for HTTPS or SSH.

  • Obsidian desktop app
  • Git installed on your system
  • Basic familiarity with Git concepts such as commits, branches and remotes

Get the obsidian-git source from GitHub

The source repository is Vinzent03/obsidian-git on GitHub, released under the MIT licence and written in TypeScript. The README provides this command to clone the repository.

Refer to the full documentation for how to install the plugin into your vault's plugin setup in Obsidian.

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

Run commit-and-sync and the main commands

Commit-and-sync is the core feature. With default settings, the Commit-and-sync command commits all changes, pulls, and pushes. Open the Command Palette in Obsidian to find it.

Commit only commits staged changes when there are any. If nothing is staged, the plugin either stages and commits everything or stops, depending on the Stage all changes when nothing is staged setting. Commit all changes commits without pushing.

  • Commit-and-sync: commit all changes, pull, and push by default
  • Commit-and-sync with specific message: same, with your own message
  • Commit-and-sync and close: same, and closes the Obsidian window on desktop
  • Commit all changes: commits without pushing
  • Push and Pull: run each step on its own

Review changes with the Source Control, History and Diff views

The Source Control View lets you stage and unstage files, commit and see diffs. Open it with the Open source control view command.

The History View shows commit logs and changed files. Open it with Open history view. Author and date are hidden by default and can be turned on in the settings.

The Diff View compares versions side by side and lets you stage or reset individual hunks. Open it from the Source Control View or with Open diff view.

  • Open source control view: stage/unstage, commit and diff files
  • Open history view: browse commits and changed files
  • Open diff view: review, stage or reset hunks

Use editor signs and conflict resolution

On desktop, signs in Live Preview mark added, modified and deleted lines or hunks. You can stage or reset changes from the signs and use commands to move between hunks. This needs to be enabled in the plugin settings.

When a merge conflicts, the editor highlights your version and the incoming version, with buttons to keep ours, theirs or both. Source Control lists conflicted files. After reviewing, mark the file as resolved and commit to finish the merge. The README links to a separate conflict resolution guide.

  • Signs are desktop only
  • Common ancestor (base) controls appear when Git includes it, for example with merge.conflictStyle=diff3

Know the limits on mobile and Linux

The README says the mobile implementation is very unstable and recommends other sync services. It uses isomorphic-git, a JavaScript re-implementation of Git, which has no SSH authentication, limited repository size, no rebase merge strategy and no submodule support. Crashes on clone or pull can happen depending on device memory.

On Linux, the README says Snap is not supported and Flatpak is not recommended because it lacks access to all system files. It suggests AppImage or a full-access installation of your system's package manager.

  • Mobile: no SSH, limited repo size, no rebase, no submodules
  • Linux: avoid Snap; Flatpak is not recommended

What people use it for

  • Keep a version history of your notes so you can see earlier commits in the History View.
  • Back up a vault to a remote Git repository with scheduled commit, pull and push.
  • Review and stage individual hunks in the Diff View before committing.
  • Resolve merge conflicts in Markdown notes directly in the editor.

Frequently asked questions

Is obsidian-git free?

The source repository is released under the MIT licence, according to the project page. The README does not list any prices.

Does obsidian-git work on mobile?

The README says the mobile implementation is very unstable and recommends other sync services. It uses isomorphic-git, which lacks SSH authentication and has memory limits.

What do I need installed to use obsidian-git?

You need the Obsidian desktop app and Git installed on your system. On desktop, the plugin runs your installed Git.

Can obsidian-git resolve merge conflicts?

Yes. The editor highlights conflicting sections with buttons to keep ours, theirs or both, and Source Control lists conflicted files. You then mark the file as resolved and commit.

What is an alternative to obsidian-git on mobile?

The README names GitSync, which is available on Android and iOS and is not associated with this plugin. Obsidian Sync and other community plugins are also listed as comparable projects.

Does obsidian-git support SSH?

The README says authentication for HTTPS and SSH may need extra setup, and points to the Authentication Guide. On mobile, SSH is not supported.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

obsidian-git suits desktop Obsidian users who are comfortable with Git and want version history, remote backups and in-editor diffs and conflict resolution. If you mainly use mobile, or do not want to learn commits, branches and remotes, the author recommends a different sync service such as GitSync.

Install options & downloads