Sync Local Markdown Notes with a Self-Hosted Git Server on a NAS

Sat, 30 May 2026 16:14:19 +0800

If you already have a local NAS and want to keep your notes as much as possible under your own control, you can put Markdown notes into a Git Server on the NAS and sync them with Android and Windows clients. This setup does not depend on public cloud drives, and it works well with note tools centered on local Markdown files, such as Obsidian, Markor, VS Code, and Typora.

The basic idea is simple:

Create a bare Git repository on the NAS as the central notes repository.
Clone the repository on Windows and write notes with a normal editor.
Clone the same repository on Android and use a Git client to pull and push.
Before switching devices, run pull; after writing, run commit and push.

This is not the most hands-off sync method, but it gives good control and clear version history. Once you build the habit of committing, you can keep notes, configuration, and image attachments on your own NAS for long-term storage.

Who This Setup Is For

This setup is suitable for people who:

Already have a NAS at home or in the office.
Mainly write notes as Markdown files.
Want note data stored inside a local network instead of only on a commercial cloud drive.
Need sync between Windows and Android devices.
Can accept basic Git operations such as clone, pull, commit, and push.

If you want fully automatic and invisible sync, Syncthing, WebDAV, or the built-in sync of a notes app may be easier. Git is better for a notes library where version history, rollback, migration, and control matter.

1. Install Git Server on the NAS

Different NAS systems expose this in different places, but the goal is the same: let the NAS provide a Git repository that can be accessed through SSH.

There are three common approaches:

Method	Suitable Scenario
Install Git Server from the NAS package center	Synology, QNAP, and other consumer NAS systems when you want less setup work
Deploy Gitea with Docker	You want a web UI, account management, and a more complete Git service
Use SSH + a bare repository directly	You only use it yourself and want something simple and stable

For personal note sync, SSH + a bare repository is usually enough. Suppose the NAS has a dedicated Git user named git, and repositories are stored under /volume1/git. On the NAS terminal, run:

1
2
3

mkdir -p /volume1/git/notes.git
cd /volume1/git/notes.git
git init --bare

A bare repository is not edited directly. It only acts as the sync center. The actual note-writing directory lives locally on Windows or Android.

Then confirm that SSH can access the NAS:

`1`	`ssh git@192.168.1.10`

If the NAS supports SSH public-key login, configure keys so you do not need to enter a password every time you push. Windows and Android can each generate their own SSH key, and then you can add the public keys to the NAS authorized_keys file or the Git Server user settings.

2. Windows Setup

On Windows, install Git for Windows first. Then choose a local directory for notes, such as D:\Notes.

Initial clone:

`1`	`git clone git@192.168.1.10:/volume1/git/notes.git D:\Notes`

After entering the directory, you can create a basic structure:

1
2

cd D:\Notes
mkdir inbox, daily, projects, resources

Then open D:\Notes with Obsidian, VS Code, Typora, or another Markdown editor. After writing the first batch of notes, commit them:

1
2
3

git add .
git commit -m "初始化笔记库"
git push origin main

If the default branch is master, replace main with master in the command. You can also standardize it to main:

1
2

git branch -M main
git push -u origin main

For daily use, keep this rhythm on Windows:

git pull --rebase
git add .
git commit -m "更新笔记"
git push

3. Android Setup

On Android, use a client that supports Git to sync the local Markdown directory. Common choices include:

Tool	Usage
Termux	Most flexible, close to a Linux command line
MGit	Graphical Git client, suitable if you do not want to type many commands
GitJournal	More like a notes app, suitable for simple Markdown notes

If you choose Termux, first install Git and OpenSSH:

1
2

pkg update
pkg install git openssh

Generate an SSH key:

`1`	`ssh-keygen -t ed25519 -C "android-notes"`

Add the generated public key to the Git user authorization on the NAS. Then choose a local directory on the phone and clone the repository:

`1`	`git clone git@192.168.1.10:/volume1/git/notes.git ~/notes`

If you want ordinary Android editors to access this directory, you can put the repository in shared storage, for example:

1
2

cd /sdcard
git clone git@192.168.1.10:/volume1/git/notes.git Notes

Then open /sdcard/Notes with Markor, Obsidian Android, or another Markdown editor. After editing on the phone, return to Termux and run:

cd /sdcard/Notes
git pull --rebase
git add .
git commit -m "手机更新笔记"
git push

Permissions and paths are the easiest sources of trouble on Android. Termux’s own home directory is more stable, but some editors may not access it directly. /sdcard is easier for editors to access, but permissions, file watching, and performance may be limited by the system. Test with a small number of notes before deciding on the final directory.

4. How Obsidian and Joplin Fit In

The NAS Git Server only solves where files live and how they sync. You still need to choose a notes app for writing. Here, the setup can be split into an Obsidian path and a Joplin path.

Setup	Sync Method	Best For	Notes
Obsidian + Git	The notes directory is the Git repository, and Windows and Android both pull the same repository	People who want backlinks, knowledge graphs, plugins, and pure Markdown files	On Android, test whether the Git client and Obsidian can access the same directory correctly
Joplin + Git	Do not put the Joplin database directly into Git; use Joplin’s own sync or export Markdown to Git regularly	People who want web clipping, end-to-end encryption, and a traditional notebook structure	Joplin’s local data is not a normal Markdown folder and is not suitable as a direct Git-synced notes library

Obsidian Setup

