@youngwat/git-file-manager 0.0.0-stage → 1.0.0

package/src/commands/sync.js

@@ -0,0 +1,295 @@
+'use strict';
+
+/**
+ * sync —— 把指定 commit（可连续可不连续）里的文件改动，按原目录结构同步到另一个目录。
+ *
+ * 两种模式：
+ *   content（默认）：取文件在该 commit 时点的完整内容，覆盖写到目标目录的同名相对路径。
+ *                    不要求目标目录是 git 仓库、也不要求两边基线一致；内容相同自动跳过。
+ *   patch          ：生成这些 commit 的 diff 并 git apply 到目标目录。
+ *                    适合「目标目录是与源同基线的另一个副本，且要保留它上面的本地改动」。
+ */
+
+const fs = require('fs');
+const path = require('path');
+const git = require('../git');
+const log = require('../log');
+const backup = require('../backup');
+const { parseCommitSpec, short } = require('../commitSpec');
+
+const { CliError } = log;
+
+const MODES = ['content', 'patch'];
+
+/** 简易 glob：** 跨目录，* 不跨目录，? 单字符；不含通配符时按路径前缀匹配 */
+function globToRegExp(pattern) {
+  const p = String(pattern).replace(/\\/g, '/');
+  let re = '';
+  for (let i = 0; i < p.length; i++) {
+    const ch = p[i];
+    if (ch === '*') {
+      if (p[i + 1] === '*') {
+        i += 1;
+        if (p[i + 1] === '/') { i += 1; re += '(?:.*/)?'; } else { re += '.*'; }
+      } else {
+        re += '[^/]*';
+      }
+    } else if (ch === '?') {
+      re += '[^/]';
+    } else if ('\\^$.|+()[]{}'.includes(ch)) {
+      re += `\\${ch}`;
+    } else {
+      re += ch;
+    }
+  }
+  return new RegExp(`^${re}$`);
+}
+
+function makeMatcher(patterns) {
+  const list = (patterns || []).map((raw) => String(raw).trim().replace(/\\/g, '/')).filter(Boolean);
+  if (list.length === 0) return () => false;
+  return (file) => list.some((p) => {
+    if (!/[*?]/.test(p)) return file === p || file.startsWith(`${p}/`);
+    return globToRegExp(p).test(file);
+  });
+}
+
+/** 解析 --paths / --exclude 等逗号分隔（或数组）参数 */
+function toList(value) {
+  if (value == null) return [];
+  const arr = Array.isArray(value) ? value : String(value).split(',');
+  return arr.map((s) => s.trim()).filter(Boolean);
+}
+
+/**
+ * 汇总这些 commit 涉及的文件，后出现的改动覆盖先前的。
+ * 返回 [{ action, path, fromPath, sha }]，action ∈ add | modify | delete | rename
+ */
+function collectChanges(shas, filters) {
+  const map = new Map();
+  const merges = [];
+
+  for (const sha of shas) {
+    const info = git.commitInfo(sha);
+    if (info.parents.length > 1) merges.push(sha);
+    const args = ['show', '--name-status', '--format=', '-z', '--find-renames'];
+    if (info.parents.length > 1) args.push('--first-parent');
+    args.push(sha);
+    const parts = git.buffer(args).toString('utf8').split('\0');
+    let i = 0;
+    while (i < parts.length) {
+      const status = parts[i++];
+      if (!status) continue;
+      const code = status[0];
+      if (code === 'R' || code === 'C') {
+        const fromPath = parts[i++];
+        const toPath = parts[i++];
+        if (toPath) map.set(toPath, { action: 'rename', path: toPath, fromPath, sha });
+        if (fromPath) map.set(fromPath, { action: 'delete', path: fromPath, sha, renamedTo: toPath });
+      } else {
+        const file = parts[i++];
+        if (!file) continue;
+        const action = code === 'D' ? 'delete' : (code === 'A' ? 'add' : 'modify');
+        map.set(file, { action, path: file, sha });
+      }
+    }
+  }
+
+  const entries = Array.from(map.values()).filter((e) => filters(e.path));
+  entries.sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+  return { entries, merges };
+}
+
+/** 拼接目标路径并确保没有越界写出 --to 之外 */
+function safeJoin(root, rel) {
+  const base = path.resolve(root);
+  const full = path.resolve(base, rel);
+  const inside = path.relative(base, full);
+  if (inside.startsWith('..') || path.isAbsolute(inside)) {
+    throw new CliError(`目标路径越界（拒绝写入 --to 之外）：${rel}`);
+  }
+  return full;
+}
+
+const KB = (n) => `${(n / 1024).toFixed(1)} KB`;
+
+function printPlan(plan, ctx) {
+  const rows = plan.map((item) => [
+    { add: 'A 新增', modify: 'M 修改', delete: 'D 删除', rename: 'R 改名' }[item.action],
+    item.path,
+    item.size != null ? KB(item.size) : '-',
+    item.reason,
+  ]);
+  log.plain('');
+  log.plain(log.renderTable(['动作', '文件', '大小', '说明'], rows));
+}
+
+function planEntries(entries, ctx) {
+  const plan = [];
+  for (const e of entries) {
+    const target = safeJoin(ctx.toDir, e.path);
+    const exists = fs.existsSync(target);
+    if (e.action === 'delete') {
+      const reason = e.renamedTo
+        ? `已改名为 ${e.renamedTo}`
+        : (ctx.del ? '删除目标文件' : '跳过（未加 --delete）');
+      plan.push(Object.assign({}, e, { target, exists, same: false, reason }));
+      continue;
+    }
+    const content = git.buffer(['show', `${e.sha}:${e.path}`]);
+    const same = exists && fs.readFileSync(target).equals(content);
+    let reason;
+    if (same) reason = '内容一致，跳过';
+    else if (!exists) reason = e.action === 'modify' ? '目标不存在，按新增写入' : '新建';
+    else reason = e.action === 'rename' ? '按新路径写入' : '覆盖';
+    plan.push(Object.assign({}, e, { target, content, exists, same, size: content.length, reason }));
+  }
+  return plan;
+}
+
+function writeAtomic(file, buf) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const tmp = `${file}.gfm-tmp-${process.pid}`;
+  fs.writeFileSync(tmp, buf);
+  fs.renameSync(tmp, file);
+}
+
+function backupFile(item, ctx) {
+  if (!ctx.backup) return;
+  const dest = safeJoin(ctx.toDir, path.join('.gfm-backup', ctx.stamp, item.path));
+  fs.mkdirSync(path.dirname(dest), { recursive: true });
+  fs.copyFileSync(item.target, dest);
+}
+
+function applyPlan(plan, ctx) {
+  const stat = { written: 0, deleted: 0, skipped: 0, failed: 0 };
+  for (const item of plan) {
+    if (item.action === 'delete') {
+      if (!ctx.del) { stat.skipped += 1; log.warn(`跳过删除 ${item.path}（需要 --delete）`); continue; }
+      if (!item.exists) { stat.skipped += 1; continue; }
+      if (ctx.dryRun) { stat.deleted += 1; log.info(`[dry-run] 删除 ${item.path}`); continue; }
+      backupFile(item, ctx);
+      fs.rmSync(item.target, { force: true });
+      stat.deleted += 1;
+      log.ok(`删除 ${item.path}`);
+      continue;
+    }
+    if (item.same) { stat.skipped += 1; log.debug(`内容一致，跳过 ${item.path}`); continue; }
+    if (ctx.dryRun) { stat.written += 1; log.info(`[dry-run] ${item.exists ? '覆盖' : '新建'} ${item.path} (${KB(item.size)})`); continue; }
+    if (item.exists) backupFile(item, ctx);
+    writeAtomic(item.target, item.content);
+    stat.written += 1;
+    log.ok(`${item.exists ? '覆盖' : '新建'} ${item.path} (${KB(item.size)})`);
+  }
+  return stat;
+}
+
+const EMPTY_TREE = '4b825dc642cb6eb9a060e54bf8d69288fbee4904';
+
+function applyPatchMode(shas, ctx, rawPaths) {
+  const stat = { applied: 0, failed: 0 };
+  for (const sha of shas) {
+    const info = git.commitInfo(sha);
+    const args = ['diff', '--binary', '--no-color', '--no-ext-diff'];
+    if (info.parents.length > 1) args.push('--first-parent');
+    args.push(info.parents[0] || EMPTY_TREE, sha);
+    if (rawPaths.length) args.push('--', ...rawPaths);
+    const patch = git.buffer(args);
+    if (patch.length === 0) { log.debug(`${short(sha)} 没有可用补丁`); continue; }
+    if (ctx.dryRun) { stat.applied += 1; log.info(`[dry-run] apply ${short(sha)} ${info.subject}（${KB(patch.length)}）`); continue; }
+    const res = git.raw(['-c', 'core.autocrlf=false', 'apply', '--binary', '--whitespace=nowarn', '-'], { cwd: ctx.toDir, input: patch });
+    if (res.status === 0) {
+      stat.applied += 1;
+      log.ok(`已应用 ${short(sha)} ${info.subject}`);
+    } else {
+      stat.failed += 1;
+      log.bad(`应用 ${short(sha)} 失败：${res.stderr.toString('utf8').trim()}`);
+      log.info('patch 模式要求目标目录与源 commit 的父版本一致；基线不同请改用 --mode content');
+    }
+  }
+  return stat;
+}
+
+function summarize(stat, ctx) {
+  log.step('结果');
+  if (ctx.mode === 'patch') {
+    log.ok(`应用成功 ${stat.applied} 个 commit${stat.failed ? `，失败 ${stat.failed} 个` : ''}`);
+  } else {
+    log.ok(`写入 ${stat.written} 个，删除 ${stat.deleted} 个，跳过 ${stat.skipped} 个${stat.failed ? `，失败 ${stat.failed} 个` : ''}`);
+  }
+  if (ctx.backup) log.info(`被覆盖/删除的旧文件已备份到：${path.join(ctx.toDir, '.gfm-backup', ctx.stamp)}`);
+}
+
+function run(opts) {
+  const root = git.findRoot();
+  git.setCwd(root);
+
+  if (!opts.to) {
+    throw new CliError('缺少 --to 参数', '用法：git file-manager sync --commits "A..B" --to <目标目录>');
+  }
+  const mode = opts.mode || 'content';
+  if (!MODES.includes(mode)) throw new CliError(`--mode 只能是 ${MODES.join(' / ')}，收到：${mode}`);
+
+  // 只有给了 --from / --last 才把 commit 限制在该分支可达范围内；
+  // 否则任何能解析到的 commit 都能同步（包括被 rescue 重写掉、但仍在 backup ref 下的原 sha）
+  const useFrom = Boolean(opts.from || opts.last);
+  const fromTip = useFrom
+    ? (opts.from ? git.mustRevParse(opts.from, `--from ${opts.from}`) : git.revParse('HEAD'))
+    : undefined;
+  const { shas } = parseCommitSpec(opts.commits, {
+    last: opts.last,
+    inclusive: opts.inclusive,
+    fromTip,
+    fromLabel: opts.from || 'HEAD',
+  });
+
+  const include = toList(opts.paths);
+  const exclude = toList(opts.exclude);
+  const incMatch = makeMatcher(include);
+  const excMatch = makeMatcher(exclude);
+  const filters = (file) => (include.length ? incMatch(file) : true) && !excMatch(file);
+
+  const toDir = path.resolve(process.cwd(), opts.to);
+  const ctx = {
+    toDir,
+    mode,
+    dryRun: Boolean(opts.dryRun),
+    del: Boolean(opts.del),
+    backup: Boolean(opts.backup),
+    stamp: backup.stamp(),
+  };
+
+  log.step('sync 计划');
+  log.info(`目标目录 : ${toDir}`);
+  log.info(`模式     : ${mode}${mode === 'content' ? '（按 commit 时点的内容写入）' : '（把 diff apply 到目标目录）'}`);
+  log.info(`commit   : ${shas.length} 个 -> ${shas.map(short).join(', ')}`);
+  if (include.length) log.info(`--paths  : ${include.join(', ')}`);
+  if (exclude.length) log.info(`--exclude: ${exclude.join(', ')}`);
+
+  if (mode === 'patch') {
+    if (!ctx.dryRun) fs.mkdirSync(toDir, { recursive: true });
+    const stat = applyPatchMode(shas, ctx, include);
+    summarize(stat, ctx);
+    return stat.failed ? 1 : 0;
+  }
+
+  const { entries, merges } = collectChanges(shas, filters);
+  if (merges.length) log.warn(`含 merge commit（${merges.map(short).join(', ')}），只取它与第一父提交的差异`);
+  if (entries.length === 0) {
+    log.warn('这些 commit 里没有匹配的文件改动');
+    return 0;
+  }
+
+  const plan = planEntries(entries, ctx);
+  printPlan(plan, ctx);
+  if (ctx.dryRun) {
+    log.ok('--dry-run：没有写任何文件');
+    return 0;
+  }
+  fs.mkdirSync(toDir, { recursive: true });
+  const stat = applyPlan(plan, ctx);
+  summarize(stat, ctx);
+  return stat.failed ? 1 : 0;
+}
+
+module.exports = { run, collectChanges, makeMatcher, safeJoin };

