Obsidian+Github instead of Notion: synchronization, backup, and versioning (3-in-1)

Personal notes infrastructure (Obsidian + GitHub)

How to set up transparent synchronization of Obsidian notes between devices (Desktop, Android, iOS) via GitHub:

• Without third-party applications (like iCloud, SyncThing, Termux, etc.)

• For free

• As a bonus—a backup: of both the notes themselves and their change history.

The result is a full-fledged replacement for Notion: structured notes with automatic synchronization between devices.

Quick Solution

• A private GitHub repository,

• Synchronization via https + "Personal access token"

• For desktop: Git plugin

• For mobile: Fit plugin

• Auto-sync: on startup (Git), once a minute, without notifications.

• exclude the .obsidian folder via .gitignore

Next: in detail ("for dummies")

Background: Notion is done

Currently, Notion in Russia only works for free accounts and only through a proxy/VPN. Paid accounts have been banned. If you log in from a free account and forget to enable the proxy, you'll be kicked out of Notion, which is inconvenient.

But the main inconvenience is that Notion owns my notes and can delete them at any moment. With Obsidian, it's different: all notes are in a local folder with text files (which can be opened by many applications).

The only question is transparent synchronization... and it's solved in this article.

Background: personal experience

A few years ago, I got excited about the idea of creating a personal "zettelkasten" card index. This methodology didn't stick with me, but as a result, I discovered the Obsidian app, started taking my notes there, and a year ago, I completely switched to it from Notion.

My main argument is that I own my notes, not a corporation. The notes are stored in a folder with text files. They won't disappear if someone decides so.

There have been articles about Obsidian on Habr, for example:

• Notion is dead, long live Obsidian

• Obsidian — A free person's Notion

But for me, Obsidian was not a replacement for Notion, until I learned how to synchronize it across all devices without third-party workarounds or programs.

Below is a step-by-step algorithm that is guaranteed to work.

Step 0: Install Obsidian on all your devices

In case you don't have it yet, here's the link:

• https://obsidian.md/download

Step 1: Create a private Github repository

1. Log in to github

2. At the link https://github.com/new specify:

   • repository name

   • select: private

   • select: README file (since the repository cannot be empty)

3. create repository (green button at the bottom)

4. in the repository root, create a file .gitignore with the text .obsidian

New repository settings on GitHub

Creating .gitignore (1/2)

Creating .gitignore (2/2)

Comment: the file .gitignore is needed to avoid synchronizing the folder .obsidian, which contains local settings (they conflict on different devices during synchronization). If you don't do this, the whole setup will stop working.

Step 2: Create an access token

1. At the link https://github.com/settings/tokens/new specify:

   • token name

   • select: No Expiration (means the token won't expire)

   • select repo

2. create token (green button)

3. save the created token

   • GitHub will show a token like ghp_1wKdGc4IhVCHxXEaKClMNp1rEMwsHu1f5zNZ only once; you need to copy and save it. If you lose it, you'll have to create a new one.

Settings for a "simple" access token

Only for the "paranoid"

The created token gives access to all personal "repositories" on GitHub. If you already have repositories on GitHub and you're *uncomfortable* with such a token, there are two solutions:

1. Create an "advanced" token:

   • grant the token permissions for a specific repository "Repository permissions - Contents: Read and Write"

   • set the token's expiration to 1 year (this is the maximum; you'll have to renew it in a year, which is inconvenient)

2. A simpler option: create a separate GitHub account for Obsidian and use a "classic" token.

Step 3: Synchronization with a desktop (Windows, Linux, Mac)

I'll provide an example for Windows.

3a: clone the repository

1. Make sure git is installed on your system

   • In the console, type git --version and see the version.

   • If an error appears:

     • Install git: https://git-scm.com/downloads

     • Perform initial setup of git: in the command line, specify your "email" and "name" (any), which will be used to sign your files in git (you have a private repository, so no one will see them)

       git config --global user.email МОЙ-EMAIL
       git config --global user.name МОЁ-ИМЯ
       

       Git performs all operations "on behalf of" the user defined by these two commands. Until it has this data, git's functionality is unavailable.

2. Create a folder where Obsidian "Vaults" will be stored (a Vault is an analogue of a Workspace in Notion). For example: C:/OBSIDIAN (win) or ~/OBSIDIAN(linux).

