mirror of
https://github.com/firstsun-dev/git-files-sync.git
synced 2026-07-22 06:54:27 +00:00
docs: restyle README, host demo videos on R2, use official download stats (#44)
* docs(readme): restyle README following obsidian-pm conventions * docs: host demo videos on R2 instead of GitHub attachments * docs: use official Obsidian download stats badge --------- Co-authored-by: ClaudiaFang <tianyao.firstsun@gmail.coim>
This commit is contained in:
ClaudiaFang
GitHub
parent
bbd9bc64ac
commit
0a4cff5a46
2 changed files with 104 additions and 130 deletions
227
README.md
227
README.md
|
|
@ -1,176 +1,145 @@
|
|||
<div align="center">
|
||||
|
||||
# Git File Sync
|
||||
*Selective, file-by-file sync between your vault and GitHub, GitLab, or Gitea.*
|
||||
|
||||
[](https://github.com/firstsun-dev/git-files-sync/actions/workflows/ci.yml)
|
||||
[](https://github.com/firstsun-dev/git-files-sync/releases)
|
||||
[](https://github.com/firstsun-dev/git-files-sync/releases)
|
||||
[](https://obsidian.md)
|
||||
[](https://www.typescriptlang.org/)
|
||||
[](https://conventionalcommits.org)
|
||||
[](LICENSE)
|
||||
[](https://github.com/firstsun-dev/git-files-sync/actions/workflows/ci.yml)
|
||||
[](https://github.com/firstsun-dev/git-files-sync/releases)
|
||||
[](https://obsidian.md/plugins?id=git-file-sync)
|
||||
[](LICENSE)
|
||||
|
||||
**Supports:**
|
||||
<img src="https://img.shields.io/badge/GitHub-181717?style=flat-square&logo=github&logoColor=white" alt="GitHub" height="20">
|
||||
<img src="https://img.shields.io/badge/GitLab-FC6D26?style=flat-square&logo=gitlab&logoColor=white" alt="GitLab" height="20">
|
||||
<img src="https://img.shields.io/badge/Gitea-609926?style=flat-square&logo=gitea&logoColor=white" alt="Gitea" height="20">
|
||||
**[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.
|
||||
</div>
|
||||
|
||||
[繁體中文使用說明](USAGE_zh.md)
|
||||
Push, pull, diff, and resolve conflicts — file by file, not whole-vault. Unlike full-vault sync solutions, Git File Sync gives you granular control over exactly what leaves your device, so you can keep personal notes private while sharing project files through a real Git repository.
|
||||
|
||||
[git-file-sync](https://github.com/user-attachments/assets/78f383be-e8a4-4c9c-8845-1f46d06ea661)
|
||||
<img src="https://img.shields.io/badge/GitHub-181717?style=flat-square&logo=github&logoColor=white" alt="GitHub" height="20"> <img src="https://img.shields.io/badge/GitLab-FC6D26?style=flat-square&logo=gitlab&logoColor=white" alt="GitLab" height="20"> <img src="https://img.shields.io/badge/Gitea-609926?style=flat-square&logo=gitea&logoColor=white" alt="Gitea" height="20">
|
||||
|
||||
<video src="https://blog-assets.firstsun.org/obsidian/plugins/git-file-sync/git-file-sync-en.webm" autoplay loop muted playsinline width="600"></video>
|
||||
|
||||
|
||||
*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
|
||||
|
||||
<img src="https://img.shields.io/badge/GitHub-181717?style=for-the-badge&logo=github&logoColor=white" alt="GitHub" height="28">
|
||||
<img src="https://img.shields.io/badge/GitLab-FC6D26?style=for-the-badge&logo=gitlab&logoColor=white" alt="GitLab" height="28">
|
||||
<img src="https://img.shields.io/badge/Gitea-609926?style=for-the-badge&logo=gitea&logoColor=white" alt="Gitea" height="28">
|
||||
|
||||
| Provider | Hosting | Min. Version |
|
||||
| :--- | :--- | :--- |
|
||||
| Provider | Hosting | Min. version |
|
||||
|---|---|---|
|
||||
| <img src="https://img.shields.io/badge/GitHub-181717?style=flat-square&logo=github&logoColor=white" alt="GitHub"> | github.com · GitHub Enterprise | — |
|
||||
| <img src="https://img.shields.io/badge/GitLab-FC6D26?style=flat-square&logo=gitlab&logoColor=white" alt="GitLab"> | gitlab.com · self-hosted | GitLab 13.0+ |
|
||||
| <img src="https://img.shields.io/badge/Gitea-609926?style=flat-square&logo=gitea&logoColor=white" alt="Gitea"> | 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 `<vault>/.obsidian/plugins/`.
|
||||
3. Copy the downloaded files into that folder.
|
||||
4. Reload Obsidian and enable the plugin.
|
||||
|
||||
---
|
||||
> **Gitea note:** the plugin talks to the Gitea API v1 (`/api/v1`) and resolves branch names to commit SHAs before fetching the file tree, which is what makes 1.12+ the floor.
|
||||
|
||||
## Configuration
|
||||
|
||||
|
||||
*Configure the plugin by selecting your preferred Git service and providing the necessary credentials.*
|
||||
*Pick a provider and supply its credentials in Settings > Git File Sync.*
|
||||
|
||||
### 1. Choose Your Service
|
||||
Go to **Settings** > **Git File Sync** and select **GitLab**, **GitHub**, or **Gitea** from the dropdown.
|
||||
| | Provider | Required info | Token scope |
|
||||
|:---:|---|---|---|
|
||||
| <img src="https://img.shields.io/badge/GitHub-181717?style=flat-square&logo=github&logoColor=white" alt="GitHub"> | **GitHub** | Personal access token, owner, repo name | `repo` |
|
||||
| <img src="https://img.shields.io/badge/GitLab-FC6D26?style=flat-square&logo=gitlab&logoColor=white" alt="GitLab"> | **GitLab** | Personal access token, project ID, base URL | `api` |
|
||||
| <img src="https://img.shields.io/badge/Gitea-609926?style=flat-square&logo=gitea&logoColor=white" alt="Gitea"> | **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 |
|
||||
| :---: | :--- | :--- | :--- |
|
||||
| <img src="https://img.shields.io/badge/GitHub-181717?style=flat-square&logo=github&logoColor=white" alt="GitHub"> | **GitHub** | Personal Access Token, Owner, Repo Name | `repo` |
|
||||
| <img src="https://img.shields.io/badge/GitLab-FC6D26?style=flat-square&logo=gitlab&logoColor=white" alt="GitLab"> | **GitLab** | Personal Access Token, Project ID, Base URL | `api` |
|
||||
| <img src="https://img.shields.io/badge/Gitea-609926?style=flat-square&logo=gitea&logoColor=white" alt="Gitea"> | **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 `<vault>/.obsidian/plugins/git-file-sync/`.
|
||||
3. Copy the three files into that folder.
|
||||
4. Reload Obsidian and enable the plugin under **Settings > Community plugins**.
|
||||
|
||||
---
|
||||
## Quick start
|
||||
|
||||
1. Configure a provider in **Settings > Git File Sync** (see [Configuration](#configuration)).
|
||||
2. Open the **Sync Status View** — the list icon in the ribbon, or run `Open sync status view` from the Command Palette.
|
||||
3. Click **Refresh status** to compare your vault against the remote repo.
|
||||
4. Select files and **Push selected** or **Pull selected** as needed.
|
||||
|
||||
**Commands:**
|
||||
|
||||
| Command | What it does |
|
||||
|---|---|
|
||||
| Open sync status view | Open the sync dashboard |
|
||||
| Push current file to GitLab/GitHub/Gitea | Push the active note |
|
||||
| Pull current file to GitLab/GitHub/Gitea | Pull the active note |
|
||||
| Push all files | Push every tracked, changed file |
|
||||
| Pull all files | Pull every tracked, changed file |
|
||||
|
||||
## Privacy and security
|
||||
|
||||
- **Local storage** — personal access tokens are stored locally in the plugin's data folder inside your vault, and are only ever sent to the Git provider you configured.
|
||||
- **No telemetry** — the plugin collects no usage data or analytics.
|
||||
|
||||
## Requirements
|
||||
|
||||
- Obsidian **1.13.0** or later
|
||||
- Desktop and mobile supported
|
||||
|
||||
## Development
|
||||
|
||||
If you want to contribute or build from source:
|
||||
|
||||
```bash
|
||||
# Clone and install
|
||||
git clone https://github.com/firstsun-dev/git-files-sync.git
|
||||
npm install
|
||||
|
||||
# Development build
|
||||
npm run dev
|
||||
|
||||
# Production build
|
||||
npm run build
|
||||
npm run dev # watch build
|
||||
npm run build # type-check + production build
|
||||
npm run test # vitest suite
|
||||
npm run lint # eslint
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## License
|
||||
|
||||
This project is licensed under the [MIT License](LICENSE).
|
||||
MIT
|
||||
|
||||
---
|
||||
|
||||
|
|
|
|||
|
|
@ -1,6 +1,11 @@
|
|||
# Git File Sync 使用說明書
|
||||
|
||||
<video src="imgs/git-file-sync-zh.webm" width="100%" controls autoplay loop muted playsinline></video>
|
||||
[](https://github.com/firstsun-dev/git-files-sync/actions/workflows/ci.yml)
|
||||
[](https://github.com/firstsun-dev/git-files-sync/releases)
|
||||
[](https://obsidian.md/plugins?id=git-file-sync)
|
||||
[](LICENSE)
|
||||
|
||||
<video src="https://blog-assets.firstsun.org/obsidian/plugins/git-file-sync/git-file-sync-zh.webm" width="100%" controls autoplay loop muted playsinline></video>
|
||||
|
||||
本指南將引導您如何使用 Git File Sync 插件，在行動裝置與桌面電腦之間，透過 GitLab、GitHub 或自架的 Gitea 輕鬆同步您的筆記。
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue