# obsidian-git: Git version control inside your Obsidian vault > The obsidian-git plugin puts automatic commit-and-sync, a source control view and a history view inside Obsidian. It is a desktop-first tool, and its own README calls the mobile implementation very unstable. **Vinzent03/obsidian-git** — Integrate Git version control with automatic commit-and-sync and other advanced features in Obsidian.md - Repository: https://github.com/Vinzent03/obsidian-git - Stars: 12,057 · Forks: 644 - Language: TypeScript - License: MIT - Published: 2026-09-21 · Updated: 2026-09-21 · Language: en - Canonical page: https://hysenlabs.com/projects/vinzent03-obsidian-git ## The problem obsidian-git solves for vault owners A vault is a directory of Markdown files, and Obsidian has no built-in version history for it. Obsidian Sync is a paid first-party service, and file-level backups do not give you diffs between two drafts of the same note. obsidian-git is for people who already keep their notes in a Git repository, or who want to, and would rather not leave the editor to run git status, git add and git commit in a terminal. The plugin is a community plugin, MIT licensed, written in TypeScript, and its README describes it as bringing Git integration right into your vault with automatic commit, pull and push. The target user is a desktop Obsidian user with a remote they control. Mobile is explicitly secondary: the README warns that the plugin is highly unstable there and suggests trying other syncing services. ## How the plugin maps Git operations onto Obsidian views The plugin does not reimplement Git on desktop. It drives the Git operations through the plugin runtime and surfaces the results in three views. The Source Control View is a side pane for staging and unstaging individual files, committing, and amending the previous commit on desktop. The History View shows the commit log with message, author, date and changed files, where author and date are disabled by default and can be enabled in settings. The Diff View opens from the source control view or from the Open diff view command and compares versions. On desktop there are also signs in the editor marking added, modified and deleted lines and hunks, with commands to navigate between hunks and stage or reset the hunk under the cursor. The commit action itself is conditional: it commits staged changes when present, and when nothing is staged the Stage all changes when nothing is staged setting decides whether everything is staged and committed or the action stops. That setting is the one worth reading twice, because it changes what the Commit command means. ## Installing obsidian-git and running a first commit-and-sync The plugin installs from Obsidian's community plugin browser; the README points to a separate full documentation site for setup instructions, including mobile, and for authentication. Once enabled, open the command palette and run the initialize command if the vault is not yet a repository. For a vault that already has a remote, the plugin can clone one. The commands below are the ones the README lists by name; run them from the palette, not from a shell. ```bash Initialize a new repo Clone an existing remote repo Edit remotes ``` After a remote exists and authentication is configured, the everyday command is Commit-and-sync. With default settings the README says it commits all changes, pulls, and then pushes. There is also a variant with a specific message, and Commit-and-sync and close, which additionally closes the Obsidian window on desktop. ```bash Commit-and-sync Commit-and-sync with specific message ``` For a first real use, open the Source Control View, stage one file, and commit only that, so you can see the difference between the staged-only path and the all-changes path before you rely on either. The README also documents Open file on GitHub and Open file history on GitHub, which open the current file in a browser and only work on desktop. ## Linux packaging and the Snap and Flatpak caveats The README is unusually direct about Linux packaging, and this is the kind of detail that decides whether the plugin works at all. Snap is not supported because of its sandboxing restrictions. Flatpak is not recommended because it does not have access to all system files, and the README notes that issues remain especially with more advanced setups. The recommended path is AppImage or a full access installation from your system's package manager. This is not a plugin bug to work around; it follows from a plugin that shells out to a Git binary and needs to read and write the vault directory and possibly credential helpers outside it. If your distribution ships Obsidian only as a Snap, the honest answer is that this plugin is the wrong tool until you switch packaging. ## Mobile support is experimental and the README says so On Android and iOS the plugin runs on isomorphic-git, a JavaScript reimplementation of Git, because an Obsidian plugin cannot use a native Git installation on those platforms. The README lists the consequences: no SSH authentication, limited repository size because of memory restrictions, no rebase merge strategy, and no submodule support. It also warns that depending on the device and available free RAM, Obsidian may crash on clone or pull, produce buffer overflow errors, or run indefinitely. The README's own recommendation is not to use the plugin on mobile and to try other syncing services, naming GitSync as an alternative available on both Android and iOS and not associated with this plugin. Treat the mobile build as a way to read and occasionally push small changes, not as your primary sync path. ## Submodules, authentication and other desktop-only features Submodule support for managing multiple repositories is desktop only and opt-in, so a vault that pulls in several repositories will not behave the same way on a phone. Authentication is the other area the README hands off: some Git services need extra setup for HTTPS or SSH, and the README refers to a separate authentication guide rather than covering it inline. That is a real gap for a first-time user, because a failing push with no explanation is the most common way people conclude the plugin is broken. The plugin does not remove the need to understand remotes, branches and credentials; it moves the buttons into Obsidian. Commands such as Create new branch, Delete branch and CAUTION: Delete repository are available, which means the destructive operations are one palette entry away. ## obsidian-git compared with Obsidian Sync and GitSync The comparison that matters is with Obsidian Sync, the first-party paid service. Obsidian Sync handles synchronization as a product feature and requires no Git knowledge, no remote and no credential setup; obsidian-git gives you a Git history you own, with branches, diffs and a remote of your choosing, in exchange for Git literacy and the failure modes that come with it. If you want versioned notes and do not want to think about merge strategies, the plugin is the wrong choice. The second comparison is GitSync, which the README names specifically for mobile users on Android and iOS. The difference is architectural: obsidian-git on mobile is the same plugin running on isomorphic-git with the limitations listed above, while GitSync is a separate project aimed at the mobile case. Neither replaces a backup, since a push to a remote only helps if the remote is correct. ## Maintenance, licence and the cost of keeping it working The repository is not archived and the last push was on 2026-09-19, two days before this writing, with release 2.40.0 published on 2026-09-17. That is a fast release cadence, and it means you should expect to update the plugin rather than install it once. The licence is MIT, which is permissive and places no obligation on you beyond keeping the copyright notice; the practical implication is that you can vendor or modify it, but nothing in the licence obliges anyone to fix your issue. Upgrade cost is mostly configuration drift: settings such as Stage all changes when nothing is staged and the editor signs change behaviour when they change, and the mobile implementation can regress independently of desktop. The repository includes a tests directory, vitest configuration and a pnpm workspace, so building from source requires Node 24 or later and pnpm 11 or later per the package.json engines field. Most users should install the published release instead. ## Conclusion Adopt obsidian-git if you keep your vault on desktop and already understand Git remotes and authentication, because the plugin exposes real staging, diff and history rather than a black-box sync. Skip it if your primary device is a phone or tablet: the README calls the mobile implementation highly unstable, points to GitSync instead, and lists no SSH authentication, no rebase merge strategy and no submodule support there. Before trusting it with a live vault, verify three things: that Obsidian is installed as AppImage or via your package manager rather than Snap or Flatpak on Linux, that your remote authenticates over HTTPS or SSH, and that a manual commit-and-sync produces the commit you expect on the remote. ## FAQ ### What is obsidian-git? It is a community plugin for Obsidian that integrates Git version control into a vault, with automatic commit-and-sync, auto-pull on startup, and source control, history and diff views. It is MIT licensed and written in TypeScript. ### How do I install the obsidian-git plugin? It installs as a community plugin in Obsidian. The README points to a separate full documentation site for setup instructions, including mobile, and for authentication. ### How do I use obsidian-git on mobile? The plugin runs on mobile through isomorphic-git, but the README calls it highly unstable, warns about crashes on clone or pull and buffer overflow errors, and recommends other syncing services instead. ### How do I set up obsidian-git sync? Initialize or clone a repository, configure a remote and authentication, then use Commit-and-sync, which by default commits all changes, pulls and pushes. Auto-pull on Obsidian startup is a separate feature. ### Is obsidian-git safe? The plugin exposes destructive commands such as Discard all changes and CAUTION: Delete repository, and its safety depends on your remote and credentials rather than on the plugin. The README does not document rollback for those actions. ### How do I set up obsidian-git on Android? The README does not give a separate Android walkthrough beyond the general mobile caveats: the plugin runs on isomorphic-git with no SSH authentication, limited repository size, no rebase merge strategy and no submodule support. ## Sources - [Issues](https://github.com/Vinzent03/obsidian-git/issues) - [License: MIT](https://github.com/Vinzent03/obsidian-git/blob/master/LICENSE) - [README](https://github.com/Vinzent03/obsidian-git/blob/master/README.md) - [Releases](https://github.com/Vinzent03/obsidian-git/releases) - [Vinzent03/obsidian-git on GitHub](https://github.com/Vinzent03/obsidian-git) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/vinzent03-obsidian-git