- Sign in to GitSync.md and set the save location to On My iPhone → Obsidian.
- Clone your vault’s GitHub repository, then fully close and reopen Obsidian.
- Install and enable the Git community plugin in Obsidian.
- Set your GitHub username, commit author name, and commit author email.
- Paste a GitHub Personal Access Token into the plugin’s authentication settings.
- Run Git: Commit-and-sync and verify your test edit on GitHub.
Watch the walkthroughs
The first video shows the clone and vault setup. The follow-up fills in the authentication step: you also need to enter a Personal Access Token in Obsidian Git. Follow both parts below for the complete setup. Earlier videos call the app Sync.md; it’s now named GitSync.md.
Signing in to GitSync.md does not sign the Obsidian Git plugin in to GitHub. Your author name and email identify your commits; the Personal Access Token lets the plugin authenticate when it pulls or pushes. You need to configure both.
How the setup works
On desktop, Obsidian Git can use your installed Git tools. On iPhone, it uses a separate mobile implementation. In this workflow, GitSync.md handles the initial clone: it writes your notes and a real .git directory into Obsidian’s local folder. You then open that working copy in Obsidian and use the Git plugin to pull, commit, and push.
Both apps work with the same files. GitSync.md can also perform Git operations on that repository whenever you want to sync directly in the app.
What you’ll need
- GitSync.md on your iPhone (App Store).
- Obsidian on the same phone (App Store).
- A GitHub repository containing your vault, with your notes at the repository root.
- Access to your GitHub account to create a Personal Access Token.
If your vault is only on your desktop, commit and push it to GitHub first. Push any outstanding desktop edits before cloning it on your phone. This guide uses a local vault under On My iPhone; on iPad, use On My iPad.
Clone and open your vault
Sign in to GitSync.md
Open GitSync.md and tap Sign in with GitHub. Complete the GitHub OAuth sign-in so the app can show your repositories.
Choose Obsidian’s local folder as the save location
When GitSync.md asks for your default save location, open the folder picker and select:
On My iPhone → ObsidianChoose the Obsidian folder itself. GitSync.md will create your repository’s folder inside it. You can change this location later in GitSync.md’s App Settings.
If Obsidian’s folder is missing, open Obsidian and create a local vault with Store in iCloud turned off, then return to the folder picker.
Add and clone your vault repository
In GitSync.md, add a repository and select your vault from the GitHub repository list. Tap Add and Clone Repository, or add it first and then tap Clone Repository, depending on the app version.
Wait for the clone to finish. In the Files app, check that your notes are inside a folder such as:
On My iPhone → Obsidian → MyVaultThe clone includes the .git directory the plugin needs. You don’t need to initialize another repository in Obsidian.
Fully close and reopen Obsidian
Open the iOS app switcher and swipe Obsidian away to close it completely. Reopen Obsidian, choose the cloned vault from the vault list, and tap Open vault.
This refresh matters: in both videos, the newly cloned folder appears after Obsidian restarts. You should now see the notes from your GitHub repository.
Configure Obsidian Git
Install and enable the Git community plugin
In your cloned vault, open Settings → Community plugins. Enable community plugins if prompted, tap Browse, and search for Git. Install the Git plugin by Vinzent, then tap Enable.
If the plugin is already present in your cloned vault, check that it’s enabled on your phone.
Set your username and commit author details
Open the Git plugin’s settings and find Authentication/Commit Author. Fill in these fields:
CodyBontecou.Cody Bontecou.If you’ve tried to sync already, you may have seen “Git author name and email are not set.” These author fields fix that error. Authentication is the next step.
Add your GitHub Personal Access Token
Create a token and paste it into Obsidian Git
The follow-up video demonstrates a classic token. To follow that path:
- Open GitHub’s Personal Access Tokens page in your browser.
- Choose Tokens (classic) → Generate new token → Generate new token (classic).
- Give it a descriptive name, such as Obsidian iPhone, and choose an expiration date.
- Select the repo scope for repository access. Add workflow only if you will change GitHub Actions workflow files. Ordinary note syncing doesn’t require the extra project, user, or repository-deletion scopes selected in the demo.
- Tap Generate token, then copy the token while GitHub displays it.
- Return to Obsidian’s Git settings and paste it into Password/Personal access token under Authentication/Commit Author.
You won’t be able to reveal the saved token again in the plugin’s settings. A hidden value doesn’t mean the field is empty. If you lose the token or it expires, generate a replacement and enter it again.
GitHub recommends fine-grained tokens where possible because you can limit them to specific repositories. If you choose that option, select your vault repository and follow the plugin’s mobile setup permissions. The classic-token steps above match the video. See GitHub’s token documentation for expiration and organization restrictions.
A token grants access to your repositories. Don’t paste it into a note, publish it in a screenshot, or commit it to Git. Before entering the token, check that plugin configuration containing credentials is excluded from version control. The plugin’s .gitignore guide explains how to exclude .obsidian/plugins/. If those files are already tracked, adding an ignore rule alone won’t stop Git tracking them; remove them from tracking first while keeping your local copies. If you expose a token, revoke it on GitHub and create a replacement.
Verify your first commit and push
Make a small edit and run Commit-and-sync
- Create a note named
Hello GitSync.md, or add a short test line to an existing note. - Open Obsidian’s command palette and run Git: Commit-and-sync (search for commit if the wording differs in your plugin version).
- Wait for the operation to finish, then open the same repository and branch on GitHub.
- Check the latest commit and confirm that your new note or edit is there.
- On your desktop, pull the repository and confirm that the edit appears in your vault there too.
This is the verification shown in the videos: an edit made in Obsidian on iPhone appears in a GitHub commit and can be pulled onto another device.
Daily workflow
Pull before you start editing on a device, write your notes, then commit and push before switching to another device. In Obsidian’s command palette, use Git: Pull, Git: Commit-and-sync, or the separate commit and push commands.
You can also open the repository in GitSync.md to pull or commit and push the same files. Wait for an operation to finish before starting another in either app.
Get manual syncing working before adding automation. If you later want GitSync.md to handle sync operations through Shortcuts, follow the Shortcuts automation guide and turn off overlapping plugin timers.
Why this works
GitSync.md uses libgit2 to create a standard Git working copy on your phone. Obsidian edits the Markdown files in that folder, and the Git plugin uses the repository’s history and remote configuration with the credentials you supply in its settings. Your vault stays a folder of files you can also work with on your desktop.
The plugin’s mobile documentation describes memory and feature limitations, including no SSH authentication. This walkthrough uses a GitHub HTTPS remote. If plugin operations fail on a large vault, use GitSync.md to sync that shared folder directly.
Troubleshooting
Obsidian doesn’t show the cloned vault
In Files, check that the repository folder is under On My iPhone → Obsidian. Fully close Obsidian from the app switcher and reopen it. If you cloned elsewhere, save any unpushed edits before cloning a fresh copy into the correct location.
“Git author name and email are not set”
Open the Git plugin’s settings and fill in Author name for commit and Author email for commit. Your GitHub username alone doesn’t fill in those fields.
Pull or push fails even though GitSync.md is signed in
Enter a valid token in the plugin’s Password/Personal access token field. Check its expiration, repository permissions, and your account’s write access. For an organization repository, also check whether the token needs SSO authorization or organization approval. Use an HTTPS remote such as https://github.com/USERNAME/REPO.git.
The token field looks empty after saving
The plugin hides the saved token. Try a pull or your test commit to check authentication. If it fails and you can’t recover the original token, replace it with a newly generated one.
The plugin can’t find a Git repository
Confirm that GitSync.md completed the clone and that you opened the cloned folder as your vault. Creating a new empty vault beside the clone won’t give it the clone’s .git directory.
The plugin crashes or hangs
Use GitSync.md to perform the Git operation on the same local vault. Keep the plugin’s automatic timers off while using GitSync.md for syncing.
Recap
Clone with GitSync.md into Obsidian’s local folder, restart Obsidian, enable the Git plugin, and configure both your commit identity and your GitHub token. Verify a small edit on GitHub before relying on the setup for your daily notes.
Get GitSync.md on the App Store or explore the source on GitHub.
