# git-sync

**Repository Path**: ricsy/git-sync

## Basic Information

- **Project Name**: git-sync
- **Description**: 1111111111
- **Primary Language**: TypeScript
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-11
- **Last Updated**: 2026-03-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Git Sync

基于 Git 的文件同步工具，将本地文件备份到远程 Git 仓库（GitHub/Gitee），支持大文件压缩、多种认证方式

## ✨ 核心特性

- ⏰ **多种触发方式** - 手动执行、定时同步、文件监控自动同步
- 📦 **智能压缩** - 大文件自动 tar.gz 压缩，减少仓库体积
- 🔐 **多种认证** - 支持 Token、HTTPS、SSH 三种认证方式
- 🎯 **Glob 匹配** - 灵活配置要同步的文件路径
- 🚫 **智能排除** - 内置默认排除规则 + 自定义排除
- 📋 **详细日志** - 命令行简洁输出，详细日志写入文件
- 🔒 **敏感信息脱敏** - 支持正则和 JSON 键路径，相同值产生相同哈希
- 👁️ **干运行预览** - 预览同步文件列表，不实际执行

## 📦 安装

```bash
pip install -e .
```

## 🚀 快速使用

```bash
# 1. 复制配置示例
cp config.yaml config.example.yaml

# 2. 编辑配置
vim config.yaml

# 3. 执行同步
git-sync -c config.yaml
```

## 💻 命令行参数

除了配置文件，还可以通过命令行参数直接指定文件和选项：

```bash
# 直接指定要同步的文件/目录（需多次使用 -f）
git-sync sync -f file1.txt -f backups/
git-sync sync --file file1.txt --file backups/

# 跳过 exclude 排除规则
git-sync sync -f file1.txt -e
git-sync sync -f file1.txt --no-exclude

# 快速指定（等价于 -f xxx -e）
git-sync sync -fe file1.txt backups/
git-sync sync --files-skip-exclude file1.txt backups/

# 指定备份在仓库中的目标目录（优先级高于配置）
git-sync sync -f file1.txt -d backups/
git-sync sync -f file1.txt --dir backups/

# 路径支持 ~ 展开和绝对路径
git-sync sync -f ~/docs/ -d ~/backups/

# 组合使用
git-sync sync -fe file1.txt file2.txt -d backups/

# 自定义 commit 消息
git-sync sync -f file.txt -m "update config"

# 覆盖配置文件的触发方式（阻塞当前终端）
git-sync sync --mode schedule                    # 定时运行
git-sync sync --mode watch                       # 监控文件变化
git-sync sync --mode manual                      # 手动运行（默认）
```

### CLI 参数说明

#### sync

| 参数                                 | 说明                                |
|------------------------------------|-----------------------------------|
| `-c, --config <path>`              | 配置文件路径                            |
| `-f, --file <path>`                | 直接指定要同步的文件/目录（需多次使用 -f）           |
| `-e, --no-exclude`                 | 跳过 exclude 排除规则                   |
| `-fe, --files-skip-exclude <path>` | 直接指定文件并跳过 exclude（等价于 -f xxx -e）  |
| `-d, --dir <path>`                 | 指定备份文件在仓库中的目标目录                   |
| `--dry-run`                        | 干运行模式，仅显示文件列表不实际同步                |
| `-o, --output <path>`              | 将脱敏后的内容输出到指定文件                    |
| `-m, --message <text>`             | 自定义 commit 消息，不指定则使用默认消息          |
| `--mode <mode>`                    | 运行方式：manual/schedule/watch，覆盖配置文件 |

#### logs

| 参数                | 说明                           |
|-------------------|------------------------------|
| `-n, --lines <N>` | 显示最近 N 行日志（最大 10000）         |
| `-f, --follow`    | 实时跟踪日志（类似 tail -f，Ctrl+C 退出） |
| `-c, --clear`     | 清空日志文件                       |

示例：

```bash
git-sync logs               # 查看最近 100 行日志
git-sync logs -n 200        # 查看最近 200 行
git-sync logs -f            # 实时跟踪日志（Ctrl+C 退出）
git-sync logs --clear       # 清空日志文件
git-sync logs -fc           # 清空日志并实时跟踪
```

## 📝 配置文件

支持 YAML、JSON、TOML 格式。配置示例：

