remote-repo-copy

用 TypeScript 编写的 CLI 工具：把远程 Git 仓库克隆到本地临时目录，再按配置把其中的文件或目录复制到指定的本地文件夹。

环境要求

• Node.js >= 16.7
• 已安装 Git 并加入 PATH（克隆通过系统 git 完成，需能访问目标仓库）

安装

npm i -g remote-repo-copy

安装后即可在任意目录直接使用 remote-repo-copy 命令。

升级到最新版本：

npm i -g remote-repo-copy@latest

本地开发或从源码运行：

npm install
npm run build          # 产物输出到 dist/，构建时会自动压缩

npm start -- run       # 运行编译产物
npm run dev -- run     # 免编译直接运行 TS 源码

使用方法

零配置运行

内置默认配置开箱即用：拉取 https://gitee.com/WilliamHao/skills.git 的 main 分支，把仓库根目录全部内容复制到当前工作目录下的 .opencode/skills、.lingma/skills、.dsh/skills。

remote-repo-copy run

配置来源优先级

run 不带 -c 时按顺序取用，并会打印实际来源：

1. -c, --config <path> 显式指定的文件（不存在则报错）
2. 工具根目录下的 remote-repo-copy.config.json（存在即使用）
3. 内置默认配置（见 src/config.ts 的 createDefaultConfig()）

加载配置文件: /path/to/remote-repo-copy/remote-repo-copy.config.json
未找到配置文件: ...,使用内置默认配置

命令与参数

init：导出内置默认配置为可编辑文件（已存在则拒绝覆盖）

• -c, --config <path>：输出路径，默认当前目录的 remote-repo-copy.config.json

run：克隆仓库并按配置复制

• -c, --config <path>：指定配置文件；不指定时按上文优先级查找
• --repo-url <url>：临时覆盖仓库地址
• --branch <name>：临时覆盖分支或标签
• --keep-cache：保留临时克隆目录（默认自动清理）

通用：-h, --help、-V, --version。

示例

# 零配置运行
remote-repo-copy run

# 导出配置后自定义并指定执行
remote-repo-copy init -c ./configs/skills.json
remote-repo-copy run -c ./configs/skills.json

# 临时换仓库与分支
remote-repo-copy run --repo-url [email protected]:owner/repo.git --branch release/1.2

配置文件

{
  "repoUrl": "https://gitee.com/WilliamHao/skills.git",
  "branch": "main",
  "depth": 1,
  "clean": false,
  "mappings": [
    { "from": ".", "to": ".opencode/skills" },
    { "from": "docs/guide.md", "to": "./local/guide.md", "clean": true }
  ]
}

顶层字段：

• repoUrl：必填，仓库地址，支持 HTTPS、SSH、本地路径
• branch：可选，分支或标签，默认仓库默认分支
• depth：可选，浅克隆深度，默认 1；0 表示完整克隆
• clean：可选，复制前是否清空目标目录，默认 false
• mappings：必填，至少一条

mappings 每项：

• from：必填，仓库内相对路径（文件或目录），. 表示仓库根，不可为绝对路径
• to：必填，本地目标路径；相对路径基于执行命令时的工作目录解析
• clean：可选，覆盖顶层 clean

执行流程与日志

克隆到系统临时目录 → 按 mappings 逐条复制 → 删除临时目录（成功、复制失败、克隆失败都会清理）。

克隆仓库: https://gitee.com/WilliamHao/skills.git (main)
克隆完成: /var/folders/.../remote-repo-copy-cSSC2R
复制: . -> .opencode/skills
全部复制完成
已清理临时目录: /var/folders/.../remote-repo-copy-cSSC2R

项目结构

• src/index.ts：CLI 入口
• src/cli.ts：commander 命令定义与异常处理
• src/config.ts：配置加载优先级、校验与导出
• src/default-config.ts：内置默认配置
• src/git.ts：调用系统 git 克隆到临时目录
• src/copier.ts：路径解析与递归复制
• src/runner.ts：克隆、复制、清理流程编排
• src/version.ts：从 package.json 读取版本号
• scripts/minify.mjs：构建后用 esbuild 压缩 dist 产物

常见问题

• 配置文件不存在：检查 -c 路径；不带 -c 时先找工具根目录配置，再回退内置默认
• 配置文件已存在：init 不覆盖，请先备份删除或改用 -c 指定其他路径
• 远程仓库中不存在路径：核对对应 from 与实际仓库路径
• 复制到意料之外的位置：to 相对当前工作目录解析，先确认所在目录
• 目标目录残留旧文件：设置 "clean": true
• git clone 失败：确认地址、访问权限（私有仓库需配置 SSH key 或 HTTPS 凭证）与 git 可用