Sync Obsidian with GitHub on iOS

Tip

Open this guide on your iOS device and another screen for a better experience

There are some apps on iOS that allow us to have a Git repo on the device. However, most of those apps are not free or have limited functionality. At the end of this guide, you will learn how to sync your Obsidian vault with GitHub on your device for free.

1. Prepare your repo

It's fine if your repo is new, or if it already has the .obsidian directory with some files. Just add these lines to the .gitignore file:

.obsidian/community-plugins.json
.obsidian/workspace.json
.obsidian/workspace-mobile.json
.obsidian/plugins/*/main.js
.obsidian/plugins/*/manifest.json
.obsidian/plugins/*/styles.css
.obsidian/themes/*/manifest.json
.obsidian/themes/*/theme.css
.trash
.DS_Store

2. Install the Obsidian app

Note

For the sake of this guide, the name of the vault is my-vault.

1. Download Obsidian from the App Store.
2. Open Obsidian app, tap on "Create a vault" -> "Continue without sync", and give any name to your vault.ℹ️ This automatically creates a new directory with the name of your vault and a sub-directory: .obsidian.

3. Set up Git and Obsidian

1. Download iSH Shell from the App Store.

2. Open iSH Shell app and install Git by running the following command:

   apk add git
   

3. Make a new directory (The name can be different from your vault)

   mkdir my-vault
   

4. Change the current directory to the one you just created

   cd my-vault
   

5. Connect the Obsidian vault with your repository. This command will open Finder to select a directory. ⚠️ The two . . are important.

   mount -t ios-unsafe . . 
   

6. In the Locations section, select On my iPhone/iPad then the Obsidian directory, and finally my-vault. ⚠️ Before tapping on Open at the top right, be sure you see “Folder is Empty”

7. Remove the .obsidian directory.

   rm -r .obsidian
   

8. Generate an access token. (See GitHub access tokens on a new tab for more details)

9. Clone your repository in the current directory. Replace <token> with the GitHub token you generated. ⚠️ Don't forget to add the . at the end.

   git clone https://<token>@github.com/<username>/<repo>.git .
   

10. Mark the repo as safe. Be sure to use the absolute path

    git config --global --add safe.directory /root/my-vault
    

11. Set your name

    git config user.name "Your Name"
    

12. Set your email

    git config user.email "your_email@example.com"
    

4. Install the Obsidian Git plugin

1. Open Obsidian app, go to the Settings by tapping on the top left button to show the left sidebar, and then tap on the gear ⚙️.
2. Enable the community plugins by tapping "Community plugins" in the settings, and then on "Turn on community plugins" button.
3. Look for the Git plugin by Vinzent, by tapping on Browse, and then typing "Git" on the Search community plugins... text box.
4. Tap Install, and then Enable.

5. Testing your vault with Git

Create a note on your device, then

If your device is an iPhone

1. Open the Obsidian menu by hiding the keyboard and then tap on the the button with three lines at the bottom right.
2. Tap on Open Git Source control to see the modified files.
3. Click on the arrow-up button to commit and sync your changes.

If your device is an iPad

TODO

If you see your file created from your device on your repo, congratulations, now your vault is synced with Git on your iOS device. For more details about how to use the Git plugin, check the Git plugin documentation

Troubleshooting

Git commands stuck forever on iSH

Restart iSH, then reconnect the Obsidian vault directory again with your Git directory again:

mount -t ios-unsafe . . 

Unfortunately this works only during the current terminal session. I wish I can find a better solution for this issue.

Cannot move or delete my repo ("Resource busy")

If you see "Resource busy" while you are moving or deleting your git repo, probably your repo is still connected with your Obsidian vault. You need to disconnect them first, and then try again

umount my-vault

References

• Syncing Obsidian across Multiple Devices Using Git and/or Syncthing for Free | Dev Avatar
• Sync your notes across devices - Obsidian Help
• Git plugin documentation - Obsidian Publish
• Git Commands Stuck Forever (Solution) | GitHub