package/src/commands/undo.js

@@ -0,0 +1,66 @@
+'use strict';
+
+/**
+ * undo —— 把分支指针回滚到最近一次 rescue 开始前。
+ * 备份来自 refs/gfm/backup/<时间戳>/<分支>，被 ref 引用的对象不会被 gc 回收。
+ */
+
+const git = require('../git');
+const log = require('../log');
+const backup = require('../backup');
+const rescue = require('./rescue');
+
+const { CliError } = log;
+
+function printBackups() {
+  const refs = backup.listBackups();
+  if (refs.length === 0) {
+    log.warn('没有任何 backup ref（refs/gfm/backup 为空）');
+    return 0;
+  }
+  log.step('backup refs');
+  log.plain(log.renderTable(
+    ['ref', 'sha', '创建时间'],
+    refs.map((r) => [r.ref, String(r.sha).slice(0, 8), r.date || '']),
+  ));
+  const state = backup.readState();
+  if (state && state.command === 'rescue') {
+    log.plain('');
+    log.info(`最近一次 rescue：${state.phase}  ${state.startedAt}`);
+    log.info(`  ${state.from.name}  ${String(state.from.tip).slice(0, 8)}`);
+    if (state.to) log.info(`  ${state.to.name}  ${String(state.to.tip).slice(0, 8)}`);
+    log.info('回滚：git file-manager undo');
+  }
+  return 0;
+}
+
+function rollbackToRef(ref) {
+  const sha = backup.refSha(ref);
+  if (!sha) throw new CliError(`无法解析 backup ref：${ref}`, '用 git file-manager undo --list 查看可用 ref');
+  const parts = String(ref).split('/');
+  const branch = parts[parts.length - 1];
+  if (!git.refExists(`refs/heads/${branch}`)) {
+    throw new CliError(`backup ref 对应的分支不存在：${branch}`);
+  }
+  if (!git.isClean()) throw new CliError('工作区不干净，无法回滚', '先 git checkout -- . 或 git stash');
+  const cur = git.currentBranch();
+  if (cur === branch) git.checkout(branch, { detach: true });
+  git.setBranch(branch, sha);
+  git.checkout(branch);
+  log.ok(`${branch} -> ${String(sha).slice(0, 8)}`);
+  return 0;
+}
+
+function run(opts) {
+  git.setCwd(git.findRoot());
+  if (opts.list) return printBackups();
+  if (opts.ref) return rollbackToRef(opts.ref);
+
+  const state = backup.readState();
+  if (!state || state.command !== 'rescue') {
+    throw new CliError('没有可以撤销的 rescue 现场', '用 git file-manager undo --list 查看历史 backup ref');
+  }
+  return rescue.abortRescue();
+}
+
+module.exports = { run, printBackups };

