ossync

ossync 是一个 Node.js CLI，用于把私有仓库中的某个 Git 提交快照安全同步到一个独立的开源工作目录。它默认假设开源目录位于当前项目内部，例如 ./opensource，并且该目录本身是一个独立 Git 仓库。

第一版聚焦在“安全同步快照”这一个核心动作，不做敏感词扫描。同步前会展示关键上下文，并在默认模式下要求交互确认。

功能

• init：初始化项目级配置和开源目录
• status：查看当前仓库、公开目录和最近同步状态
• sync：将指定 ref 的 Git 快照同步到开源目录
• 目标目录同步时会删除除 .git 外的旧文件
• 默认阻止在公开仓库存在未提交改动时继续同步

设计约束

• 私有仓库和公开仓库是两个独立仓库
• 开源目录默认必须位于私有仓库内部
• 开源目录不能等于私有仓库根目录
• sync 默认只同步 Git 已提交的内容，不包含当前工作区未提交改动

安装

本地开发

npm install

本地试运行

node ./src/cli.js --help

如果需要全局命令，可以在项目内执行：

npm link
ossync --help

命令说明

ossync init

在私有仓库根目录写入配置文件 .opensource-sync.json，并准备开源目录。

示例：

ossync init
ossync init --public-dir opensource --yes

默认行为：

• 创建 opensource 目录
• 如果目标目录不是 Git 仓库，则自动执行 git init -b main
• 将 opensource/ 写入私有仓库的 .gitignore

常用参数：

• --public-dir <path>：设置公开目录
• --yes：使用默认值，不进入交互
• --force：覆盖已有配置
• --no-auto-add-to-gitignore：不修改 .gitignore
• --no-init-target-repo：不自动初始化公开仓库

ossync status

查看当前配置和最近同步记录。

ossync status

输出内容包括：

• 私有仓库根目录
• 当前分支和 HEAD
• 私有仓库工作区是否干净
• 开源目录是否存在
• 开源目录是否是独立 Git 仓库
• 最近一次同步的来源引用和提交

ossync sync

将某个 Git 提交、分支或 tag 的快照同步到公开目录。

ossync sync
ossync sync --ref HEAD~1
ossync sync --ref v1.0.0
ossync sync --dry-run
ossync sync --yes

默认行为：

1. 读取配置文件
2. 解析目标 ref
3. 检查开源目录是否存在且为独立 Git 仓库
4. 检查开源目录工作区是否干净
5. 列出将要删除的内容数量
6. 交互确认
7. 使用 git archive --format=zip 导出快照
8. 删除开源目录中除 .git 外的全部内容
9. 解压快照到开源目录
10. 写入最近同步状态文件 .opensource-sync.state.json

常用参数：

• --ref <ref>：指定来源引用，默认 HEAD
• --yes：跳过交互确认
• --force：允许公开仓库存在未提交改动
• --dry-run：只展示计划，不实际同步

配置文件

文件名：.opensource-sync.json

示例：

{
  "version": 1,
  "publicDir": "opensource",
  "confirmDelete": true,
  "autoAddToGitignore": true,
  "dangerouslyAllowOutsideRepo": false
}

字段说明：

• version：配置版本，当前固定为 1
• publicDir：公开目录，相对于私有仓库根目录
• confirmDelete：同步时是否要求删除确认
• autoAddToGitignore：初始化时是否自动追加到 .gitignore
• dangerouslyAllowOutsideRepo：是否允许公开目录位于私有仓库外部，默认关闭

状态文件

文件名：.opensource-sync.state.json

该文件由 sync 自动写入，用于记录最近一次同步结果。例如：

{
  "lastSyncAt": "2026-03-26T08:00:00.000Z",
  "lastSourceRef": "HEAD",
  "lastResolvedCommit": "abc1234def5678",
  "publicDir": "opensource"
}

推荐工作流

1. 在私有仓库提交一个你准备开源的节点
2. 执行 ossync sync --ref <commit-or-tag>
3. 切到 opensource 目录检查内容
4. 在公开仓库中手工删除不适合公开的文件、补 README 或 LICENSE
5. 在公开仓库里提交并推送

测试

运行：

npm test

当前测试覆盖：

• init 初始化配置、.gitignore 和嵌套公开仓库
• sync 替换目标目录内容
• status 展示最近同步状态

已知限制

• 当前不做敏感词扫描
• 当前不做“同步后自动删除某些路径”的规则化处理
• 当前默认面向本地仓库工作流，不包含远程推送逻辑