3. Assemble the https link that GitHub will use for synchronization

   • Link format: https://<PERSONAL_ACCESS_TOKEN>@github.com/<USERNAME>/<REPO>.git,

   • For example: https://[e-mail]/myaccount/my-obsidian-vault.git

4. Launch the console (cmd.exe in Windows)

   • in the console, navigate to the OBSIDIAN folder (cd /OBSIDIAN) and from there, execute the command with the assembled link git clone https://<PERSONAL_ACCESS_TOKEN>@github.com/<USERNAME>/<REPO>.git

As a result, a folder OBSIDIAN/my-obsidian-vault will appear, containing files from GitHub (README.md and .gitignore, as well as a folder .git with GitHub settings)

3b: create a Vault in Obsidian based on the downloaded folder

Creating a new Vault in Obsidian

1. From the Obsidian application: open the synchronized folder my-obsidian-vault as a vault

2. Now you can fill the "vault" with notes and files, or just edit README.md

If you already have notes in Obsidian, the algorithm is the same:

• first, create and synchronize an empty repository with GitHub

• then copy all the files from the old vault there

3c: Set up synchronization via the 'Git' Obsidian plugin

Git plugin in Obsidian (1/4) - search and installation

UPDATE: in new versions of the Obsidian-git plugin, the term "Backup" (in the screenshots below) has been replaced with the term "Commit-and-sync"

1. In Obsidian's settings, under "Community plugins", find and install the 'git' plugin

2. Next, in the settings of the git plugin itself, set:

   • Vault Backup Interval (minutes): 1

   • Auto Backup after stopping file edits: ON
     

3. Pull updates on startup: ON

4. Disable notifications: ON (you can leave it off, but then notifications will appear every minute)

Git plugin in Obsidian (2/4) - settings

Git plugin in Obsidian (3/4) - settings

Git plugin in Obsidian (4/4) - settings

Now all notes from this vault will be uploaded to GitHub every minute after you finish editing. Also, when you launch Obsidian, the latest version of the notes will be immediately downloaded from GitHub.

If you don't want to wait a minute, you can force-upload changes to GitHub using the Obsidian command "Git: Create backup": CTRL+P, git b. You can also (in Obsidian's settings) create a hotkey for this command (for example, ALT+S)

Step 4: Synchronization with a mobile device (Android, iOS)

Here, everything is simpler than on desktop:

Search for and install the Fit plugin on mobile

1. Open the Obsidian app

2. Create a new empty Vault (do not create any files in it)

3. Inside Obsidian, find and install the community plugin "Fit"

4. In the plugin settings:

   • paste the Token (from step 1). The token itself, not the URL.

   • authorize by clicking the "Authenticate user"

   • Github repository name: select from the list, for example: my-obsidian-vault

   • Branch name: select main. (no other options here)

   • Auto sync: select Muted

   • Auto check interval: set to 1 minute

   • File change: click so the button is not active (and doesn't spam every minute).

That's it, the mobile app setup is complete: Obsidian will sync with GitHub every minute.

Drawbacks of Fit plugin version v1.1.1

The cat button for forced synchronization via the Fit plugin

Unfortunately, the Fit plugin (still) doesn't support auto-sync "on startup".

Therefore, right after launching, to avoid waiting a minute, you can pull changes using the "Fit Sync" cat button.

Also, the current version of the plugin has one "bug": if you delete an unnecessary folder with files on the desktop (and sync the repository), the files will be deleted on mobile, but the empty folder will remain... and you'll have to delete it manually. It's inconvenient, but this scenario is quite rare. Plus, there's a chance the plugin author will fix this bug.

However, the plugin has an undeniable advantage: it works on mobile.

Step 5: safety precautions

Do not edit the same file on two devices simultaneously.

However, this advice also applies to Notion: I once lost parts of texts in Notion when a note was open in multiple places.

In reality, following this advice is easy.

And if something goes wrong, Obsidian will report a version conflict, and you'll have to deal with it (whereas Notion will silently resolve it somehow on its own).

• On desktop, version conflicts are resolved using GIT tools.

  • In short: you just need to edit the "conflicting" file and remove unnecessary lines (including service lines) to get everything back to normal.

  • and if different lines of a note were edited simultaneously, the smart git will resolve everything itself (correctly, seamlessly, automatically).

• On mobile, the conflict is resolved differently: the local file doesn't change, but its "external" copy appears in the folder _FIT. You need to look at it and decide what to keep and what to change in the original file.

Once again: a note version conflict is a force majeure, you will most likely never encounter it (if you don't edit the same note on two devices simultaneously). And if you do, it's easy to resolve.

Questions and Answers:

Why is the Fit plugin used on mobile instead of the full Git?

Mobile apps cannot call other mobile apps, so the Obsidian plugin cannot call a third-party Git app on mobile.

Obsidian plugins are written in JS. The mobile obsidian-git plugin has a JS implementation of a full git... but it's still raw (it's slow with a large number of files and spams alerts).

Therefore, for mobile devices, you have to use the Fit plugin, which uses a simplified GitHub API, instead of the full Git.

Why is the Git plugin used on desktop instead of the simpler Fit?

There are two reasons for this:

• storing the entire change history on the local machine (in the .git folder)

• the convenience of automatically resolving version conflicts if different lines of the same file were edited simultaneously on different devices.

Can I use only the mobile version (without a desktop)?

Yes, absolutely. You can skip Step 3 - everything will still work.

True, the desktop version provides an additional backup with change history (stored on the desktop), but if you forgo the desktop, the system will continue to work.

You can also forgo the mobile version and work only on the desktop (but why? :))

