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

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:

1. Create a bare Git repository on the NAS as the central notes repository.
2. Clone the repository on Windows and write notes with a normal editor.
3. Clone the same repository on Android and use a Git client to pull and push.
4. 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:

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:

1
2
3
4

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:

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:

1
2
3
4
5

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.

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:

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:

1. Enable WebDAV on the NAS or deploy Nextcloud.
2. Configure the same sync target on Joplin for Windows.
3. Configure the same sync target on Joplin for Android.
4. 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:

1
2
3
4
5
6
7

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:

1. Before writing on another device, run git pull --rebase.
2. After a writing session, run commit and push promptly.
3. Do not edit the same file on two devices for a long time at the same time.
4. Do not keep adding unlimited images and large attachments into the Git repository.
5. 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:

1
2
3
4

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

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.