Obsidian Git

The Obsidian Git Plugin provides Git integration directly within Obsidian.md, allowing users to manage their vaults using version control.

Core capabilities include:

• Automated Syncing: Scheduled automatic commits, pulls, and pushes, as well as auto-pulling on Obsidian startup.
• Visual Git Tools: Dedicated views for Source Control (staging/committing), History (commit logs), and Diff (comparing file versions).
• Editor Integration (Desktop Only): Line-level signs in the editor to indicate added, modified, or deleted lines/hunks.
• Repository Management: Support for submodules (desktop only), branch management, and remote configuration.
• GitHub Integration (Desktop Only): Ability to open current files or their history directly in a web browser on GitHub.

The mobile implementation uses isomorphic-git (a JavaScript re-implementation) because native Git is unavailable on Android/iOS. This leads to several critical limitations and stability concerns:

Critical Warnings:

• The implementation is very unstable.
• Depending on device RAM, Obsidian may crash during clone/pull, encounter buffer overflows, or run indefinitely.

Technical Restrictions:

• No SSH support: You must use HTTPS with a Personal Access Token.
• Memory limits: Repository size is limited by device memory.
• No Rebase: The rebase merge strategy is not supported.
• No Submodules: Git submodules are not supported.

Recommended Alternatives:

• GitSync: Available for Android and iOS.
• Working Copy: Recommended for iOS users.

Control how the plugin tracks line history when text is moved.

Follow lines (Cut/Copy/Paste): By default, each line shows the last commit where it was changed. If you cut and paste a line, it shows the commit associated with the new location.

• You can change this behavior via configuration to 'all commits', which allows the plugin to follow the original authorship even after lines are moved around.

When syncing a vault with iCloud on desktop, the entire .git directory is synced to mobile devices, which can significantly slow down Obsidian startup times.

To mitigate this, use one of these two patterns:

1. Parent Directory Pattern: Place the Git repository one level above your Obsidian vault, making the vault a subdirectory of the Git repo.
2. Git File Pattern: Move the .git directory to a different location and create a .git file inside your vault containing only: gitdir: <path-to-your-actual-git-directory>

To use the Obsidian Git plugin effectively, understand the following core concepts:

• Git: A version control system that tracks changes to your notes. It manages a local repository where you batch changes into commits. These commits can be reverted or checked out later.
• Syncing: The process of pulling (bringing changes from a remote repository like GitHub to your local vault) and pushing (sending your local commits to the remote repository). This keeps your local and remote repositories consistent.
• Commit-and-sync: A workflow that combines multiple steps into one: staging everything $\rightarrow$ committing $\rightarrow$ pulling $\rightarrow$ pushing.

Note: Git is designed for asynchronous collaboration and version tracking, not for live, real-time collaborative editing of the same note.

If the plugin clone fails due to memory/stability issues on iOS, use the Working Copy app to perform the initial clone:

1. Ensure all changes are pushed/reconciled on other devices.
2. Create a new vault in Obsidian (do NOT use iCloud on iOS).
3. In Working Copy, clone the repo using the direct URL (not the GitHub web URL). Use your username and Personal Access Token for authentication.
4. Open the iOS Files app.
5. Copy the repository from Working Copy and paste it into the directory where your Obsidian vault is located.
6. Open Obsidian. The files should be visible.
7. Install and enable the Git plugin.
8. In the plugin settings under "Authentication/Commit Author", add your name and email.
9. Use the command palette to run the Pull command to sync.

Line author information (based on git blame) provides metadata in the editor gutter about who last changed a line and when.

Constraints:

• Works only in Live-Preview and Source mode (not in Reading mode).
• Supported on Obsidian Desktop only.

How to activate:

1. Use the plugin settings UI.
2. Or, use the Command Palette: Git: Toggle line author information.

Git Installation

Follow the Official Git documentation to install Git on your Mac.

Configure macOS Keychain

To use the macOS keychain for storing your Git credentials, run the following command in your terminal:

git config --global credential.helper osxkeychain

Important: After setting the helper, you must complete a single authenticated action (such as a clone, pull, or push) via the terminal. Once that action is successful, you can sync Obsidian without further authentication prompts.

The Source Control View provides a visual interface similar to git status. You can access it by running the Open source control view command.

Key capabilities include:

• Staging: Stage or unstage individual files, or stage/unstage all files at once.
• Discarding: Discard all changes made to a specific file.
• Diffing: Open a diff view to inspect changes in modified files.
• Syncing: Perform Push, Pull, Commit, or Commit-and-sync operations.
• View Modes: Toggle between a list view and a tree view using the button at the top of the view.

When installing on Linux, avoid certain package formats due to sandboxing and file access restrictions:

• Do NOT use Snap: Sandboxing restrictions prevent proper Git operation.
• Avoid Flatpak: While improving, it still faces issues accessing system files required for advanced setups.
• Recommended: Use AppImage or install via your system's native package manager for full access.

Installing GitHub Desktop is insufficient for this plugin. You must install regular Git.

Requirements:

• Git version 2.29 or higher.
• Install via the official website using default settings.
• Ensure 3rd-party software access is enabled during installation.
• Git Credential Manager must be enabled. You can verify this by running the following command in your terminal; it should output manager.

git config credential.helper