Why not synchronize everything through third-party applications (like SyncThing)?

• they require attention (you need to make sure nothing has broken)

• they drain the battery (on mobile)

• they use more data (on mobile)

• synchronization through them takes a little longer

• they don't store the history of all changes (as git does in the local folder .git and on GitHub)

• most importantly—they allow for an unsafe scenario: accidentally delete on one device—it syncs/deletes everywhere immediately. To avoid this, you need to set up an additional backup somewhere.

Here, everything is in one application: launch Obsidian—syncing starts; close it—it stops.

Where can I see the file change history?

File change history on GitHub

If you're not strong with git (like me), you can view the change history of any file on the GitHub website (for each file, there is a "🕓History" button in the top right).

What if GitHub stops being accessible from Russia one day?

Indeed, the Fit plugin is tightly coupled to the GitHub API.

But it's like in that parable - "either the donkey will die, or the shah will...".

• Most likely, by that time, the mobile Obsidian-Git plugin will be finalized. And then it will be possible to use any git server (even your own).

• Or they will finalize the Fit plugin (or create a new one) to work with some open-source service.

• or do it the old-fashioned way:

  • Android: synchronize via the external application "Termux", inside which you can install a full-fledged git (instructions can be googled)

  • iOS: synchronize via iCloud

• finally, Obsidian has its own synchronization service for $4 a month. However, it would be good to add an additional backup to it.

In January, I already predicted a YouTube slowdown. So I'll be a predictor once more. So: GitHub will remain accessible in the coming years (well, what if :))

What else can be done with this setup?

• In Obsidian, you can use multiple Vaults (analogous to Workspaces in Notion), and create a separate GitHub repository for each. However, you'll have to configure synchronization separately for each one: in Obsidian, plugins are installed inside a Vault, not in the application globally.

• If you have your own server, you can set up another backup: scheduled backup of the GitHub repository via git.

A moment of common sense

As a psychologist by my main profession, I dare to assert that the ability to own (to possess, to manage, to be the master) is one of the basic qualities necessary for a good life.

What does Obsidian have to do with this?

The thing is, a person can only realize themselves (according to their values) from a state of ownership of their own life (when you feel the right and ability to influence). And the ability to own and influence is always cultivated from small things, including through ownership of the results of one's creativity. Including through ownership of personal documents.

And I view the current situation—where corporations try to manage authors' content and effectively offer them to renounce their right of ownership—as just a temporary imbalance and a "growing pain" of our civilization.

At the same time, I want to separate the concepts of "ownership" and "management": it's very convenient when you can delegate the management of a resource but continue to be the owner. However, in these instructions, these two roles had to be combined: to manage and to own by oneself.

In general, the recognition and realization of the value of "ownership" is a trend. It's still small, but—according to my observations—it's showing steady growth.

So if you decide to reclaim the right to manage your own notes with Obsidian—you know what to do.