mirror of
https://github.com/firstsun-dev/git-files-sync.git
synced 2026-07-22 06:54:27 +00:00
docs: overhaul README and add Traditional Chinese usage guide
This commit is contained in:
ClaudiaFang
parent
282e4bfc7b
commit
cab60ad9fa
5 changed files with 165 additions and 188 deletions
2
LICENSE
2
LICENSE
|
|
@ -1,6 +1,6 @@
|
|||
MIT License
|
||||
|
||||
Copyright (c) 2026 Wanjin Li
|
||||
Copyright (c) 2026 Claudia Fang
|
||||
|
||||
Permission is hereby granted, free of charge, to any person obtaining a copy
|
||||
of this software and associated documentation files (the "Software"), to deal
|
||||
|
|
|
|||
273
README.md
273
README.md
|
|
@ -1,228 +1,133 @@
|
|||
# Git File Push
|
||||
# Git File Sync
|
||||
|
||||
An Obsidian plugin that enables seamless synchronization of individual notes with GitLab or GitHub repositories across mobile and desktop platforms.
|
||||
[](https://github.com/firstsun-dev/git-files-push/releases)
|
||||
[](https://github.com/firstsun-dev/git-files-push/releases)
|
||||
[](LICENSE)
|
||||
[](https://obsidian.md)
|
||||
|
||||
## Features
|
||||
**Git File Sync** is a powerful Obsidian plugin that enables seamless synchronization of individual notes with GitLab or GitHub 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.
|
||||
|
||||
- **Multiple Git Services**: Support for both GitLab and GitHub (user selectable)
|
||||
- **GitHub Organization Support**: Works with both personal and organization repositories
|
||||
- **Push to Remote**: Upload individual notes to your Git repository
|
||||
- **Pull from Remote**: Download and sync notes from your repository
|
||||
- **Batch Operations**: Push or pull all modified files at once with progress tracking
|
||||
- **Sync Status View**: Visual dashboard showing all files' sync status with complete git diff
|
||||
- **Remote-Only Files Detection**: Shows files that exist on remote but not locally
|
||||
- **Batch Selection**: Select multiple files for batch push/pull/delete operations
|
||||
- **Status Filtering**: Filter files by sync status (All/Synced/Modified/Not in remote/Remote only)
|
||||
- **Progress Bar**: Real-time progress indicator during sync operations
|
||||
- **Last Sync Time**: Display when the last sync check was performed
|
||||
- **Conflict Resolution**: Visual diff viewer to compare local and remote versions when conflicts occur
|
||||
- **Vault Folder Filter**: Optionally sync only files within a specific vault folder
|
||||
- **Ribbon Icon**: Quick access button in the left sidebar for pushing the current note
|
||||
- **Command Palette**: Commands for pushing and pulling files (single or batch)
|
||||
- **Context Menu**: Right-click any file to push or pull directly from the file menu
|
||||
- **Cross-Platform**: Works on both desktop and mobile versions of Obsidian
|
||||
- **Mobile Optimized**: Responsive UI design for small screens
|
||||
- **Sync Tracking**: Maintains metadata to track last synced SHA and timestamp for each file
|
||||
- **Conflict Detection**: Automatically detects conflicts and prompts for resolution
|
||||
- **Auto-Refresh**: Automatically updates file status after push/pull operations
|
||||
[繁體中文使用說明](USAGE_zh.md)
|
||||
|
||||
## Setup
|
||||
---
|
||||
|
||||
1. Install the plugin in Obsidian
|
||||
2. Open Settings → Git File Push
|
||||
3. Select your preferred Git service (GitLab or GitHub)
|
||||
4. Configure the settings based on your choice:
|
||||
## Key Features
|
||||
|
||||
### GitLab Configuration
|
||||
- **GitLab Personal Access Token**: Create a token in GitLab (User Settings → Access Tokens) with "API" scope
|
||||
- **GitLab Base URL**: Defaults to `https://gitlab.com` (change if using self-hosted GitLab)
|
||||
- **Project ID**: Found in your GitLab project's overview page
|
||||
### 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.
|
||||
|
||||
### GitHub Configuration
|
||||
- **GitHub Personal Access Token**: Create a token in GitHub (Settings → Developer Settings → Personal Access Tokens) with "repo" scope
|
||||
- **Repository Owner**: Your GitHub username or organization name
|
||||
- **Repository Name**: Name of the GitHub repository
|
||||
### 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 that aren't in your vault yet.
|
||||
|
||||
### Common Settings
|
||||
- **Branch**: The branch to sync with (defaults to `main`)
|
||||
- **Root Path**: Optional path prefix in the repository (e.g., "notes" to store files in a notes/ folder)
|
||||
- **Vault Folder**: Optional vault folder to sync (e.g., "sync" to only sync files in the sync/ folder, leave empty to sync all files)
|
||||
### 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.
|
||||
|
||||
## Usage
|
||||
### Mobile First
|
||||
Full support for Obsidian Mobile. Push and pull your notes on the go with a responsive UI designed specifically for touch interfaces.
|
||||
|
||||
### Sync Status View
|
||||
---
|
||||
|
||||
The Sync Status View is the main interface for managing your file synchronization.
|
||||
## Installation
|
||||
|
||||
**Opening the view:**
|
||||
- Click the list-checks icon in the left ribbon, or
|
||||
- Use Command Palette: "Open sync status view"
|
||||
### From Community Plugins (Recommended)
|
||||
1. Open **Obsidian Settings** > **Community plugins**.
|
||||
2. Click **Browse** and search for `Git File Sync`.
|
||||
3. Click **Install**, then **Enable**.
|
||||
|
||||
**Understanding the interface:**
|
||||
### Manual Installation
|
||||
1. Download the latest `main.js`, `manifest.json`, and `styles.css` from the [Releases](https://github.com/firstsun-dev/git-files-push/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.
|
||||
|
||||
1. **Service Information Panel**
|
||||
- Shows current service (GitLab/GitHub), branch, and vault folder
|
||||
- Displays last sync time
|
||||
---
|
||||
|
||||
2. **Control Buttons**
|
||||
- **Refresh status**: Check all files against remote repository (shows progress bar)
|
||||
- **Select all**: Select all files in current filter view
|
||||
- **Deselect all**: Clear all selections
|
||||
- **Push selected (N)**: Push all selected files to remote
|
||||
- **Pull selected (N)**: Pull all selected files from remote
|
||||
- **Delete selected (N)**: Delete selected local files (with confirmation)
|
||||
## Configuration
|
||||
|
||||
3. **Status Filters**
|
||||
- **All**: Show all files
|
||||
- **Synced**: Files that match remote (✓)
|
||||
- **Modified**: Files with local changes (⚠)
|
||||
- **Not in remote**: Local files not yet pushed (✗)
|
||||
- **Remote only**: Files on remote but not local (↓)
|
||||
### 1. Choose Your Service
|
||||
Go to **Settings** > **Git File Sync** and select either **GitLab** or **GitHub**.
|
||||
|
||||
4. **File Status Summary**
|
||||
- Shows count of files in each status category
|
||||
### 2. Provider Setup
|
||||
| Service | Required Info | Scope Needed |
|
||||
| :--- | :--- | :--- |
|
||||
| **GitLab** | Personal Access Token, Project ID, Base URL | `api` |
|
||||
| **GitHub** | Personal Access Token, Owner, Repo Name | `repo` |
|
||||
|
||||
5. **File List**
|
||||
- Each file shows: checkbox, status icon, file path, and status text
|
||||
- Click checkbox to select files for batch operations
|
||||
- Files show different actions based on status:
|
||||
- **Modified files**: Show diff button, Push, and Pull buttons
|
||||
- **Not in remote**: Push to remote, Remove local file buttons
|
||||
- **Remote only**: Pull from remote button
|
||||
### 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.
|
||||
|
||||
**Workflow examples:**
|
||||
---
|
||||
|
||||
*Sync all changes to remote:*
|
||||
1. Click "Refresh status"
|
||||
2. Review modified files
|
||||
3. Click "Select all" or manually select files
|
||||
4. Click "Push selected"
|
||||
## Usage Guide
|
||||
|
||||
*Pull new files from remote:*
|
||||
1. Click "Refresh status"
|
||||
2. Click "Remote only" filter
|
||||
3. Click "Select all"
|
||||
4. Click "Pull selected"
|
||||
### 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.
|
||||
|
||||
*Clean up local files not in remote:*
|
||||
1. Click "Refresh status"
|
||||
2. Click "Not in remote" filter
|
||||
3. Select unwanted files
|
||||
4. Click "Delete selected"
|
||||
### 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`.
|
||||
- **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`.
|
||||
|
||||
### Push Files
|
||||
### Daily Workflow: Pulling Changes
|
||||
To get the latest updates from other devices:
|
||||
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.
|
||||
|
||||
**Single file:**
|
||||
- Click the cloud upload icon in the left ribbon, or
|
||||
- Use Command Palette: "Push current file to GitLab/GitHub", or
|
||||
- Right-click a file and select "Push to GitLab/GitHub"
|
||||
- Status updates automatically after push
|
||||
### 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.
|
||||
|
||||
**Multiple files:**
|
||||
- Open Sync Status View
|
||||
- Select files using checkboxes
|
||||
- Click "Push selected (N)"
|
||||
- Or use "Refresh status" and filter by "Modified" or "Not in remote"
|
||||
### 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.
|
||||
|
||||
### Pull Files
|
||||
---
|
||||
|
||||
**Single file:**
|
||||
- Use Command Palette: "Pull current file from GitLab/GitHub", or
|
||||
- Right-click a file and select "Pull from GitLab/GitHub"
|
||||
- Status updates automatically after pull
|
||||
## Privacy and Security
|
||||
|
||||
**Multiple files:**
|
||||
- Open Sync Status View
|
||||
- Select files using checkboxes
|
||||
- Click "Pull selected (N)"
|
||||
- Or filter by "Remote only" to see files only on remote
|
||||
- **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 GitLab/GitHub.
|
||||
- **No Telemetry**: This plugin does not collect any data or usage analytics.
|
||||
|
||||
**Pull remote-only files:**
|
||||
- These are files that exist on remote but not in your local vault
|
||||
- Open Sync Status View → Click "Remote only" filter
|
||||
- Select files and click "Pull selected" to download them
|
||||
|
||||
### Batch Operations
|
||||
|
||||
**Push all modified files:**
|
||||
- Use Command Palette: "Push all markdown files"
|
||||
- Confirms before pushing
|
||||
- Shows progress during operation
|
||||
- Auto-refreshes status when complete
|
||||
|
||||
**Pull all modified files:**
|
||||
- Use Command Palette: "Pull all markdown files"
|
||||
- Warns about overwriting local changes
|
||||
- Shows progress during operation
|
||||
- Auto-refreshes status when complete
|
||||
|
||||
### Conflict Resolution
|
||||
|
||||
When a conflict is detected:
|
||||
1. A modal will appear showing both local and remote versions
|
||||
2. Review the differences in the diff viewer
|
||||
3. Choose to keep either the local or remote version
|
||||
4. The chosen version will be synced
|
||||
5. File status updates automatically
|
||||
---
|
||||
|
||||
## Development
|
||||
|
||||
### Prerequisites
|
||||
- Node.js v16 or higher
|
||||
- npm or yarn
|
||||
If you want to contribute or build from source:
|
||||
|
||||
### Setup
|
||||
```bash
|
||||
# Clone the repository
|
||||
git clone https://github.com/tianyao/gitlab-files-push.git
|
||||
|
||||
# Install dependencies
|
||||
# Clone and install
|
||||
git clone https://github.com/firstsun-dev/git-files-push.git
|
||||
npm install
|
||||
|
||||
# Start development mode (watch mode)
|
||||
# Development build
|
||||
npm run dev
|
||||
|
||||
# Production build
|
||||
npm run build
|
||||
```
|
||||
|
||||
### Available Commands
|
||||
- `npm run dev` - Build in watch mode using esbuild
|
||||
- `npm run build` - Type check and build for production
|
||||
- `npm run lint` - Run ESLint checks
|
||||
- `npm run test` - Run Vitest test suite
|
||||
- `npm run test:ui` - Run tests with UI
|
||||
- `npm run version` - Bump version in manifest.json and versions.json
|
||||
|
||||
### Manual Installation
|
||||
|
||||
Copy `main.js`, `manifest.json`, and `styles.css` (if exists) to your vault:
|
||||
```
|
||||
VaultFolder/.obsidian/plugins/git-file-push/
|
||||
```
|
||||
|
||||
## Project Structure
|
||||
|
||||
- `src/main.ts` - Main plugin class and command registration
|
||||
- `src/settings.ts` - Settings interface and configuration UI
|
||||
- `src/services/gitlab-service.ts` - GitLab API integration
|
||||
- `src/logic/sync-manager.ts` - Sync logic and conflict handling
|
||||
- `esbuild.config.mjs` - Build configuration
|
||||
|
||||
## Releasing
|
||||
|
||||
1. Update `minAppVersion` in `manifest.json` if needed
|
||||
2. Run `npm run version` to bump version numbers
|
||||
3. Create a GitHub release with tag matching the version
|
||||
4. Upload `manifest.json`, `main.js`, and `styles.css` as release assets
|
||||
|
||||
## Code Quality
|
||||
|
||||
- ESLint is configured with Obsidian-specific rules
|
||||
- Run `npm run lint` to check for issues
|
||||
- Husky pre-commit hooks ensure code quality
|
||||
---
|
||||
|
||||
## License
|
||||
|
||||
0-BSD
|
||||
This project is licensed under the [MIT License](LICENSE).
|
||||
|
||||
## Author
|
||||
---
|
||||
|
||||
[tianyao](https://github.com/tianyao)
|
||||
**Created by [firstsun-dev](https://github.com/firstsun-dev)**
|
||||
|
|
|
|||
72
USAGE_zh.md
Normal file
72
USAGE_zh.md
Normal file
|
|
@ -0,0 +1,72 @@
|
|||
# Git File Sync 使用說明書
|
||||
|
||||
本指南將引導您如何使用 Git File Sync 插件，在行動裝置與桌面電腦之間，透過 GitLab 或 GitHub 輕鬆同步您的筆記。
|
||||
|
||||
---
|
||||
|
||||
## 1. 初始設定
|
||||
|
||||
在開始同步之前，請確保您已完成以下設定：
|
||||
|
||||
1. **選擇服務**：在 `設定` > `Git File Sync` 中選擇 GitLab 或 GitHub。
|
||||
2. **填寫憑證**：
|
||||
- **GitHub**：需要 個人存取權杖 (PAT)、帳號名稱、儲存庫名稱。
|
||||
- **GitLab**：需要 個人存取權杖 (PAT)、專案 ID、伺服器網址 (預設為 gitlab.com)。
|
||||
3. **儲存庫路徑**：如果您想將筆記存放在儲存庫的特定資料夾（例如 `notes/`），請在 `Root Path` 中設定。
|
||||
|
||||
---
|
||||
|
||||
## 2. 核心操作流程
|
||||
|
||||
### 💡 檢查同步狀態
|
||||
每次開始工作或切換裝置時，建議先檢查狀態：
|
||||
1. 點擊側邊欄的 **清單圖示** 或使用指令面板 (`Ctrl/Cmd + P`) 輸入 `Open sync status view`。
|
||||
2. 點擊 **Refresh status**。
|
||||
3. 您會看到檔案清單，標示為：
|
||||
- **Synced**：已同步（與雲端一致）。
|
||||
- **Modified**：本機已修改（需要 Push）。
|
||||
- **Remote only**：雲端有新檔案（需要 Pull）。
|
||||
|
||||
---
|
||||
|
||||
### ⬆️ 如何上傳（Push）
|
||||
當您寫完筆記，想備份到雲端時：
|
||||
- **單一檔案**：
|
||||
- 點擊左側功能列的 **雲端上傳圖示**。
|
||||
- 或者在檔案列表點擊右鍵，選擇 `Push to GitLab/GitHub`。
|
||||
- **批量上傳**：
|
||||
- 在同步面板勾選多個檔案，點擊下方的 **Push selected**。
|
||||
|
||||
---
|
||||
|
||||
### ⬇️ 如何下載（Pull）
|
||||
當您在另一台裝置更新了筆記，想同步回目前裝置時：
|
||||
1. 打開同步面板，點擊 **Refresh status**。
|
||||
2. 找到顯示為 **Remote only** 或 **Modified** (雲端版本較新) 的檔案。
|
||||
3. 勾選後點擊 **Pull selected**。
|
||||
4. **注意**：Pull 會覆蓋掉您本機的內容。如果有衝突，會自動開啟衝突解決視窗。
|
||||
|
||||
---
|
||||
|
||||
## 3. 衝突處理 (Conflict Resolution)
|
||||
|
||||
如果同一個檔案在本機和雲端都被修改過，同步時會跳出衝突視窗：
|
||||
1. 左側為 **本機版本**，右側為 **雲端版本**。
|
||||
2. 您可以查看差異處。
|
||||
3. 選擇 **Keep Local**（保留本機）或 **Keep Remote**（採用雲端版本）。
|
||||
4. 選擇後系統會自動更新檔案。
|
||||
|
||||
---
|
||||
|
||||
## 4. 行動裝置使用技巧
|
||||
|
||||
- **開啟面板**：從螢幕左側向右滑動，展開功能列即可看到同步圖示。
|
||||
- **工作前先 Pull**：建議每次開始寫筆記前，先點一下 Refresh 確保讀取到最新版本。
|
||||
- **完成後即 Push**：寫完後隨手 Push，確保您的變更已儲存至雲端。
|
||||
|
||||
---
|
||||
|
||||
## 🔒 隱私與安全
|
||||
|
||||
- 您的存取權杖 (Token) 僅會儲存在您本機的 Obsidian 資料夾內。
|
||||
- 本插件不會收集任何個人數據或使用紀錄。
|
||||
|
|
@ -4,7 +4,7 @@
|
|||
"version": "1.0.0",
|
||||
"minAppVersion": "0.15.0",
|
||||
"description": "Selectively sync individual notes with GitLab or GitHub. Push, pull, diff, and resolve conflicts — file by file, on mobile and desktop.",
|
||||
"author": "tianyao",
|
||||
"authorUrl": "https://github.com/tianyao",
|
||||
"author": "firstsun-dev",
|
||||
"authorUrl": "https://github.com/firstsun-dev",
|
||||
"isDesktopOnly": false
|
||||
}
|
||||
|
|
@ -15,7 +15,7 @@
|
|||
"semantic-release": "semantic-release"
|
||||
},
|
||||
"keywords": [],
|
||||
"license": "0-BSD",
|
||||
"license": "MIT",
|
||||
"devDependencies": {
|
||||
"@eslint/js": "9.30.1",
|
||||
"@eslint/json": "0.14.0",
|
||||
|
|
|
|||
Loading…
Reference in a new issue