package/src/commitSpec.js

@@ -0,0 +1,122 @@
+'use strict';
+
+/**
+ * commit 表达式解析。支持：
+ *   "A..B"          区间（默认含左端 A；加 --exclusive 则按 git 语义不含 A）
+ *   "A,B,C"         逐个列举
+ *   "A..B,C,D..E"   任意混用
+ *   --last N        从 --from 分支顶端往回数 N 个
+ * 结果统一按拓扑顺序（旧 -> 新）排序并去重。
+ */
+
+const git = require('./git');
+const { CliError } = require('./log');
+
+function splitTerms(spec) {
+  return String(spec || '').split(',').map((s) => s.trim()).filter(Boolean);
+}
+
+function expandRange(term, inclusive) {
+  const idx = term.indexOf('..');
+  const left = term.slice(0, idx) || 'HEAD';
+  const right = term.slice(idx + 2) || 'HEAD';
+  const list = git.lines(['rev-list', '--reverse', `${left}..${right}`]);
+  if (inclusive) {
+    const leftSha = git.revParse(left);
+    if (leftSha && !list.includes(leftSha)) list.unshift(leftSha);
+  }
+  return list;
+}
+
+function topoSort(shas) {
+  const metas = new Map(shas.map((s) => [s, git.commitInfo(s)]));
+  return shas.slice().sort((a, b) => {
+    if (a === b) return 0;
+    if (git.isAncestor(a, b)) return -1;
+    if (git.isAncestor(b, a)) return 1;
+    const ta = metas.get(a).time;
+    const tb = metas.get(b).time;
+    return ta - tb || (a < b ? -1 : 1);
+  });
+}
+
+/**
+ * @param {string} spec    表达式；与 last 二选一
+ * @param {object} opts    { last, inclusive, fromTip, fromLabel }
+ * @returns {{ shas: string[], terms: string[] }}
+ */
+function parseCommitSpec(spec, opts = {}) {
+  const { last, inclusive = true, fromTip, fromLabel } = opts;
+  if (!last && !spec) {
+    throw new CliError('缺少 commit 参数', '用 --commits "A..B" 或 --commits "A,B,C"，也可以用 --last N');
+  }
+
+  const terms = [];
+  const picked = new Set();
+
+  if (last) {
+    if (!fromTip) throw new CliError('--last 需要知道起点分支', '请同时给出 --from <分支>');
+    const n = Number(last);
+    if (!Number.isInteger(n) || n <= 0) throw new CliError(`--last 需要正整数，收到：${last}`);
+    const recent = git.lines(['rev-list', `-n`, String(n), fromTip]);
+    if (recent.length === 0) throw new CliError(`分支 ${fromLabel || fromTip} 上没有任何 commit`);
+    for (const sha of recent) picked.add(sha);
+    terms.push(`--last ${n}`);
+  } else {
+    for (const term of splitTerms(spec)) {
+      terms.push(term);
+      if (term.includes('...')) {
+        throw new CliError(`不支持三点范围：${term}`, '三点范围的含义容易误读，请改用 A..B');
+      }
+      if (term.includes('..')) {
+        for (const sha of expandRange(term, inclusive)) picked.add(sha);
+      } else {
+        const sha = git.revParse(term);
+        if (!sha) throw new CliError(`无法解析为 commit：${term}`);
+        picked.add(sha);
+      }
+    }
+  }
+
+  if (picked.size === 0) {
+    const shown = terms.length ? terms.join(' ') : JSON.stringify(String(spec || ''));
+    throw new CliError(
+      `--commits 没有解析出任何 commit（收到：${shown}）`,
+      '常见原因：shell 变量没展开或已失效（PowerShell 的 $c1 不跨会话保留）。用 git log --oneline 或 git rev-parse <ref> 重新取 sha，也可以直接用 A..B / HEAD~3 这类表达式',
+    );
+  }
+
+  let ordered;
+  if (fromTip) {
+    const all = git.lines(['rev-list', '--reverse', fromTip]);
+    const allSet = new Set(all);
+    const missing = Array.from(picked).filter((s) => !allSet.has(s));
+    if (missing.length) {
+      throw new CliError(
+        `以下 commit 不在分支 ${fromLabel || fromTip} 上：\n  ${missing.map(short).join('\n  ')}`,
+        '请用 --from 指定正确的分支，或检查 commit 是否已被重写',
+      );
+    }
+    ordered = all.filter((s) => picked.has(s));
+  } else {
+    ordered = topoSort(Array.from(picked));
+  }
+
+  return { shas: ordered, terms };
+}
+
+const short = (sha) => String(sha).slice(0, 8);
+
+/** "abcd1234 subject" —— 用于打印计划 */
+function describe(sha) {
+  const info = git.commitInfo(sha);
+  return `${short(sha)} ${info.subject}`;
+}
+
+/** 把连续 commit 折叠成 "a..b" 形式的展示串 */
+function summarize(shas) {
+  if (shas.length === 0) return '(空)';
+  return `${short(shas[0])} .. ${short(shas[shas.length - 1])}（${shas.length} 个）`;
+}
+
+module.exports = { parseCommitSpec, topoSort, describe, short, summarize };

