# Come Gither Sync your Obsidian vault with a GitHub repository through the GitHub API. Come Gither works on desktop and mobile, including iPad. It does not need git on your device. ## Why Real git implementations struggle on mobile with large repositories. Come Gither talks to the GitHub API instead. It downloads and uploads only the files that changed. The cost of a sync grows with your edits, not with the size of your vault. ## Features - **Two-way sync.** The plugin creates real commits on your repository. Other devices and plain git see normal history. - **Placeholders for large binaries.** Text files and the config folder sync fully, up to the download limit. Binary files (PDFs, images, audio) arrive as empty placeholders. Open one, and the plugin offers to download it. A setting switches between "ask first" and "download immediately". - **Free up space.** The command *Remove local copy (keep on GitHub)* turns a downloaded file back into a placeholder. - **Conflict resolution.** When both sides change a text file, the plugin merges the edits when they do not overlap. When they overlap, it keeps your local file and saves the server version under `_conflicts/` for review. A "remote wins" mode takes the server version instead. The config folder always takes the server version. When an overwrite would replace your changed file with a placeholder, your local copy is saved under `_conflicts/` first. - **Preview before you sync.** The command *Preview sync* lists incoming and outgoing changes. Each outgoing change has a Revert button. - **Safe interruption.** A killed or backgrounded pull resumes where it stopped. An interrupted upload restarts, but nothing appears on GitHub until the final commit lands. - **Log export.** The command *Export sync log* writes the sync log to a note, so you can share it from any device. - **Ribbon menu.** The Come Gither icon in the ribbon opens a menu: *Sync now*, *Preview sync*, *Export sync log*, *Show beta features*, and each beta command when beta features are on. - **Large files through Git LFS.** Files over 100 MB, up to 2 GB, go to GitHub through Git LFS. Raise **Largest upload (MB)** above 100 to push them. An LFS file you edit stays in LFS at any size. LFS files from GitHub arrive as placeholders and download when you open them. A notice shows the progress of each LFS upload and download. The sync commit adds one line per file to `.gitattributes` and never removes lines. LFS files count toward your LFS quota (10 GiB storage and 10 GiB download per month included on Free and Pro). Desktop git needs [git-lfs](https://git-lfs.com) installed to see these files. ## Network use disclosure This plugin sends the contents of your vault to the GitHub API (`api.github.com`) and downloads repository content from it. It collects no telemetry. Sync also contacts GitHub's Git LFS endpoint (`github.com`, `lfs.github.com`) and the storage URLs GitHub returns (currently Amazon S3 hosts run by GitHub) to upload and download Git LFS files. The beta command *Test large file support* contacts the same hosts, only when beta features are on and you start the command. Nothing else talks to any other service. ## Token storage disclosure The plugin needs a GitHub personal access token (fine-grained, Contents read and write, scoped to one repository). The token is stored **in plain text** in the plugin's local settings file (`data.json` in the plugin's folder under your vault's config folder, usually `.obsidian/plugins/come-gither/`) on each device. The plugin never syncs its own folder, so the token never leaves your device. ## Setup 1. Create a fine-grained personal access token with Contents read and write access to your vault repository. 2. [Install the plugin](#install) and open its settings. 3. Enter the repository owner, name, branch, and your token. 4. Run the command **Sync now**. The first sync of a large vault takes a while and is safe to interrupt. Start it when the app can stay in the foreground. ## Settings - **Conflict policy** — merge (default) or remote wins. - **Placeholder downloads** — ask first (default) or download immediately. - **Largest automatic download (MB)** — text files above this size, and all binary files, stay placeholders until you open them. - **Largest upload (MB)** — files above this size are skipped on push. The default is 30. Files over 100 MB go through Git LFS (limit: 2 GB). A large upload can run out of memory on a phone. - **Automatic sync interval (minutes)** — 0 is off; otherwise 3 to 60. - **Pull when Obsidian starts** — on by default. The startup pull never pushes; local edits and deletions wait for a manual or interval sync. - **Deletion guard threshold** — 10 by default. A pull that would delete more files than this on the device, or a push that would delete more than this on GitHub, stops and asks first. Automatic and startup syncs pause instead until you run **Sync now**. 0 turns the guard off. - **Enable beta features** — off by default. Turns on unfinished features. They may change or break. ## Beta features Beta features are unfinished. Each one lists what it does and what it writes. Read the list before you turn on **Enable beta features**. You can see the list in three places: - The plugin's settings page, under the toggle. - The command **Show beta features**. - The ribbon icon menu, item *Show beta features*. While beta features are off, their commands do not show in the command palette or the ribbon menu. ### Test large file support Checks whether this device and your token can send a file to GitHub's large file storage (Git LFS). Git LFS is the route for files over GitHub's 100 MB limit. You pick a vault file (largest first) and confirm. The command hashes the file, asks GitHub for an upload, uploads the file, verifies it, commits a pointer, and reads the start of the file back. It reports each step. What it writes: the chosen file goes to Git LFS in your repository and stays there. It counts toward your LFS storage (10 GiB included on Free and Pro). A pointer commit goes on a temporary branch, `come-gither-lfs-test`, and the command deletes the branch afterwards. Your sync branch does not change. This command also talks to `github.com` and GitHub's LFS storage, not only `api.github.com`. The results show in a window and go to the sync log. If a step fails, run **Export sync log** and share the note. ## Limits - Files over the upload limit (30 MB by default) are skipped with a warning. Files over 100 MB go through Git LFS, up to GitHub's 2 GB LFS limit; desktop git then needs git-lfs installed. - Syncing the config folder includes the code and settings of your other plugins. Anyone with write access to your repository can change what those plugins run. Use a repository only you control. - A conflict whose GitHub version is larger than the download limit is logged, but no copy lands in `_conflicts/`; resolve it with desktop git. - A new empty file is not uploaded until it has content. - A binary embedded in a note renders as broken until you open the file directly once. - Deletions sync both ways. Deleting a downloaded file locally deletes it on GitHub on the next sync. Deleting a placeholder does not; the placeholder returns. A pull or push that would delete more files than the deletion guard threshold asks first. You choose to delete them or keep them. Keep brings the files back: a pull keeps them on this device and adds them back to GitHub on the same sync; a push restores them on this device (large files and binaries as placeholders). An automatic or startup sync never asks: it pauses the sync, deletes nothing, and waits for your next **Sync now**. ## Install Come Gither is in the Obsidian community plugin list. 1. In Obsidian, open **Settings → Community plugins**. 2. Select **Browse**, then search for "Come Gither". 3. Select **Install**, then **Enable**. You can also open the [plugin page](https://obsidian.md/plugins?id=come-gither) and select **Install**. Obsidian updates the plugin like any other community plugin. If you installed an earlier version through BRAT, you can remove the BRAT entry. The community version replaces it. ## License MIT