Gitee Sync

English | 中文

English

Gitee Sync stores an Obsidian vault as ordinary files in a private Gitee, GitHub, or GitLab repository. GitLab.com and self-managed GitLab instances are supported. The plugin connects directly to the platform API, requires no server or local Git installation, and works on desktop, iOS, and Android.

The sync engine uses Git blob hashes and a three-way comparison between the local vault, remote repository, and the last successful device-local baseline. It supports incremental two-way sync, deletion propagation, conflict resolution, dry-run previews, and diagnostic logs. When both sides modify the same file, the newer modification wins.

The plugin interface automatically follows Obsidian's language and currently supports English and Chinese.

Installation

In Obsidian, open Settings → Community plugins → Browse, search for Gitee Sync, install it, and enable it.

For local development builds:

npm install
npm run build

mkdir -p "<vault>/.obsidian/plugins/gitee-sync"
cp main.js manifest.json "<vault>/.obsidian/plugins/gitee-sync/"

Repository and token

Gitee: Create a private repository. In Settings → Security Settings → Personal access tokens, create a token with the projects permission.

GitHub: Create a private repository. A fine-grained personal access token needs Contents: Read and write access to the repository; a classic token needs the repo scope.

GitLab: Create a private project and initialize its default branch. Use a personal or project access token with the api scope and a role that can write to the repository. For self-managed GitLab, enter the instance base URL, such as https://gitlab.example.com, and the full project path from the repository URL, such as group/subgroup/project.

Configuration

Trigger sync from the ribbon icon, the Sync now command, the status bar, the timer, or startup sync. Use Preview sync plan to inspect planned actions without changing either side.

Changing the backend, repository/project, or branch clears the device-local baseline so the next sync safely performs a full reconciliation.

Each Obsidian vault keeps its own repository, token, and sync options in Obsidian's vault-scoped local storage. Configuring one vault never changes another vault's settings, even if the plugin directory is copied or synced between vaults.

Multiple devices

Install and configure the plugin on every device with the same repository. Each device keeps its own sync baseline. A new device downloads the remote vault on its first sync and uses incremental sync afterwards.

Mobile operating systems suspend timers in the background, so enabling Sync on startup is recommended.

iOS file visibility

If a downloaded folder is visible but a file with a non-standard extension is not, open Settings → Files and links and enable Detect all file extensions. The file may already be present but hidden by Obsidian's file explorer.

Sync behavior

• Local-only changes are uploaded; remote-only changes are downloaded.
• Deletions propagate in both directions. Local deletions use Obsidian's trash, and remote history remains recoverable through Git.
• If both sides modify the same file, the newer modification wins. A modification wins over a deletion.
• Hidden paths such as .obsidian and .git are ignored on both sides.
• Empty files (0 bytes) are skipped for consistent behavior across the supported repository APIs.
• Sync stops if the remote platform returns a truncated file tree, preventing accidental mass deletion.
• Every uploaded or deleted file creates a repository commit, so previous versions remain recoverable.

Limitations and security

• The first sync of a large vault creates one commit per file and may be limited by platform API quotas.
• Keep large attachments in an excluded folder. Individual files should preferably remain below 50 MB.
• Tokens are stored in Obsidian's vault-scoped local storage and are not written to the plugin's data.json file.
• Do not manually push the same vault to the same repository while the plugin manages it.

中文

Gitee Sync 将 Obsidian vault 中的笔记以普通文件形式保存到私有 Gitee、GitHub 或 GitLab 仓库。支持 GitLab.com 和自建 GitLab。插件直接连接平台 API，无需服务器或本地安装 Git，并支持桌面端、iOS 和 Android。

同步引擎使用 Git blob 内容哈希，对本地 vault、远端仓库和每台设备上次成功同步的基线进行三方比较。支持双向增量同步、删除同步、冲突处理、同步预演和诊断日志。两端同时修改同一文件时，保留修改时间较新的版本。

插件界面会自动跟随 Obsidian 的语言，目前支持中文和英语。

安装

在 Obsidian 中打开 设置 → 第三方插件 → 浏览，搜索 Gitee Sync，安装并启用插件。

本地开发版本可手动构建安装：

npm install
npm run build

mkdir -p "<vault>/.obsidian/plugins/gitee-sync"
cp main.js manifest.json "<vault>/.obsidian/plugins/gitee-sync/"

仓库和令牌

Gitee： 创建私有仓库，然后在 设置 → 安全设置 → 私人令牌 中创建令牌，并勾选 projects 权限。

GitHub： 创建私有仓库。Fine-grained token 需要目标仓库的 Contents: Read and write 权限；classic token 需要勾选 repo。

GitLab： 创建私有项目并初始化默认分支。使用带有 api scope 且角色具备仓库写入权限的个人或项目访问令牌。自建 GitLab 需要填写实例根地址（例如 https://gitlab.example.com），项目路径填写仓库 URL 中的完整路径（例如 group/subgroup/project）。

配置

可通过侧边栏同步图标、命令面板中的 立即同步、状态栏、定时器或启动时同步触发。使用 预览同步计划 可以在不修改两端文件的情况下检查计划动作。

更换存储后端、仓库/项目或分支时会清除本机同步基线，下一次同步将安全地执行全量对账。

每个 Obsidian 仓库分别保存自己的远端仓库、令牌和同步选项。配置一个仓库不会修改其他仓库，即使插件目录被复制或同步也不会串用配置。

多设备

在每台设备安装插件并配置同一仓库。每台设备分别保存同步基线。新设备首次同步会下载远端 vault，之后只进行增量同步。

移动端进入后台后，系统可能暂停定时器，建议开启 启动时同步。

iOS 文件显示

如果同步后能看到新目录，却看不到某些非标准扩展名文件，请打开 设置 → 文件与链接 → 检测所有文件扩展名。文件可能已经下载，只是被 Obsidian 文件列表隐藏。

同步规则

• 只在本地修改的文件会上传，只在远端修改的文件会下载。
• 删除会双向传播。本地删除进入 Obsidian 回收站，远端文件仍可通过 Git 历史恢复。
• 两端同时修改同一文件时，保留修改时间较新的版本；修改优先于删除。
• .obsidian、.git 等隐藏路径在两端都会被忽略。
• 空文件（0 字节）会被跳过，以便在各仓库平台间保持一致行为。
• 远端平台返回被截断的文件树时会中止同步，避免误判为批量删除。
• 每次文件上传或删除都会生成仓库 commit，旧版本可随时恢复。

限制与安全

• 大型 vault 首次同步会逐文件生成 commit，可能受到平台 API 限流影响。
• 建议将大附件放入排除目录，单文件尽量保持在 50 MB 以下。
• 令牌存放在 Obsidian 按仓库隔离的本地存储中，不会写入插件的 data.json 文件。
• 插件管理仓库后，不要同时把同一个 vault 手动推送到相同仓库。