Obsidian on iPad syncing via iSH, git, and GitHub

2022.01-D.Quah-Obsidian-iPad-syncing-via-iSH-git.md

Obsidian iPad syncing via iSH git

by Danny Quah, Jan 2022

This gist describes using Obsidian on iPad while syncing to other Obsidian platforms. The procedure uses git in iSH on iOS, and thus differs from using either Obsidian Sync or Working Copy as described in Obsidian/iOS+app.

(To be clear, Obsidian is one of my favourite Apps, and I'm all for supporting the team financially. Moreover, everything I've heard suggests the paid Obsidian Sync is excellent. However, I don't want my syncing processes to proliferate --- each service using a different client sync flow --- so I keep my systems minimal: just syncthing and git. After writing this I found an Obsidian Forum writeup which uses the same tools I do to achieve the same goal, but you'll want to read that with its accumulated contributions dispersed across the comments. So at least I was thinking about all this right :). Here, I just provide a linear, consistent run-through.)

I couldn't just begin using Obsidian on iPad directly as its instructions suggest, because I already have an Obsidian vault on my desktop. How do I bring that information over? iPad Obsidian does not let you open a folder on the iPad filesystem as a vault. And even if it did, how do you get your files into iPad's filesystem? Instead, iPad Obsidian opens up to give you only the option to create a new vault or to set up syncing through Obsidian Sync or Working Copy.

On desktop and Android, however, Obsidian is perfectly content letting you "Open folder as vault" acknowledging you likely already have existing folders of Markdown files. I wanted the same experience. True, iOS is relatively more closed than other platforms, but Obsidian elsewhere only needs a filesystem, folders, and Markdown files; nothing extra. On other platforms if I need to pop out and edit my Markdown files using something like gvim, I do so and come back into Obsidian again seamlessly, with all the changes I made reflected in my Obsidian interface. Surely iPad Obsidian must be able to leverage exactly the same structure that its same underlying code already uses elsewhere else.

It turns out this is possible. I do this using on the iPad a Linux command-line environment iSH and code-management system git; and on the desktop, related tools I already use there.

By "desktop" here I mean interchangeably your notebook, your desktop, your Android, ... basically every platform where Obsidian lives for you and on which you can run git, but that is not your iPad.

iPad preparation

I'm going to describe how I got my Obsidian vault on my desktop into iPad Obsidian to use. If you need to do this in the opposite direction, the steps I describe will of course need be adjusted appropriately.

Initialize iPad for Obsidian use:

• (If needed) Install iSH on iPad.
• (If needed) Install git in iSH.
• (If needed) Install doas in iSH.

Because git will need to write into folders and files that are owned by the Obsidian process, not just your iSH login, you will need to invoke git everytime either as root or using doas.

Initialize iOS Obsidian vault and iSH git repo

1. (If needed) On github.com create myWp repo, and git push desktop's already-extant Obsidian vault folder up to it.
2. iPad>Obsidian > Create new vault Wp; exit Obsidian
3. iPad>iSH:
   a. If needed, make mountpoint mkdir -p /mnt/dq/Obsidian (I make all my mountpoints contain my user login name dq, but it's unnecessary and you'll obviously want to adjust this for yourself. I just like things to look clean.)
   b. mount -t ios null /mnt/dq/Obsidian (File picker appears, select Obsidian to associate with this mountpoint.). Mounting Obsidian rather than a specific vault means this method will work with multiple vaults. Subsequently just cd to the appropriate folder when in iSH.
   c. Either as root or using doas (obviously replace the GitHub URL with your own):

cd /mnt/dq/Obsidian/Wp
git init
git remote add origin https://github.com/me/myWp.git
# Some users might have to do a "git add" and "git commit" before
# a local branch is available to rename. I didn't, so...
git branch -M main
git pull --rebase origin main # This might take a while
git push -u origin main

Open iPad>Obsidian and check that the contents of myWp are now available on the iPad's Obsidian vault Wp.

The sequence of steps 1.-3. above means three items are now in sync: (1) Obsidian vault folder on desktop; (2) Obsidian vault Wp folder on your iPad; (3) GitHub repo myWp containing the contents of your Obsidian vault folder.

Normal work cycle

Whenever you want to work on iPad>Obsidian:

1. Go to iPad>iSH; (if needed) mount -t ios null /mnt/dq/Obsidian; cd /mnt/dq/Obsidian/Wp; git pull.
2. Work away on iPad>Obsidian.
3. When done, go to iSH; (if needed) mount -t ios null /mnt/dq/Obsidian (choose Obsidian); cd /mnt/dq/Obsidian/Wp (or the appropriate other Obsidian vault sub-folder); git add .; git commit -m "Message"; git push.
4. (Optional) If I'm putting iPad aside for a while, I like to umount /mnt/dq/Obsidian, but that's up to you.

Whenever you want to work on desktop>Obsidian:

1. In a shell go to your Obsidian vault folder, and git pull.
2. Work away on desktop>Obsidian.
3. When done, in a shell go again to your Obsidian vault folder, and git push.

Additional notes

1. The .gitignore in my Obsidian vault folders contain at least the line .obsidian. This folder can always be created as needed from the Obsidian app based on the data I provide in the vault, and I prefer each platform to have its own Obsidian customization. Moreover, the data I want to share are data I create myself, not information and cache that an app puts together, relatively invisibly, from my data and actions, and that might be finetuned to a specific filesystem and directory structure. So, yeah, .obsidian is in my .gitignore.
2. An alternative to using iSH, mount -t ios, and git is to use the (for these purposes) workalikes a-Shell, pickFolder, and lg2. These latter are all fast and good. Personally, however, I like having a full-blown linux distro on my iPad so I would choose iSH in any case. But, on the other hand, git on iSH continues to face issues of sporadic hanging on commit and pull (e.g. ish-943, ish-1640) so having lg2 around or even as the main git-work client can be useful.
3. It would be excellent if iPad>Obsidian could just use any folder available in iPad's Files App. Right now, it can only pick up vaults created from within it in the first place. That is why I had first to create the empty vault before mounting Obsidian from iSH. The way things are now iPad's Files app can see my entire iSH filesystem. If Obsidian could too, I can then skip the mount and umount steps.