mirror of
https://github.com/xheldon/git-folder-sync.git
synced 2026-07-22 06:59:00 +00:00
add Readme
This commit is contained in:
Xheldon
parent
33b4284577
commit
088c5e90bc
2 changed files with 286 additions and 86 deletions
190
README.md
190
README.md
|
|
@ -1,164 +1,182 @@
|
|||
# Git 同步 Obsidian 插件
|
||||
# Git Sync Obsidian Plugin
|
||||
|
||||
一个支持与 GitHub 仓库同步的 Obsidian 插件，使用 React 构建用户界面，支持热重载开发。
|
||||
An Obsidian plugin that supports synchronization with GitHub repositories, built with a modern interface and hot reload development support.
|
||||
|
||||
## 功能特性
|
||||
## Features
|
||||
|
||||
- 🔄 **双向同步**: 支持将笔记同步到 GitHub 或从 GitHub 拉取笔记
|
||||
- 🎯 **单文件操作**: 可以单独同步当前编辑的文件
|
||||
- 📁 **批量操作**: 支持整个 Vault 的批量同步
|
||||
- 🔧 **可视化配置**: 使用 React 构建的现代化配置界面
|
||||
- 🚀 **热重载开发**: 支持开发时的热重载
|
||||
- 📂 **递归文件夹**: 完整支持文件夹结构的递归同步
|
||||
- 🔄 **Bidirectional Sync**: Support syncing notes to GitHub or pulling notes from GitHub
|
||||
- 🎯 **Single File Operations**: Sync individual files currently being edited
|
||||
- 📁 **Batch Operations**: Support batch synchronization of entire Vault
|
||||
- 🔧 **Visual Configuration**: Modern configuration interface with intuitive controls
|
||||
- 🚀 **Hot Reload Development**: Support for hot reload during development
|
||||
- 📂 **Recursive Folders**: Complete support for recursive synchronization of folder structures
|
||||
- 🌍 **Internationalization**: Support for Chinese and English languages
|
||||
- 💾 **Smart Caching**: File status caching to reduce GitHub API calls
|
||||
- 📊 **Real-time Status**: Status bar showing file sync status and last modified time
|
||||
|
||||
## 安装
|
||||
## Installation
|
||||
|
||||
### 手动安装
|
||||
### Manual Installation
|
||||
|
||||
1. 下载最新的 release 文件
|
||||
2. 将文件解压到你的 Obsidian 插件目录：`{vault}/.obsidian/plugins/git-sync/`
|
||||
3. 重启 Obsidian
|
||||
4. 在设置中启用"Git Sync"插件
|
||||
1. Download the latest release files
|
||||
2. Extract files to your Obsidian plugins directory: `{vault}/.obsidian/plugins/git-sync/`
|
||||
3. Restart Obsidian
|
||||
4. Enable the "Git Sync" plugin in settings
|
||||
|
||||
### 开发安装
|
||||
### Development Installation
|
||||
|
||||
1. 克隆此仓库到你的插件目录：
|
||||
1. Clone this repository to your plugins directory:
|
||||
|
||||
```bash
|
||||
cd {vault}/.obsidian/plugins/
|
||||
git clone https://github.com/你的用户名/obsidian-git-sync git-sync
|
||||
git clone https://github.com/yourusername/obsidian-git-sync git-sync
|
||||
cd git-sync
|
||||
```
|
||||
|
||||
2. 安装依赖：
|
||||
2. Install dependencies:
|
||||
|
||||
```bash
|
||||
npm install
|
||||
```
|
||||
|
||||
3. 开发模式（支持热重载）：
|
||||
3. Development mode (with hot reload):
|
||||
|
||||
```bash
|
||||
npm run dev
|
||||
```
|
||||
|
||||
4. 构建生产版本：
|
||||
4. Build production version:
|
||||
```bash
|
||||
npm run build
|
||||
```
|
||||
|
||||
## 配置
|
||||
## Configuration
|
||||
|
||||
### 1. GitHub Personal Access Token
|
||||
|
||||
首先需要创建一个 GitHub Personal Access Token：
|
||||
First, create a GitHub Personal Access Token:
|
||||
|
||||
1. 访问 [GitHub Settings > Developer settings > Personal access tokens](https://github.com/settings/tokens)
|
||||
2. 点击"Generate new token (classic)"
|
||||
3. 选择以下权限：
|
||||
- `repo` (完整的仓库访问权限)
|
||||
4. 复制生成的 token
|
||||
1. Visit [GitHub Settings > Developer settings > Personal access tokens](https://github.com/settings/tokens)
|
||||
2. Click "Generate new token (classic)"
|
||||
3. Select the following permissions:
|
||||
- `repo` (Full repository access)
|
||||
4. Copy the generated token
|
||||
|
||||
### 2. 仓库路径配置
|
||||
### 2. Repository Path Configuration
|
||||
|
||||
仓库路径格式：`@https://github.com/用户名/仓库名/路径/到/文件夹`
|
||||
Repository path formats:
|
||||
|
||||
示例：
|
||||
- `https://github.com/username/repo/path/to/folder` (Standard GitHub URL)
|
||||
- `username/repo/path/to/folder` (Short format)
|
||||
|
||||
- `@https://github.com/Xheldon/git-sync/data/_post`
|
||||
- `@https://github.com/username/notes/obsidian-vault`
|
||||
Examples:
|
||||
|
||||
## 使用方法
|
||||
- `https://github.com/Xheldon/git-sync/data/_post`
|
||||
- `username/notes/obsidian-vault`
|
||||
|
||||
### 编辑器按钮
|
||||
## Usage
|
||||
|
||||
点击左侧边栏的设置图标打开配置界面。
|
||||
### Settings Interface
|
||||
|
||||
### 笔记同步菜单
|
||||
Click the settings icon in the left sidebar to open the configuration interface, or access it through Obsidian's plugin settings.
|
||||
|
||||
在编辑笔记时，可以通过以下方式访问同步菜单：
|
||||
### Note Sync Menu
|
||||
|
||||
1. 使用命令面板：`Ctrl/Cmd + P` → 搜索"显示同步菜单"
|
||||
2. 右键点击编辑器 → 选择"Git 同步"
|
||||
While editing notes, you can access the sync menu through:
|
||||
|
||||
菜单选项：
|
||||
1. Command palette: `Ctrl/Cmd + P` → Search for "Show Sync Menu"
|
||||
2. Right-click in editor → Select "Git Sync"
|
||||
3. Status bar sync button (bottom right)
|
||||
|
||||
- **同步当前文件到远端**: 将当前文件上传到 GitHub
|
||||
- **拉取远端覆盖当前文件**: 从 GitHub 下载文件覆盖本地
|
||||
Menu options:
|
||||
|
||||
### 配置界面功能
|
||||
- **Sync current file to remote**: Upload current file to GitHub
|
||||
- **Pull remote to current file**: Download file from GitHub to overwrite local
|
||||
|
||||
#### 基本设置
|
||||
### Configuration Interface Features
|
||||
|
||||
- **GitHub Personal Token**: 输入你的访问令牌
|
||||
- **GitHub 仓库路径**: 配置目标仓库和路径
|
||||
#### Basic Settings
|
||||
|
||||
#### 批量操作
|
||||
- **Interface Language**: Choose between Chinese, English, or follow Obsidian
|
||||
- **GitHub Personal Token**: Enter your access token
|
||||
- **GitHub Repository Path**: Configure target repository and path
|
||||
- **Show Ribbon Icon**: Toggle sidebar button visibility
|
||||
|
||||
- **初始化仓库**: 当 Vault 为空时，从远端下载所有文件
|
||||
- **强制同步远端到本地**: 将远端文件同步到本地（会覆盖同名文件）
|
||||
- **强制同步本地到远端**: 将本地文件同步到远端
|
||||
#### Batch Operations (Danger Zone)
|
||||
|
||||
## 开发
|
||||
- **Initialize Repository**: Download all files from remote when Vault is empty
|
||||
- **Force Sync Remote to Local**: Sync remote files to local (overwrites same-name files)
|
||||
- **Force Sync Local to Remote**: Sync local files to remote
|
||||
- **Clear File Cache**: Clear all cached file status data
|
||||
|
||||
### 项目结构
|
||||
#### Sponsor
|
||||
|
||||
- **Support Development**: Links to sponsor the project development
|
||||
|
||||
## Development
|
||||
|
||||
### Project Structure
|
||||
|
||||
```
|
||||
├── main.ts # 插件主文件
|
||||
├── types.ts # 类型定义
|
||||
├── github-service.ts # GitHub API服务
|
||||
├── settings-modal.tsx # React配置界面
|
||||
├── styles.css # 样式文件
|
||||
├── manifest.json # 插件清单
|
||||
├── package.json # 项目配置
|
||||
├── tsconfig.json # TypeScript配置
|
||||
├── esbuild.config.mjs # 构建配置
|
||||
└── version-bump.mjs # 版本管理脚本
|
||||
├── main.ts # Main plugin file
|
||||
├── types.ts # Type definitions
|
||||
├── github-service.ts # GitHub API service
|
||||
├── file-cache.ts # File caching service
|
||||
├── i18n-simple.ts # Internationalization system
|
||||
├── styles.css # Stylesheet
|
||||
├── manifest.json # Plugin manifest
|
||||
├── package.json # Project configuration
|
||||
├── tsconfig.json # TypeScript configuration
|
||||
├── esbuild.config.mjs # Build configuration
|
||||
└── version-bump.mjs # Version management script
|
||||
```
|
||||
|
||||
### 开发命令
|
||||
### Development Commands
|
||||
|
||||
```bash
|
||||
# 安装依赖
|
||||
# Install dependencies
|
||||
npm install
|
||||
|
||||
# 开发模式（热重载）
|
||||
# Development mode (hot reload)
|
||||
npm run dev
|
||||
|
||||
# 构建生产版本
|
||||
# Build production version
|
||||
npm run build
|
||||
|
||||
# 版本管理
|
||||
# Version management
|
||||
npm run version
|
||||
```
|
||||
|
||||
## 技术栈
|
||||
## Tech Stack
|
||||
|
||||
- **TypeScript**: 主要开发语言
|
||||
- **React**: 用户界面框架
|
||||
- **Obsidian API**: 插件核心 API
|
||||
- **GitHub API**: 通过@octokit/rest 进行仓库操作
|
||||
- **esbuild**: 快速构建工具
|
||||
- **TypeScript**: Primary development language
|
||||
- **Obsidian API**: Core plugin API
|
||||
- **GitHub API**: Repository operations via @octokit/rest
|
||||
- **esbuild**: Fast build tool
|
||||
- **i18n**: Custom internationalization system
|
||||
|
||||
## 注意事项
|
||||
## Important Notes
|
||||
|
||||
1. **权限要求**: 需要 GitHub 仓库的写入权限
|
||||
2. **文件冲突**: 强制同步会覆盖现有文件，请谨慎使用
|
||||
3. **网络要求**: 需要稳定的网络连接访问 GitHub API
|
||||
4. **Token 安全**: 请妥善保管你的 GitHub Personal Access Token
|
||||
1. **Permission Requirements**: Requires write access to GitHub repository
|
||||
2. **File Conflicts**: Force sync will overwrite existing files, use with caution
|
||||
3. **Network Requirements**: Requires stable network connection to access GitHub API
|
||||
4. **Token Security**: Keep your GitHub Personal Access Token secure
|
||||
5. **Rate Limits**: GitHub API has rate limits (5000 requests/hour for authenticated users)
|
||||
|
||||
## 贡献
|
||||
## Contributing
|
||||
|
||||
欢迎提交 Issue 和 Pull Request！
|
||||
Issues and Pull Requests are welcome!
|
||||
|
||||
## 赞助
|
||||
## Sponsor
|
||||
|
||||
如果这个插件对你有帮助，欢迎请我喝杯咖啡 ☕
|
||||
If this plugin helps you, consider buying me a coffee ☕
|
||||
|
||||
[](https://paypal.me/xheldoncao)
|
||||
[](https://paypal.me/xheldoncao)
|
||||
|
||||
你的支持是我继续开发和维护这个项目的动力！
|
||||
For users in mainland China: [https://www.xheldon.com/donate/](https://www.xheldon.com/donate/)
|
||||
|
||||
## 许可证
|
||||
Your support motivates me to continue developing and maintaining this project!
|
||||
|
||||
## License
|
||||
|
||||
MIT License
|
||||
|
|
|
|||
182
README_CN.md
Normal file
182
README_CN.md
Normal file
|
|
@ -0,0 +1,182 @@
|
|||
# Git 同步 Obsidian 插件
|
||||
|
||||
一个支持与 GitHub 仓库同步的 Obsidian 插件，具有现代化界面和热重载开发支持。
|
||||
|
||||
## 功能特性
|
||||
|
||||
- 🔄 **双向同步**: 支持将笔记同步到 GitHub 或从 GitHub 拉取笔记
|
||||
- 🎯 **单文件操作**: 可以单独同步当前编辑的文件
|
||||
- 📁 **批量操作**: 支持整个 Vault 的批量同步
|
||||
- 🔧 **可视化配置**: 现代化配置界面，操作直观简单
|
||||
- 🚀 **热重载开发**: 支持开发时的热重载
|
||||
- 📂 **递归文件夹**: 完整支持文件夹结构的递归同步
|
||||
- 🌍 **国际化支持**: 支持中文和英文界面
|
||||
- 💾 **智能缓存**: 文件状态缓存，减少 GitHub API 调用
|
||||
- 📊 **实时状态**: 状态栏显示文件同步状态和最后修改时间
|
||||
|
||||
## 安装
|
||||
|
||||
### 手动安装
|
||||
|
||||
1. 下载最新的 release 文件
|
||||
2. 将文件解压到你的 Obsidian 插件目录：`{vault}/.obsidian/plugins/git-sync/`
|
||||
3. 重启 Obsidian
|
||||
4. 在设置中启用"Git Sync"插件
|
||||
|
||||
### 开发安装
|
||||
|
||||
1. 克隆此仓库到你的插件目录：
|
||||
|
||||
```bash
|
||||
cd {vault}/.obsidian/plugins/
|
||||
git clone https://github.com/yourusername/obsidian-git-sync git-sync
|
||||
cd git-sync
|
||||
```
|
||||
|
||||
2. 安装依赖：
|
||||
|
||||
```bash
|
||||
npm install
|
||||
```
|
||||
|
||||
3. 开发模式（支持热重载）：
|
||||
|
||||
```bash
|
||||
npm run dev
|
||||
```
|
||||
|
||||
4. 构建生产版本：
|
||||
```bash
|
||||
npm run build
|
||||
```
|
||||
|
||||
## 配置
|
||||
|
||||
### 1. GitHub Personal Access Token
|
||||
|
||||
首先需要创建一个 GitHub Personal Access Token：
|
||||
|
||||
1. 访问 [GitHub Settings > Developer settings > Personal access tokens](https://github.com/settings/tokens)
|
||||
2. 点击"Generate new token (classic)"
|
||||
3. 选择以下权限：
|
||||
- `repo` (完整的仓库访问权限)
|
||||
4. 复制生成的 token
|
||||
|
||||
### 2. 仓库路径配置
|
||||
|
||||
仓库路径格式：
|
||||
|
||||
- `https://github.com/用户名/仓库名/路径/到/文件夹` (标准 GitHub URL)
|
||||
- `用户名/仓库名/路径/到/文件夹` (简短格式)
|
||||
|
||||
示例：
|
||||
|
||||
- `https://github.com/Xheldon/git-sync/data/_post`
|
||||
- `username/notes/obsidian-vault`
|
||||
|
||||
## 使用方法
|
||||
|
||||
### 设置界面
|
||||
|
||||
点击左侧边栏的设置图标打开配置界面，或通过 Obsidian 的插件设置访问。
|
||||
|
||||
### 笔记同步菜单
|
||||
|
||||
在编辑笔记时，可以通过以下方式访问同步菜单：
|
||||
|
||||
1. 使用命令面板：`Ctrl/Cmd + P` → 搜索"显示同步菜单"
|
||||
2. 右键点击编辑器 → 选择"Git 同步"
|
||||
3. 状态栏同步按钮（右下角）
|
||||
|
||||
菜单选项：
|
||||
|
||||
- **同步当前文件到远端**: 将当前文件上传到 GitHub
|
||||
- **从远端拉取到当前文件**: 从 GitHub 下载文件覆盖本地
|
||||
|
||||
### 配置界面功能
|
||||
|
||||
#### 基本设置
|
||||
|
||||
- **界面语言**: 选择中文、英文或跟随 Obsidian
|
||||
- **GitHub Personal Token**: 输入你的访问令牌
|
||||
- **GitHub 仓库路径**: 配置目标仓库和路径
|
||||
- **显示侧边栏按钮**: 切换侧边栏按钮的显示
|
||||
|
||||
#### 批量操作（危险区域）
|
||||
|
||||
- **初始化仓库**: 当 Vault 为空时，从远端下载所有文件
|
||||
- **强制同步远端到本地**: 将远端文件同步到本地（会覆盖同名文件）
|
||||
- **强制同步本地到远端**: 将本地文件同步到远端
|
||||
- **清空文件缓存**: 清空所有缓存的文件状态数据
|
||||
|
||||
#### 赞助
|
||||
|
||||
- **支持开发**: 赞助项目开发的链接
|
||||
|
||||
## 开发
|
||||
|
||||
### 项目结构
|
||||
|
||||
```
|
||||
├── main.ts # 插件主文件
|
||||
├── types.ts # 类型定义
|
||||
├── github-service.ts # GitHub API 服务
|
||||
├── file-cache.ts # 文件缓存服务
|
||||
├── i18n-simple.ts # 国际化系统
|
||||
├── styles.css # 样式文件
|
||||
├── manifest.json # 插件清单
|
||||
├── package.json # 项目配置
|
||||
├── tsconfig.json # TypeScript 配置
|
||||
├── esbuild.config.mjs # 构建配置
|
||||
└── version-bump.mjs # 版本管理脚本
|
||||
```
|
||||
|
||||
### 开发命令
|
||||
|
||||
```bash
|
||||
# 安装依赖
|
||||
npm install
|
||||
|
||||
# 开发模式（热重载）
|
||||
npm run dev
|
||||
|
||||
# 构建生产版本
|
||||
npm run build
|
||||
|
||||
# 版本管理
|
||||
npm run version
|
||||
```
|
||||
|
||||
## 技术栈
|
||||
|
||||
- **TypeScript**: 主要开发语言
|
||||
- **Obsidian API**: 插件核心 API
|
||||
- **GitHub API**: 通过 @octokit/rest 进行仓库操作
|
||||
- **esbuild**: 快速构建工具
|
||||
- **i18n**: 自定义国际化系统
|
||||
|
||||
## 注意事项
|
||||
|
||||
1. **权限要求**: 需要 GitHub 仓库的写入权限
|
||||
2. **文件冲突**: 强制同步会覆盖现有文件，请谨慎使用
|
||||
3. **网络要求**: 需要稳定的网络连接访问 GitHub API
|
||||
4. **Token 安全**: 请妥善保管你的 GitHub Personal Access Token
|
||||
5. **速率限制**: GitHub API 有速率限制（认证用户每小时 5000 次请求）
|
||||
|
||||
## 贡献
|
||||
|
||||
欢迎提交 Issue 和 Pull Request！
|
||||
|
||||
## 赞助
|
||||
|
||||
如果这个插件对你有帮助，欢迎请我喝杯咖啡 ☕
|
||||
|
||||
[](https://paypal.me/xheldoncao)
|
||||
|
||||
中国大陆用户: [https://www.xheldon.com/donate/](https://www.xheldon.com/donate/)
|
||||
|
||||
你的支持是我继续开发和维护这个项目的动力！
|
||||
|
||||
## 许可证
|
||||
|
||||
MIT License
|
||||
Loading…
Reference in a new issue