```yaml
trigger:
  type: manual  # manual | schedule | watch
  schedule: ""  # hourly | daily HH:MM | weekly DDD HH:MM | minutes N

remote:
  platform: github  # github | gitee
  repo: owner/repo
  branch: main

auth:
  type: token  # token | https | ssh
  token: your_token_here

paths:
  - ./docs
  - ./scripts

exclude:
  - "*.tmp"

compressThreshold: 1048576  # 1MB，超过此大小的文件会被压缩
compressTimeout: 300  # 压缩超时时间（秒），最小 1 秒，最大 3600 秒（1 小时），默认 300 秒
targetDir: "."  # 备份文件在仓库中的目录，. 表示根目录
tempDir: "/tmp/git-sync/backups"  # 临时仓库目录
commitMessage: "backup: sync files"  # 自定义 commit 消息，可被 CLI -m 参数覆盖
debug: false
autoCreateBranch: false  # 远程分支不存在时是否自动创建
enableLogFile: false  # 是否启用日志文件写入，默认关闭
logRotation: "10 MB"  # 日志轮转大小
logRetention: "7 days"  # 日志保留时间

# 脱敏配置
redact:
  enabled: true  # 是否启用脱敏
  maxFileSize: 5242880  # 单文件脱敏大小限制（字节），超过此大小跳过脱敏，默认 5MB
  maxJsonDepth: 100  # JSON 递归解析最大深度，超过此深度跳过脱敏，默认 100
  formatJson: true  # 是否格式化 JSON 输出，true 使用 indent=2，false 使用紧凑格式
  rules:
    - file: "*.service"  # 文件 glob 模式
      type: text  # text(正则) 或 json(键路径)
      deterministic: true  # 确定性脱敏：相同值产生相同哈希，便于数据关联
      replacements:
        "TAVILY_API_KEY=\\S+": "TAVILY_API_KEY={redacted}"
        "GH_TOKEN=\\S+": "GH_TOKEN={redacted}"
    - file: "config.json"
      type: json
      deterministic: true
      # JSON 键路径通配符：
      #   *   匹配当前层的任意键（如 a.*.c 匹配 a.xxx.c）
      #   **  递归匹配任意深度的键（如 **.token 匹配任意深度的 token 键）
      replacements:
        "api.key": "{redacted}"
        "api.token": "{redacted}"
```

**确定性脱敏说明：**
- `deterministic: true`（默认）时，相同值脱敏为相同输出（如 `{redacted_a1b2c3d4}`）
- `deterministic: false` 时，相同值脱敏为 `{redacted}`（无哈希后缀）
- 确定性脱敏便于数据关联分析，同一敏感值可追溯

**配置占位符：**
配置文件支持占位符语法 `{xxx}`，运行时会提示输入实际值：

```yaml
auth:
  token: "{your_token}"  # 运行时会提示输入
remote:
  repo: "{owner/repo-name}"  # 运行时会提示输入
```

**JSON 键路径通配符说明：**

| 格式   | 示例          | 说明                                             |
|------|-------------|------------------------------------------------|
| `*`  | `api.*.key` | 匹配当前层的任意键（a.b、a.c 都能匹配）                        |
| `**` | `**.token`  | 递归匹配任意深度的键（a.token、a.b.token、a.b.c.token 都能匹配） |

### trigger.schedule 格式说明

| 格式                 | 示例                 | 说明                     |
|--------------------|--------------------|------------------------|
| `hourly`           | `hourly`           | 每小时执行                  |
| `daily HH:MM`      | `daily 02:00`      | 每天指定时间执行               |
| `weekly DDD HH:MM` | `weekly mon 02:00` | 每周指定星期和时间执行            |
| `minutes N`        | `minutes 30`       | 每 N 分钟执行（最大 10080，即一周） |

## 🚫 默认排除规则

以下文件/目录为配置示例中的排除规则（实际排除规则由配置文件中的 `exclude` 字段定义）：

- `.git/*`
- `.env`
- `*.tmp`
- `*.log`
- `.DS_Store`
- `Thumbs.db`
- `.venv/*`
- `*.pyc`
- `__pycache__/*`
- `node_modules/*`
- `secret/**`

## 📋 日志文件

日志文件默认保存在平台标准数据目录下：

| 平台      | 日志路径                                                   |
|---------|--------------------------------------------------------|
| Linux   | `~/.local/share/git-sync/logs/main.log`                |
| macOS   | `~/Library/Application Support/git-sync/logs/main.log` |
| Windows | `%LOCALAPPDATA%/git-sync/logs/main.log`                |

