Git on KnightLi Blog

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.

Using Agent Skills to Replace Copilot's 'Generate Commit Message' in VS Code

Mon, 06 Apr 2026 13:09:49 +0800

GitHub Copilot’s “Generate Commit Message” in VS Code is very useful. Once the quota is exhausted, the reset cycle can feel long. This post is a practical attempt to replace that feature with local Agent Skills.

Problem and Goal

The goal of this post is to provide a practical alternative: use git-commit-push-zh skill agents to complete standardized commits and pushes.

Alternative: `git-commit-push-zh`

This skill turns your current changes into a fixed workflow:

Check change status.
Confirm the current branch.
Stage changes.
Generate a Chinese commit message.
Run commit.
Push to the remote branch.

The corresponding commands are:

git status --short
git branch --show-current
git add -A
git commit -m "<中文提交信息>"
git push origin <当前分支>

Suggested Commit Message Convention

Use this format consistently:

`1`	`<类型>(<范围>): <中文摘要>`

Type examples:

feat: New feature
fix: Bug fix
docs: Documentation update
refactor: Refactoring
chore: Maintenance changes

Examples:

feat(site): 新增全站 head 广告脚本注入
fix(i18n): 修正 relref 相关文章链接路径
chore(content): 合并 AI 工作流分类到 AI工具

Common Failure Scenarios

nothing to commit: no new changes to commit; stop before pushing.
push failed: check permissions, remote branch state, and conflicts first.
SSH/permission issues: verify credentials and access, then retry.

Appendix: Original `SKILL.md`

The content below is the original git-commit-push-zh document, preserved as-is for reuse and maintenance.

---
name: git-commit-push-zh
description: 在当前 Git 仓库中将“当前更改”完成一次标准提交流程：检查状态、暂存变更、生成中文提交信息、执行 commit 并 push 到当前分支对应远端。用户提出“提交代码”“提交当前更改”“生成中文提交信息并推送”“git commit push 中文说明”等请求时使用。
---

# 中文提交并推送

使用此技能将当前仓库改动一次性提交并推送到远端。

## 工作流程

1. 查看变更状态：`git status --short`。
2. 确认当前分支：`git branch --show-current`。
3. 暂存当前变更：`git add -A`。
4. 生成中文提交信息（简洁、可检索）。
5. 执行提交：`git commit -m "<中文提交信息>"`。
6. 执行推送：`git push origin <当前分支>`。

## 提交信息规范（中文）

1. 建议格式：`<类型>(<范围>): <中文摘要>`。
2. 类型示例：`feat`、`fix`、`chore`、`docs`、`refactor`。
3. 摘要要求：准确描述本次改动，不写空话。
4. 若仅少量变更，也保持可读性与可检索性。

示例：

- `feat(site): 新增全站 head 广告脚本注入`
- `fix(i18n): 修正 relref 相关文章链接路径`
- `chore(content): 合并 AI 工作流分类到 AI工具`

## 错误处理

1. 若无可提交变更（nothing to commit），明确告知并停止 push。
2. 若 push 失败，先回报关键错误（权限、远端不存在、冲突等）。
3. 常见 SSH/权限问题可在用户确认后重试高权限环境。

## 输出约定

1. 汇报提交哈希、分支名、提交信息。
2. 汇报 push 结果（成功或失败原因）。
3. 仅在确有失败时提供下一步最小操作建议。

How Git Tracks File Executable Permission (+x)

Sun, 29 Mar 2026 10:00:00 +0800

In a Linux environment, Git tracks a file’s executable bit (+x). If you want a script to be preserved as an executable file in the repository, you need to explicitly record that permission change in Git.

Add Executable Permission to a File

1
2
3

git update-index --chmod=+x script.sh
git commit -m "chore: mark script.sh as executable"
git push

This command stages the executable-bit change for script.sh. After you commit and push, other users will keep the same permission state when they pull or clone the repository.

Remove Executable Permission from a File

1
2
3

git update-index --chmod=-x script.sh
git commit -m "chore: remove executable bit from script.sh"
git push

Verify the Result

Use the following commands to check file permissions in your working tree:

1
2

git clone xxxxxxxxxxxxxxx
ls -l script.sh

If you see something like -rwxr-xr-x, the file is executable. If you see -rw-r--r--, it is not executable.

Notes

git update-index --chmod=+x/-x only updates the file mode recorded by Git; it does not replace changes to file content.
In team workflows, it is best to commit permission-only changes separately for easier review and tracking.

Build a Git Server on Synology NAS and Back It Up with Hyper Backup

Wed, 07 Dec 2022 00:00:00 +0000

Synology NAS can be used as a lightweight private Git server. For personal projects or a small team, this is often enough: repositories stay inside the LAN, access can be managed through NAS accounts, and the data can be backed up with Synology’s built-in tools.

This note records the basic setup idea and the backup workflow with Hyper Backup.

Install Git Server

Open Package Center on Synology DSM and install the Git Server package.

After installation, open Git Server and allow the required users to use Git over SSH. The NAS account must have SSH access and permission to the folder where repositories are stored.

Prepare A Repository Directory

Create a shared folder or a subdirectory for Git repositories, for example:

`1`	`/volume1/git`

Inside this directory, create bare repositories:

`1`	`git init --bare project.git`

A bare repository does not contain a working tree. It is suitable for use as a remote repository.

Connect From A Client

From another machine, clone the repository through SSH:

`1`	`git clone user@nas-ip:/volume1/git/project.git`

You can also add it as a remote in an existing local project:

1
2

git remote add origin user@nas-ip:/volume1/git/project.git
git push -u origin master

If SSH uses a non-standard port, specify it in the SSH configuration or use a custom remote URL.

Permissions

Make sure the repository directory belongs to the correct user or group. If multiple users need access, assign them to a shared group and grant read/write permission to the Git folder.

When push fails, check these items first:

whether SSH login works;
whether the user is allowed in Git Server;
whether the folder permission is writable;
whether the repository was initialized as bare;
whether the remote URL is correct.

Back Up With Hyper Backup

After repositories are stored on the NAS, configure Hyper Backup to back up the Git directory.

In Hyper Backup:

Create a new backup task.
Select the destination, such as another disk, another NAS, rsync server or cloud storage.
Select the Git repository folder.
Configure the schedule.
Enable version retention if needed.

This protects the repository data against disk failure, accidental deletion or wrong pushes.

Restore Notes

When restoring, recover the whole bare repository directory. After restoration, test with:

`1`	`git clone user@nas-ip:/volume1/git/project.git`

If cloning works, the repository is usable again.

Summary

Synology Git Server is simple, but it is enough for many private repositories. The important points are SSH access, correct folder permissions, bare repositories and a reliable Hyper Backup task.