A Git-Powered Obsidian Sync Setup with Termux on Android
I am currently working on a mission to treat my phone as a primary computing device powered by a terminal environment - a concept I like to call the Mobputer.
To make this setup viable for serious writing, my notes must be more than disconnected text files stranded on a mobile device. They need to live in a robust system that syncs flawlessly across different environments.
I built a reliable setup relying on a GitHub repository, Termux (as the terminal environment on Android), Obsidian (using Obsidian Sync or SyncThing for cross-device syncing), and the Obsidian Git plugin to handle version control directly inside the editor.
Here is how I bridged my desktop vault to my phone.
Preparing the Environment
The first step is structural: you must separate your personal app configuration from your actual note content. This ensures the writing environment remains consistent everywhere without causing sync conflicts.
1. Ignore Desktop Configurations
On your desktop setup, prevent Obsidian’s internal configuration files from leaking into version control. You can do this by ignoring the .obsidian folder.
echo ".obsidian" >> .gitignore
This command appends the .obsidian directory to your Git ignore list. Why is this important?
- It holds UI preferences.
- It stores desktop-specific plugin states.
- It retains workspace layouts. Syncing these between vastly different devices (like a PC and a phone) creates immediate conflicts.
2. Handle File Synchronization
Next, I handled the actual file synchronization. I opened my GitHub repository as an Obsidian vault and created a new remote vault in Obsidian Sync.
While I chose to use end-to-end encryption, the most important part of this step is ensuring you include all file types and plugins in your sync settings. This allows the mobile environment to mirror the core desktop setup without requiring manual reconstruction.
Setting up Termux on Android
On the Android side, I needed to prepare Termux to make the system portable.
1. Initialize Storage and Install Git
First, grant Termux access to your internal storage and install the necessary utilities.
termux-setup-storage
This prompts Android to grant Termux access to the shared internal storage.
pkg install git termux-exec -y
This installs Git and termux-exec, which ensures commands execute correctly within the Android environment.
2. Configure Git Credentials
I configured Git to avoid annoying authentication prompts during my daily workflow.
git config --global credential.helper store
This tells Git to save your authentication credentials locally. Since a modern smartphone is typically already encrypted and physically secured via biometrics or a PIN, this safely eliminates the need to type a GitHub Personal Access Token (PAT) on every single sync.
Connecting Mobile to the System
The next challenge was connecting the two existing environments: Obsidian on my phone and my remote Git repository.
The goal was to make them recognize each other without breaking Obsidian's internal file management. Standard syncing brings the markdown files over, but Git tracking requires the hidden .git folder, which standard sync services often mishandle or ignore completely.
1. Clone the Repo for Metadata
Inside Obsidian on mobile, I connected to my remote vault and pointed it to a specific folder inside my internal storage (e.g., /Documents/XYZ).
To establish Git history on the device, I opened Termux and cloned the repository into a temporary location. This step exists solely to retrieve the .git folder.
cd /storage/shared/Documents/
git clone https://github.com/user/xyz.git
This navigates to the shared Android documents folder and downloads a fresh copy of the remote repository into a temporary directory.
2. Inject Git Metadata into the Vault
Once cloned, extract the Git metadata and inject it into your live, synced vault directory.
cp -r xyz/.git ./XYZ/
cp xyz/.gitignore ./XYZ/
These commands securely copy the hidden version control folder and the ignore rules from the temporary clone into the live Obsidian vault (XYZ). You can delete the temporary clone afterward.
3. Verify and Fix Ownership Issues
Next, verify the connection by running a pull inside the live vault.
cd ./XYZ
git pull
Because of how Android file system ownership models work, Git will sometimes trigger security warnings, refusing to trust the directory. To fix this, explicitly mark the directory as safe:
git config --global --add safe.directory /storage/shared/Documents/XYZ
Note: Authentication relies on a GitHub Personal Access Token (Classic) instead of an account password.
4. Clean the Working Tree
Finally, ensure the repository state is clean. Sometimes Git on Termux hasn't fully indexed the synced files, incorrectly flagging them as deleted.
git status
git restore .
git status
Running restore . forces Git to align its index with the actual files sitting in the directory. The final status check confirms the working tree is clean. Git will now operate quietly in the background, tracking everything.
How I Use It Daily
Once the infrastructure is set up, it requires almost zero maintenance.
Inside Obsidian on my phone, the Obsidian Git plugin is the only interface I touch. I set it up once with my GitHub identity and token and it tracks my writing automatically.
I just open a new note and start writing. Everything syncs in the background seamlessly. A quick status check through Termux or the Obsidian Git command palette confirms that everything is tracked properly.
Once the first commit and push succeed, my notes are versioned, portable, and completely recoverable. This infrastructure layer allows my writing to exist independently of any single app or device.
Obsidian acts as the beautiful editor, Git preserves the indestructible history and mobile access via Termux turns the entire setup into a computing system I carry in my pocket everywhere I go.