可通过配置文件配置：

```yaml
enableLogFile: false  # 是否启用日志文件写入，默认关闭
logRotation: "10 MB"  # 日志轮转大小
logRetention: "7 days" # 日志保留时间
```

## ❌ 错误码

| 错误码 | 含义                        | 说明       |
|-----|---------------------------|----------|
| 0   | SUCCESS                   | 同步成功     |
| 101 | CONFIG_LOAD_FAILED        | 配置文件加载失败 |
| 102 | CONFIG_VALIDATION_FAILED  | 配置验证失败   |
| 201 | AUTH_FAILED               | 认证失败     |
| 202 | GIT_CLONE_FAILED          | Git 克隆失败 |
| 203 | GIT_PUSH_FAILED           | Git 推送失败 |
| 301 | FILE_COMPRESSION_FAILED   | 文件压缩失败   |
| 302 | FILE_PATTERN_MATCH_FAILED | 文件匹配失败   |
| 303 | FILE_TOO_LARGE            | 文件过大     |
| 401 | UNKNOWN_ERROR             | 未知错误     |

## ⚠️ 使用限制

- 同步前必须确认配置文件存在且有效
- Token、密码等敏感信息不会出现在日志中
- 文件处理失败时会记录详细错误信息
- 不得同步包含敏感信息的文件（如 `.env`、私钥等）
- 同步过程中不会删除或覆盖用户原始文件
- 只会推送文件到配置的分支

## 📊 处理流程图

### 触发与同步主流程

```
开始
  │
  ▼
加载配置文件
  │
  ▼
检测到占位符 {xxx}？ ────否───► 验证配置
  │是                         │
  ▼                            ▼
提示用户输入              验证配置
  │                            │
  ▼                            ▼
更新配置文件 ──────────► 执行同步
  │                            │
  └────── 重新加载配置 ◄────────┘
```

### 触发模式流程

```
触发类型判断
  │
  ├─► MANUAL ──► 执行一次备份
  │
  ├─► SCHEDULE ──► 设置定时任务 ──► 循环等待 ──► schedule.run_pending()
  │                                              ▲
  │                                              │
  └────────────────── 退出 ◄─────────────────────┘（Ctrl+C）
  │
  └─► WATCH ──► 启动文件监控 ──► 等待文件变化 ──► 触发备份
                    ▲                                 │
                    │                                 │
                    └─────── 退出（Ctrl+C/SIGTERM）◄─┘
```

### 文件扫描与备份流程

```
开始
  │
  ▼
文件扫描（基于 patterns）
  │
  ▼
跳过 exclude 规则？ ────是───► 跳过排除文件
  │否                            │
  ▼                              ▼
检查文件大小                检查文件大小
  │                              │
  ▼                              ▼
超过压缩阈值？              超过压缩阈值？
  │是        │否                │是        │否
  ▼           ▼                  ▼           ▼
压缩文件    普通文件          压缩文件    普通文件
  │                              │
  └──────────┬───────────────────┘
             │
             ▼
生成备份文件列表
             │
             ▼
干运行模式？ ────是───► 显示文件列表，结束
  │否
  ▼
应用脱敏规则（如启用）
  │
  ▼
复制文件到目标目录
```

### Git 仓库同步流程

```
开始
  │
  ▼
本地仓库已存在且有效？ ────是───► git fetch + git merge
  │否                                  │
  ▼                                    ▼
git clone（depth=1）              切换到目标分支
  │                                    │
  ▼                                    ▼
切换到目标分支 ◄──────────────────────┘
  │
  ▼
添加文件到 Git 索引
  │
  ▼
检查是否有变更
  │
  ├─ 无变更 ──► git push（推送已有 commit），结束
  │
  ▼
执行 git commit
  │
  ▼
本地分支存在？ ────否───► autoCreateBranch？
  │是                         │是           │否
  ▼                           ▼              ▼
git push                  git push       抛出异常
                          HEAD:refs/heads/xxx（需用户确认）
```

### 首次推送（空仓库）流程

```
开始
  │
  ▼
克隆远程仓库
  │
  ▼
检查远程分支是否存在
  │
  ├─ 存在 ──► 切换到该分支 ──► 正常推送流程
  │
  └─ 不存在 ──► 本地创建分支
                  │
                  ▼
              autoCreateBranch？
                │是           │否
                ▼              ▼
            推送到远程      抛出异常
            结束             （需用户确认）
```