package/src/git.js

@@ -0,0 +1,194 @@
+'use strict';
+
+/**
+ * git 命令封装。所有调用都走 spawnSync，不引第三方依赖：
+ * 参数数组直接传，不经过 shell，路径/中文/空格都安全。
+ */
+
+const { spawnSync } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+const log = require('./log');
+
+const { CliError } = log;
+
+let cwd = process.cwd();
+
+function setCwd(dir) { cwd = dir; }
+function getCwd() { return cwd; }
+
+/** 底层执行，返回 spawnSync 结果（stdout/stderr 为 Buffer） */
+function raw(args, opts = {}) {
+  const where = opts.cwd || cwd;
+  log.debug(`git ${args.join(' ')}   (cwd: ${where})`);
+  const res = spawnSync('git', args, {
+    cwd: where,
+    input: opts.input,
+    windowsHide: true,
+    maxBuffer: 512 * 1024 * 1024,
+  });
+  if (res.error) {
+    throw new CliError(`无法执行 git：${res.error.message}`, '请确认 git 已安装并在 PATH 中');
+  }
+  return res;
+}
+
+/** 执行并校验退出码；allowFail 时返回结果交给调用方判断 */
+function run(args, opts = {}) {
+  const res = raw(args, opts);
+  if (res.status !== 0 && !opts.allowFail) {
+    const stderr = res.stderr.toString('utf8').trim();
+    throw new CliError(`git ${args.join(' ')} 执行失败：${stderr ? `\n${stderr}` : '(无错误输出)'}`);
+  }
+  return { status: res.status, stdout: res.stdout, stderr: res.stderr };
+}
+
+const text = (args, opts) => run(args, opts).stdout.toString('utf8').trim();
+const buffer = (args, opts) => run(args, opts).stdout;
+const check = (args, opts) => raw(args, opts).status === 0;
+
+function lines(args, opts) {
+  const out = text(args, opts);
+  if (!out) return [];
+  return out.split('\n').map((s) => s.replace(/\r$/, ''));
+}
+
+function findRoot(dir = cwd) {
+  const res = raw(['rev-parse', '--show-toplevel'], { cwd: dir });
+  if (res.status !== 0) {
+    throw new CliError(`当前目录不是 git 仓库：${dir}`);
+  }
+  return res.stdout.toString('utf8').trim();
+}
+
+const gitDir = () => text(['rev-parse', '--absolute-git-dir']);
+
+function revParse(ref) {
+  const res = raw(['rev-parse', '--verify', '--quiet', `${ref}^{commit}`]);
+  if (res.status !== 0) return null;
+  return res.stdout.toString('utf8').trim();
+}
+
+function mustRevParse(ref, label) {
+  const sha = revParse(ref);
+  if (!sha) throw new CliError(`无法解析为 commit：${label || ref}`);
+  return sha;
+}
+
+/** 当前分支名；detached HEAD 返回 null */
+function currentBranch() {
+  const name = text(['rev-parse', '--abbrev-ref', 'HEAD']);
+  return name === 'HEAD' ? null : name;
+}
+
+const refExists = (ref) => check(['rev-parse', '--verify', '--quiet', ref]);
+const isAncestor = (a, b) => check(['merge-base', '--is-ancestor', a, b]);
+const isClean = () => text(['status', '--porcelain']).length === 0;
+const hasConflicts = () => text(['ls-files', '-u']).length > 0;
+
+/** 是否有进行中的 rebase / merge / cherry-pick */
+function inProgress() {
+  const dir = gitDir();
+  const marks = [
+    ['rebase-merge', 'rebase'],
+    ['rebase-apply', 'rebase'],
+    ['CHERRY_PICK_HEAD', 'cherry-pick'],
+    ['MERGE_HEAD', 'merge'],
+    ['REVERT_HEAD', 'revert'],
+  ];
+  const active = [];
+  for (const [file, name] of marks) {
+    if (fs.existsSync(path.join(dir, file))) active.push(name);
+  }
+  return Array.from(new Set(active));
+}
+
+function commitInfo(sha) {
+  const out = text(['show', '-s', '--format=%H%n%P%n%an%n%ct%n%s', sha]);
+  const [head, parents, author, ctime, ...rest] = out.split('\n');
+  return {
+    sha: head,
+    parents: parents.trim() ? parents.trim().split(' ') : [],
+    author,
+    time: Number(ctime) || 0,
+    subject: rest.join('\n'),
+  };
+}
+
+/** 包含该 commit 的远端分支（用于提示「源分支已推送，需要 force-push」） */
+function remoteBranchesContaining(ref) {
+  return lines(['branch', '-r', '--contains', ref])
+    .map((s) => s.trim())
+    .filter((s) => s && !s.includes('->'));
+}
+
+function checkout(ref, opts = {}) {
+  const args = ['checkout', '--quiet'];
+  if (opts.detach) args.push('--detach');
+  args.push(ref);
+  return run(args);
+}
+
+const setBranch = (name, sha) => run(['branch', '-f', name, sha]);
+
+/**
+ * 单步 cherry-pick。返回：
+ *   { ok: true }                        成功
+ *   { ok: false, conflict: true, ... }  有冲突，等待人工解决
+ *   { ok: false, empty: true }          内容已存在（空提交），已自动跳过
+ */
+function cherryPick(sha) {
+  const res = raw(['cherry-pick', '--no-edit', sha]);
+  if (res.status === 0) return { ok: true };
+  const stderr = res.stderr.toString('utf8');
+  if (hasConflicts()) return { ok: false, conflict: true, sha, stderr };
+  if (/empty|nothing to commit|--allow-empty/i.test(stderr)) {
+    raw(['cherry-pick', '--skip']);
+    return { ok: false, empty: true, sha, stderr };
+  }
+  throw new CliError(`git cherry-pick ${sha} 失败：\n${stderr.trim()}`);
+}
+
+function cherryPickContinue() {
+  const res = raw(['cherry-pick', '--continue', '--no-edit']);
+  if (res.status === 0) return { ok: true };
+  const stderr = res.stderr.toString('utf8');
+  if (hasConflicts()) return { ok: false, conflict: true, stderr };
+  throw new CliError(`git cherry-pick --continue 失败：\n${stderr.trim()}`);
+}
+
+const cherryPickAbort = () => raw(['cherry-pick', '--abort']);
+
+const configGet = (key) => {
+  const res = raw(['config', '--get', key]);
+  return res.status === 0 ? res.stdout.toString('utf8').trim() : null;
+};
+
+module.exports = {
+  setCwd,
+  getCwd,
+  raw,
+  run,
+  text,
+  lines,
+  buffer,
+  check,
+  findRoot,
+  gitDir,
+  revParse,
+  mustRevParse,
+  currentBranch,
+  refExists,
+  isAncestor,
+  isClean,
+  hasConflicts,
+  inProgress,
+  commitInfo,
+  remoteBranchesContaining,
+  checkout,
+  setBranch,
+  cherryPick,
+  cherryPickContinue,
+  cherryPickAbort,
+  configGet,
+};