Obsidian is the best fit for this NAS Git sync setup. Its vault is essentially an ordinary folder containing Markdown files, image attachments, and configuration files. You can directly use D:\Notes or /sdcard/Notes as the Obsidian vault.

Windows workflow:

`1`	`git clone git@192.168.1.10:/volume1/git/notes.git D:\Notes`

Then open D:\Notes in Obsidian.

Android workflow:

1
2

cd /sdcard
git clone git@192.168.1.10:/volume1/git/notes.git Notes

Then open /sdcard/Notes in Obsidian Android.

Suggestions for the Obsidian setup:

For single-user use, you can commit .obsidian/ so themes, plugins, and some settings sync across devices.
If Android and Windows use very different plugins, commit only the note content and exclude device-state files such as .obsidian/workspace.json.
Put image attachments under attachments/ to avoid scattering them across directories.
Before opening Obsidian, run git pull --rebase; after writing, run commit and push.

You can prepare a .gitignore to reduce conflicts caused by device-state files:

1
2
3

.obsidian/workspace.json
.obsidian/workspace-mobile.json
.trash/

Joplin Setup

Joplin works differently from Obsidian. Although it uses Markdown syntax, its local data is mainly managed by the application’s database. It is not a normal Markdown folder that can be synced directly with Git. Therefore, do not put Joplin’s configuration or database directory directly into a Git repository.

If you prefer Joplin, two safer approaches are:

Approach	Description
Use Joplin’s built-in sync	Sync through WebDAV, Nextcloud, Joplin Cloud, Dropbox, OneDrive, and similar options. The NAS can provide WebDAV or Nextcloud
Export Markdown to Git regularly	Use Joplin as the main notes app, regularly export notes as Markdown, and commit them to the NAS Git repository as a backup

If your NAS already has WebDAV or Nextcloud, connecting Joplin directly to the NAS for sync is smoother than Git. It can also enable end-to-end encryption, which is suitable for people who do not want to handle Git conflicts but still want data under their own control.

The recommended Joplin + NAS path is:

Enable WebDAV on the NAS or deploy Nextcloud.
Configure the same sync target on Joplin for Windows.
Configure the same sync target on Joplin for Android.
When versioned backup is needed, export Markdown to the Git repository regularly.

Simple rule of thumb:

Choose Obsidian if you want “local Markdown folder + backlinks + Git history”.
Choose Joplin if you want “traditional notes app + web clipping + encrypted sync”.
If you want the NAS Git Server as the main sync center, Obsidian is more suitable.
If you want the NAS to act as a private cloud sync backend, Joplin is more suitable.

5. Recommended Notes Directory Structure

Do not design the notes library too elaborately at the beginning. Start with a structure like this:

Notes/
  inbox/
  daily/
  projects/
  resources/
  attachments/
  README.md

The meaning is straightforward:

inbox/ stores temporary notes.
daily/ stores journals, logs, and daily records.
projects/ stores project notes.
resources/ stores long-term reference material.
attachments/ stores images, PDFs, and other attachments.

If you use Obsidian, you can use this directory directly as a vault. Whether to commit .obsidian/ depends on personal preference. For single-user multi-device use, committing it is fine. If plugins differ greatly across devices, commit only part of the configuration.

6. Avoiding Sync Conflicts

The key to syncing notes with Git is not complicated commands, but stable habits.

Recommended rules:

Before writing on another device, run git pull --rebase.
After a writing session, run commit and push promptly.
Do not edit the same file on two devices for a long time at the same time.
Do not keep adding unlimited images and large attachments into the Git repository.
Regularly keep another backup of the repository outside the NAS.

If a conflict happens, Git will mark the conflicting files. Markdown text conflicts are usually not hard to resolve, but the experience is worse on a phone, so try to resolve conflicts on Windows.

7. Do You Need Automatic Sync?

You can write a simple Windows script that chains pull, add, commit, and push. But for note sync, fully automatic commits are not recommended, because accidental deletions, empty commits, conflicts, and large attachments may all be pushed automatically.

A safer approach is semi-automatic:

Pull manually before opening notes.
Run a script to commit after writing.
Use a simple commit message that says what changed.

For example, you can prepare a sync-notes.ps1 on Windows:

git pull --rebase
git add .
git commit -m "更新笔记"
git push

If there are no changes, git commit will report nothing to commit. That is not a problem.

8. Pros and Cons of This Setup

Aspect	Description
Pros	Data stays on the local NAS, version history is clear, rollback is possible, migration is easy, and it suits Markdown
Cons	Requires understanding Git, conflicts need manual handling, and the mobile experience is not as smooth as cloud sync
Best for	Technical users, local-first notes, personal knowledge bases, project documentation
Not for	People who do not want to touch a command line, need real-time multi-user collaboration, or frequently sync large attachments

My Recommendation

If you only want to sync ordinary Markdown notes between Android and Windows, start with the smallest setup: one bare repository on the NAS, Git for Windows on Windows, and Termux or MGit on Android. Do not introduce complex permissions, automation scripts, or excessive categorization on day one.

After this workflow runs smoothly, then consider Gitea, automatic backups, per-device SSH key management, a separate attachment repository, scheduled tasks, and other extensions. The most important thing for a notes system is long-term stability, not filling it with every feature on the first day.

In one sentence: a NAS Git Server is suitable for turning Markdown notes into a local-first, traceable, and portable personal knowledge library. It is less effortless than cloud sync, but the control is clearer.

Note Sync on KnightLi Blog