Using Git To Sync Obsidian Notes on iOS with a-shell (free)

Chris Woodall | 2022-01-02

Obsidian is a wonderful note-taking too, but until mid-2021 there was no official mobile application. I use git to host my Obsidian vaults, and github to store them and sometimes create websites from them using a GitHub Action, GitHub Pages and Neuron. This is how I host my Generative Art Studio page. However, on iOS there is no native support for using git to sync your notes. You can use iCloud, or Obsidian Sync. I have no issues with paying for either of these services, but I wanted to be able to keep my current workflow, but extend it to mobile.

I developed a free method using a-shell, which can be automated, after initial setup, using iOS Shortcuts. There are two other methods that are well documented on the Obsidian forum:

This method uses a-shell, which uses webAssembly for many of it’s executables, which allows it to be more flexible, this has support for python, lua, javascript, C and C++, and most importantly git, using lg2. The main benefit is it is free (iSH is also free), and it is natively scriptable using Shortcuts (which iSH is not).

So let’s get started.

Install the software

  1. Install Obsidian from the AppStore and launch it.
  2. Install a-shell from the AppStore. We will be using this and a few of it’s built in shortcuts such as pickFolder and the lg2 (which is based on libgit2)

Setup your ssh keys and git configuration:

  1. Launch a-shell.
  2. Mount the Obsidian directory you will be doing your work within. This will be the Obsidian folder : pickFolder
    • WARNING: In the above video I use an iCloud folder. I do not recommend this. After a week of using this on my iPad and iPhone I started running into issues here.
  3. Create an ssh key using ssh-keygen. At this time GitHub no longer supports SHA-1 so we will need to use an ED25519 key.
    ssh-keygen -t ed25519 -C ""
  4. Share the public key with your github or gitlab accounts you need to clone from.
  5. Clone your obsidian vault: lg2 clone ssh:// folder-name This will prompt you for which ssh key you want to use. We will fix that in the next step. You will be prompted to enter your ssh password, if there is none press return.
  6. cd folder-name
  7. Setup user.identityFile and user configurations. This will set the default identity file to use, as well as the name and email address to sign the commits with. These are setup per repository with lg2 as it does not seem to have --global configuration access.
    lg2 config user.identityFile ~/Documents/.ssh/id_ed25519
    lg2 config user.password ""
    lg2 config "Name"
    lg2 config ""
  8. Open up Obsidian, you should see the vault in you list of vaults if you saved it into the correct location.

Setup Shortcuts

Setup shortcuts for pulling (download changes only), and syncing (pulling, committing, and then pushing). Here are the two that I created

Pull Only

lg2 pull


lg2 pull
lg2 add .
lg2 commit -m "update: {{date}}"
lg2 push

So long as you keep a strict discipline of pulling before making changes, and pushing changes from your Linux, Mac and Windows Obsidian instances frequently, this setup is pretty stable. It is a little additional step to manually trigger the sync shortcuts, when compared to a solution like Obsidian Sync, or iCloud which are all passive. If you end up with merge conflicts you will need to manually resolve them using lg2. This can be tricky because it diverges from git sometimes, and I found the documentation sparse.

Here is an example of the shortcuts in action: