-
-
+**[Releases](https://github.com/firstsun-dev/git-files-sync/releases)** · **[繁體中文使用說明](USAGE_zh.md)** · **[Changelog](CHANGELOG.md)**
-**Git File Sync** is a powerful Obsidian plugin that enables seamless synchronization of individual notes with GitLab, GitHub, or self-hosted Gitea repositories. Unlike full-vault sync solutions, it gives you granular control over what gets pushed and pulled, making it perfect for shared projects, selective backups, and cross-platform workflows.
+
+
+
-*The Sync Status View provides a clear overview of your files, allowing you to selectively push, pull, or view diffs for modified files.*
+*The Sync Status View gives a bird's-eye view of your vault, letting you selectively push, pull, or diff modified files.*
+
+## What's inside
+
+- **File-by-file control** — Sync individual notes or whole folders, not your entire vault. No lock-in to a single sync provider for everything.
+- **Three Git providers** — GitHub, GitLab (including self-hosted), and Gitea, all behind one consistent UI.
+- **Visual diffing** — A built-in diff viewer compares local and remote versions side-by-side before anything is overwritten.
+- **Conflict resolution** — When local and remote both changed, resolve manually with a dedicated conflict tool instead of guessing which version wins.
+- **Works on mobile** — Full support for Obsidian Mobile with a touch-friendly sync dashboard.
+
+## Sync Status View
+
+A single dashboard shows the state of every tracked file:
+
+- **Status filtering** — instantly see what's modified, new, or missing.
+- **Visual diffs** — line-by-line comparison of local vs. remote before syncing.
+- **Remote-only detection** — spot files that exist on GitHub/GitLab/Gitea but haven't been pulled into the vault yet.
-*The Built-in Diff Viewer lets you compare local and remote changes side-by-side before syncing.*
+*The built-in diff viewer compares local and remote changes before you push or pull.*
----
+## Providers
-## Supported Providers
-
-
-
-
-
-| Provider | Hosting | Min. Version |
-| :--- | :--- | :--- |
+| Provider | Hosting | Min. version |
+|---|---|---|
| | github.com · GitHub Enterprise | — |
| | gitlab.com · self-hosted | GitLab 13.0+ |
| | self-hosted | Gitea 1.12+ |
-> **Gitea compatibility note**: The plugin uses the Gitea API v1 (`/api/v1`). It resolves branch names to commit SHAs before fetching the file tree, which ensures compatibility with Gitea 1.12 and later. Versions before 1.12 are not supported.
-
----
-
-## Key Features
-
-### Selective Synchronization
-Don't sync your whole vault. Selectively push or pull individual notes, or use batch operations for specific folders. Perfect for keeping personal notes private while sharing project files.
-
-### Visual Sync Dashboard
-A comprehensive dashboard provides a bird's-eye view of your vault's status:
-- **Status Filtering**: Instantly see what's modified, new, or missing.
-- **Visual Diffs**: Compare local and remote changes line-by-line before syncing.
-- **Remote-Only Detection**: Identify files existing on GitLab/GitHub/Gitea that aren't in your vault yet.
-
-### Intelligent Conflict Resolution
-When versions clash, Git File Sync provides a dedicated diff viewer to help you resolve conflicts manually. Choose the local version, the remote version, or merge them with confidence.
-
-### Mobile First
-Full support for Obsidian Mobile. Push and pull your notes on the go with a responsive UI designed specifically for touch interfaces.
-
----
-
-## Installation
-
-### From Community Plugins (Recommended)
-1. Open **Obsidian Settings** > **Community plugins**.
-2. Click **Browse** and search for `Git File Sync`.
-3. Click **Install**, then **Enable**.
-
-### Manual Installation
-1. Download the latest `main.js`, `manifest.json`, and `styles.css` from the [Releases](https://github.com/firstsun-dev/git-files-sync/releases) page.
-2. Create a folder named `git-file-sync` in ` | **GitHub** | Personal access token, owner, repo name | `repo` |
+| | **GitLab** | Personal access token, project ID, base URL | `api` |
+| | **Gitea** | Personal access token, base URL, owner, repo name | (all) |
-### 2. Provider Setup
+- **GitHub token:** Settings → Developer settings → Personal access tokens → `repo` scope.
+- **GitLab token:** User settings → Access tokens → `api` scope. Base URL defaults to `https://gitlab.com`; change it for self-hosted instances.
+- **Gitea token:** User settings → Applications → Access tokens. Point the base URL at your instance (e.g. `https://gitea.example.com`).
-| | Provider | Required Info | Token Scope |
-| :---: | :--- | :--- | :--- |
-| | **GitHub** | Personal Access Token, Owner, Repo Name | `repo` |
-| | **GitLab** | Personal Access Token, Project ID, Base URL | `api` |
-| | **Gitea** | Personal Access Token, Base URL, Owner, Repo Name | (all) |
+Other settings: **branch** to sync against (default `main`), **root path** prefix inside the repo, **vault folder** to scope which notes are tracked, and **symbolic link handling** (*real* — recreate the link, GitHub only; *follow* — sync the target's content; *skip*). See [Symbolic link handling](docs/symlink-handling.md) for details.
-**GitHub token**: Settings → Developer settings → Personal access tokens → `repo` scope.
+## Daily workflow
-**GitLab token**: User settings → Access tokens → `api` scope. The Base URL defaults to `https://gitlab.com`; change it for self-hosted instances.
+**Pushing:**
+- One note — the cloud icon in the ribbon, or the command `Push current file to GitLab/GitHub/Gitea`.
+- Several notes — open the Sync Status View, filter to **Modified**, select files, click **Push selected**.
+- From the file tree — right-click any file and choose `Push to GitLab/GitHub/Gitea`.
-**Gitea token**: User settings → Applications → Access tokens. Set the Base URL to your Gitea instance (e.g. `https://gitea.example.com`).
-
-### 3. Common Settings
-- **Branch**: Specify the target branch (default: `main`).
-- **Root Path**: Prefix for files in the repository (e.g., `notes/`).
-- **Vault Folder**: Limit sync to a specific folder in your vault.
-- **Symbolic links**: Choose how symlinks are synced — *real* (recreate the link, GitHub only), *follow* (sync the target's content), or *skip*. See [Symbolic link handling](docs/symlink-handling.md).
-
----
-
-## Usage Guide
-
-### First-Time Setup
-Once configured, you should perform an initial status check:
-1. Open the **Sync Status View** by clicking the list icon in the left ribbon or using the Command Palette (`Open sync status view`).
-2. Click **Refresh status**. The plugin will compare your local files with the remote repository.
-3. Review the file list to see which files are synchronized, modified, or missing.
-
-### Daily Workflow: Pushing Changes
-When you finish editing a note and want to save it to Git:
-- **Current Note**: Use the cloud icon in the ribbon or the command `Push current file to GitLab/GitHub/Gitea`.
-- **Multiple Notes**: Open the Sync Status View, use the **Modified** filter, select the files you want to sync, and click **Push selected**.
-- **Context Menu**: Right-click any file in the File Explorer and select `Push to GitLab/GitHub/Gitea`.
-
-### Daily Workflow: Pulling Changes
-To get the latest updates from other devices:
+**Pulling:**
1. Open the Sync Status View and click **Refresh status**.
-2. Files with remote updates will show as **Modified** or **Remote only**.
-3. Select these files and click **Pull selected**.
-4. **Warning**: Pulling will overwrite local changes. If there are conflicts, the Conflict Resolution tool will open.
+2. Files with remote updates show as **Modified** or **Remote only**.
+3. Select them and click **Pull selected**. Pulling overwrites local changes — if both sides changed, the conflict tool opens instead.
-### Handling Conflicts
-If a file has changed both locally and on the remote server:
-1. A **Conflict Resolution** window will appear.
-2. The left pane shows your **Local** version, and the right pane shows the **Remote** version.
-3. Review the differences.
-4. Click **Keep Local** to overwrite the remote version on next push, or **Keep Remote** to accept the remote changes and overwrite your local file.
+**Resolving a conflict:**
+1. The Conflict Resolution window opens automatically.
+2. Left pane is your **Local** version, right pane is **Remote**.
+3. Choose **Keep Local** (overwrite remote on next push) or **Keep Remote** (accept remote, overwrite local).
-### Mobile Synchronization
-On mobile devices:
-- Swipe from the left to access the ribbon and open the Sync Status View.
-- Use the **Pull** action to keep your mobile vault up to date before editing.
-- After editing, use the **Push** action to save your changes back to the repository.
+**On mobile:** swipe from the left to open the ribbon and the Sync Status View, pull before you start editing, push when you're done.
----
+## Installation
-## Privacy and Security
+### From Community Plugins (recommended)
+1. Open **Settings > Community plugins** and turn off restricted mode.
+2. Click **Browse**, search for **Git File Sync**, click **Install**, then **Enable**.
-- **Local Storage**: Your Personal Access Tokens (PAT) are stored locally in the plugin's data folder within your vault. They are never sent to any server other than your configured Git provider.
-- **No Telemetry**: This plugin does not collect any data or usage analytics.
+### Manual
+1. Download `main.js`, `manifest.json`, and `styles.css` from the [latest release](https://github.com/firstsun-dev/git-files-sync/releases/latest).
+2. Create `