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

package/src/cli.js

@@ -0,0 +1,183 @@
+#!/usr/bin/env node
+'use strict';
+
+/** git-file-manager 命令行入口 */
+
+const { parseArgs } = require('util');
+const log = require('./log');
+const git = require('./git');
+const rescue = require('./commands/rescue');
+const sync = require('./commands/sync');
+const undo = require('./commands/undo');
+
+const { CliError } = log;
+const VERSION = require('../package.json').version;
+
+const HELP = `
+git-file-manager —— Git 提交流程救火工具
+
+用法
+  git file-manager <命令> [选项]
+  git file-manager rescue --from <分支> --to <分支> <commit id...>
+  git file-manager sync <commit id...> --to <目录>
+
+  提交可以直接写成 commit id（可多个、可混区间）：
+    git file-manager rescue --from develop --to feature a1b2c3d 9f8e7d6
+    git file-manager sync a1b2c3d 9f8e7d6 --to ../another-app
+  也可以写 --commits "a1b2c3d,9f8e7d6"（PowerShell 下逗号必须加引号，否则会被拆成两个参数）
+
+命令
+  rescue   把提交错分支的 commit 剪切到功能分支，并把源分支彻底还原（无多余提交记录）
+  sync     把指定 commit 的文件改动，按原目录结构同步到另一个目录
+  undo     回滚最近一次 rescue；--list 查看历史备份
+
+rescue
+  --from <分支>       错误提交所在的分支（默认当前分支）
+  --to <分支>         目标功能分支（必须是已存在的本地分支）
+  --commits <表达式>  "A..B" 连续 | "A,B,C" 不连续 | "A..B,C,D..E" 混合（区间默认含两端）
+                      也可以直接跟命令后面：rescue --from dev --to feat a1b2c3d 9f8e7d6
+  --last <N>          改取 --from 上最近 N 个 commit
+  --exclusive         区间不含左端 commit（等价 git 的 "A..B" 语义）
+  --base <commit>     源分支重建基点（默认取最早已选中 commit 的父提交）
+  --no-move           只清理源分支，不把 commit 迁到 --to
+  --squash            迁到 --to 时压成一个 commit
+  --allow-dirty       允许在脏工作区执行（默认拒绝）
+  --allow-merges      允许区间/选中里存在 merge commit（默认拒绝）
+  --continue          冲突解决后，接着跑
+  --abort             放弃本次 rescue，把两个分支都还原
+  -n, --dry-run       只打印计划，不动任何东西
+
+sync
+  --commits / --last / --exclusive   同 rescue，含义见上
+  --from <分支>       解析 --last 的起点分支（默认 HEAD）
+  --to <目录>         目标目录（普通目录或另一个工作副本都行）
+  --mode <模式>       content（默认，按 commit 时点的内容写入）| patch（把 diff apply 过去）
+  --paths <a,b,...>   只同步匹配的路径（支持 * ? ** 通配）
+  --exclude <a,b,...> 排除路径
+  --delete            同步删除源 commit 中删掉的文件（默认只报告不删）
+  --backup            覆盖/删除前，把目标旧文件备份到 <to>/.gfm-backup/<时间戳>/
+  -n, --dry-run       只打印计划，不写任何文件
+
+undo
+  --list              列出所有 backup ref 与最近一次操作
+  --ref <ref>         把分支回滚到指定的 backup ref
+
+通用
+  -v, --verbose       打印执行的每条 git 命令
+  -h, --help          显示帮助
+      --version       显示版本
+`;
+
+const OPTIONS = {
+  from: { type: 'string' },
+  to: { type: 'string' },
+  commits: { type: 'string' },
+  last: { type: 'string' },
+  base: { type: 'string' },
+  mode: { type: 'string' },
+  paths: { type: 'string' },
+  exclude: { type: 'string' },
+  ref: { type: 'string' },
+  list: { type: 'boolean' },
+  inclusive: { type: 'boolean' },
+  exclusive: { type: 'boolean' },
+  'no-move': { type: 'boolean' },
+  squash: { type: 'boolean' },
+  'allow-dirty': { type: 'boolean' },
+  'allow-merges': { type: 'boolean' },
+  delete: { type: 'boolean' },
+  backup: { type: 'boolean' },
+  'dry-run': { type: 'boolean', short: 'n' },
+  continue: { type: 'boolean' },
+  abort: { type: 'boolean' },
+  verbose: { type: 'boolean', short: 'v' },
+  help: { type: 'boolean', short: 'h' },
+  version: { type: 'boolean' },
+};
+
+function toOpts(values) {
+  return {
+    from: values.from,
+    to: values.to,
+    commits: values.commits,
+    last: values.last == null ? undefined : Number(values.last),
+    base: values.base,
+    mode: values.mode,
+    paths: values.paths,
+    exclude: values.exclude,
+    ref: values.ref,
+    list: Boolean(values.list),
+    inclusive: !values.exclusive,
+    move: !values['no-move'],
+    squash: Boolean(values.squash),
+    allowDirty: Boolean(values['allow-dirty']),
+    allowMerges: Boolean(values['allow-merges']),
+    del: Boolean(values.delete),
+    backup: Boolean(values.backup),
+    dryRun: Boolean(values['dry-run']),
+    continue: Boolean(values.continue),
+    abort: Boolean(values.abort),
+    verbose: Boolean(values.verbose),
+  };
+}
+
+/** 把 --commits 与直接跟在命令后面的 commit id 合并成一个表达式 */
+function mergeCommitArgs(optionValue, positionalArgs) {
+  const parts = [];
+  const push = (value) => {
+    if (value == null) return;
+    for (const item of (Array.isArray(value) ? value : [value])) {
+      const text = String(item).trim();
+      if (text) parts.push(text);
+    }
+  };
+  push(optionValue);
+  (positionalArgs || []).forEach(push);
+  return parts.length ? parts.join(',') : undefined;
+}
+
+function main(argv) {
+  const { values, positionals } = parseArgs({
+    args: argv,
+    options: OPTIONS,
+    allowPositionals: true,
+    strict: false,
+  });
+
+  const command = positionals[0];
+  const opts = toOpts(values);
+  // 没有用 --commits 时，命令后面直接写的 commit id 也算数（两者可混用）
+  opts.commits = mergeCommitArgs(values.commits, positionals.slice(1));
+  log.setVerbose(opts.verbose);
+
+  if (values.version || command === 'version') {
+    log.plain(VERSION);
+    return 0;
+  }
+  if (!command || values.help || command === 'help') {
+    log.plain(HELP.trim());
+    return 0;
+  }
+
+  if (command === 'rescue') return rescue.run(opts);
+  if (command === 'sync') return sync.run(opts);
+  if (command === 'undo') return undo.run(opts);
+  throw new CliError(`未知命令：${command}`, '见 git file-manager --help');
+}
+
+if (require.main === module) {
+  try {
+    const code = main(process.argv.slice(2));
+    process.exit(typeof code === 'number' ? code : 0);
+  } catch (err) {
+    if (err instanceof CliError) {
+      log.bad(err.message);
+      if (err.hint) log.info(`提示：${err.hint}`);
+      process.exit(1);
+    }
+    log.bad(`未预期的错误：\n${err && err.stack ? err.stack : String(err)}`);
+    process.exit(1);
+  }
+}
+
+module.exports = { main };

package/src/commands/rescue.js

@@ -0,0 +1,403 @@
+'use strict';
+
+/**
+ * rescue —— 把提交错分支的 commit 剪切到功能分支，并把源分支彻底还原。
+ *
+ * 做法（先保住内容，再改历史）：
+ *   ① 把选中的 commit 按旧 -> 新顺序 cherry-pick 到 --to 分支；
+ *   ② 源分支上「回到 base，然后重放没被选中的 commit」，选中的 commit 从历史里消失
+ *      （不是 revert，git log 里干干净净，文件改动也随之回退）。
+ *
+ * 与手工 `git rebase --onto C^ C br` 的区别：不连续的多个 commit、选中的 commit 相邻、
+ * 选中与保留的改动相互重叠，这些情况下 rebase --onto 需要反复手工分段，这里一次做完。
+ */
+
+const git = require('../git');
+const log = require('../log');
+const backup = require('../backup');
+const { parseCommitSpec, describe, short, summarize } = require('../commitSpec');
+
+const { CliError } = log;
+
+const PHASES = {
+  MOVE: 'move',
+  MOVE_CONFLICT: 'move-conflict',
+  REWRITE: 'rewrite',
+  REWRITE_CONFLICT: 'rewrite-conflict',
+  DONE: 'done',
+};
+
+function buildPlan(opts) {
+  const from = opts.from || git.currentBranch();
+  if (!from) {
+    throw new CliError('当前处于 detached HEAD，无法判断源分支', '请用 --from <分支> 显式指定错误提交所在的分支');
+  }
+  if (!opts.to) {
+    throw new CliError('缺少 --to 参数', '用法：git file-manager rescue --from <错的分支> --to <功能分支> --commits "A..B"');
+  }
+  const to = opts.to;
+  if (from === to) throw new CliError(`源分支和目标分支不能相同：${from}`);
+
+  for (const [flag, name] of [['--from', from], ['--to', to]]) {
+    if (!git.refExists(`refs/heads/${name}`)) {
+      throw new CliError(`${flag} 不是本地分支：${name}`, '请先 git switch 创建该分支，或检查分支名拼写');
+    }
+  }
+
+  const fromTip = git.mustRevParse(from, `--from ${from}`);
+  const toTip = git.mustRevParse(to, `--to ${to}`);
+
+  const { shas: commits } = parseCommitSpec(opts.commits, {
+    last: opts.last,
+    inclusive: opts.inclusive,
+    fromTip,
+    fromLabel: from,
+  });
+
+  const merges = commits.filter((s) => git.commitInfo(s).parents.length > 1);
+  if (merges.length && !opts.allowMerges) {
+    throw new CliError(
+      `选中的 commit 里有 merge commit：\n  ${merges.map(short).join('\n  ')}`,
+      'merge commit 无法无损剪切，请改用 --allow-merges（风险自负）或手工处理',
+    );
+  }
+
+  let base;
+  if (opts.base) {
+    base = git.mustRevParse(opts.base, `--base ${opts.base}`);
+  } else {
+    const first = commits[0];
+    if (git.commitInfo(first).parents.length === 0) {
+      throw new CliError(`${short(first)} 是根提交，没有父提交可用作基点`, '请用 --base <commit> 显式指定基点');
+    }
+    base = git.mustRevParse(`${first}^`);
+  }
+  if (commits.includes(base)) throw new CliError(`基点 ${short(base)} 本身在被选中的 commit 里`);
+
+  const rangeCommits = git.lines(['rev-list', '--reverse', `${base}..${fromTip}`]);
+  if (rangeCommits.length === 0) {
+    throw new CliError(`基点 ${short(base)} 到 ${from} 之间没有任何 commit`, '请检查 --base 是否给得太新');
+  }
+  for (const c of commits) {
+    if (!rangeCommits.includes(c)) {
+      throw new CliError(
+        `commit ${short(c)} 不在 ${short(base)}..${from} 区间内，无法从源分支移除`,
+        '请用 --base 指定更早的基点',
+      );
+    }
+  }
+  if (!git.isAncestor(base, fromTip)) {
+    throw new CliError(`基点 ${short(base)} 不是 ${from} 的祖先`);
+  }
+
+  const rangeMerges = git.lines(['rev-list', '--merges', `${base}..${fromTip}`]);
+  if (rangeMerges.length && !opts.allowMerges) {
+    throw new CliError(
+      `基点之后的区间里含 merge commit，重写会丢失合并信息：\n  ${rangeMerges.map(short).join('\n  ')}`,
+      '请用 --base 把基点挪到 merge 之后，或加 --allow-merges（风险自负）',
+    );
+  }
+
+  const picked = new Set(commits);
+  const keep = rangeCommits.filter((s) => !picked.has(s));
+  const already = commits.filter((s) => git.isAncestor(s, toTip));
+
+  return { from, to, fromTip, toTip, commits, base, keep, rangeCommits, already };
+}
+
+function printPlan(plan, opts) {
+  const { from, to, commits, keep, base } = plan;
+  const mode = opts.move === false ? '只清理源分支（--no-move）' : (opts.squash ? '迁移并压成一个 commit（--squash）' : '迁移并保留原 commit');
+
+  log.step('rescue 计划');
+  log.info(`源分支   : ${from} (${short(plan.fromTip)})`);
+  log.info(`目标分支 : ${to} (${short(plan.toTip)})`);
+  log.info(`基点     : ${short(base)}`);
+  log.info(`方式     : ${mode}`);
+
+  if (opts.move !== false) {
+    log.plain(`\n  迁移到 ${to} 的 commit（旧 -> 新，共 ${commits.length} 个）`);
+    log.plain(commits.map((s) => `    + ${describe(s)}`).join('\n'));
+  }
+  log.plain(`\n  将从 ${from} 的历史中移除（共 ${commits.length} 个）`);
+  log.plain(commits.map((s) => `    - ${describe(s)}`).join('\n'));
+  log.plain(`\n  保留并重放（共 ${keep.length} 个）`);
+  log.plain(keep.length ? keep.map((s) => `    = ${describe(s)}`).join('\n') : '    (无)');
+
+  if (plan.already.length) {
+    log.warn(`以下 commit 的内容已在 ${to} 上，cherry-pick 会变成空提交并自动跳过：`);
+    log.plain(plan.already.map((s) => `      ${short(s)}`).join('\n'));
+  }
+
+  const remote = git.remoteBranchesContaining(plan.fromTip);
+  if (remote.length) {
+    log.warn(`${from} 已经推送到远端（${remote.join(', ')}），本次历史重写后必须 force-push：`);
+    log.plain(`      git push --force-with-lease origin ${from}`);
+    log.plain('      协作方需要 git fetch && git reset --hard origin/' + from);
+  }
+  log.plain('');
+}
+
+// ---------------------------------------------------------------- 执行
+
+function guardRepo(opts) {
+  const root = git.findRoot();
+  git.setCwd(root);
+  if (!opts.continue && !opts.abort && !opts.dryRun) {
+    const active = git.inProgress();
+    if (active.length) {
+      throw new CliError(
+        `仓库里有进行中的操作：${active.join(' / ')}`,
+        '先把它收尾（或 git cherry-pick --abort）再执行 rescue',
+      );
+    }
+    if (!git.isClean() && !opts.allowDirty) {
+      throw new CliError('工作区不干净，无法安全剪切历史', '先 git commit / git stash；确实要带着脏工作区跑就加 --allow-dirty');
+    }
+  }
+  return root;
+}
+
+/** 按顺序 cherry-pick；冲突时把进度写进状态文件并返回 */
+function replay(list, startIndex, state, phase) {
+  for (let i = startIndex; i < list.length; i++) {
+    const sha = list[i];
+    const r = git.cherryPick(sha);
+    if (r.conflict) {
+      state.phase = `${phase}-conflict`;
+      state.cursor = i;
+      backup.saveState(state);
+      return { conflict: true, index: i, sha };
+    }
+    if (r.empty) {
+      log.warn(`${short(sha)} 的内容已存在，跳过（不产生空提交）`);
+    } else {
+      const now = git.revParse('HEAD');
+      log.ok(`${describe(sha)}  ->  ${short(now)}`);
+      if (!state.moved) state.moved = [];
+      state.moved.push(now);
+    }
+    state.cursor = i + 1;
+    state.phase = phase;
+    backup.saveState(state);
+  }
+  return { conflict: false };
+}
+
+function conflictFail(stage, sha) {
+  log.plain('');
+  log.bad(`cherry-pick 冲突，流程已暂停在 ${short(sha)}（${stage === PHASES.MOVE ? '迁移到目标分支' : '重写源分支'}阶段）`);
+  log.info('解决冲突后继续：');
+  log.plain('    git add <已解决的文件>');
+  log.plain('    git file-manager rescue --continue');
+  log.info('放弃本次 rescue 并回滚两个分支：');
+  log.plain('    git file-manager rescue --abort');
+  return 1;
+}
+
+function squashMove(plan, state) {
+  log.step(`1) 迁移 commit 到 ${plan.to}（--squash）`);
+  git.checkout(plan.to);
+  for (const sha of plan.commits) {
+    const res = git.raw(['cherry-pick', '--no-commit', '--no-edit', sha]);
+    if (res.status === 0) continue;
+    if (git.hasConflicts()) {
+      throw new CliError(
+        `--squash 迁移在 ${short(sha)} 上发生冲突`,
+        'squash 模式不支持自动续跑：请手工解决冲突并 git commit，或改用非 squash 模式重来',
+      );
+    }
+    const err = res.stderr.toString('utf8');
+    if (/empty|nothing to commit/i.test(err)) {
+      git.raw(['cherry-pick', '--skip']);
+      continue;
+    }
+    throw new CliError(`git cherry-pick --no-commit ${short(sha)} 失败：\n${err.trim()}`);
+  }
+  const last = plan.commits[plan.commits.length - 1];
+  git.run(['commit', '--no-edit', '-C', last]);
+  const now = git.revParse('HEAD');
+  log.ok(`${plan.commits.length} 个 commit 已压成 ${short(now)}`);
+  state.moved = [now];
+  state.cursor = plan.commits.length;
+  backup.saveState(state);
+}
+
+function doMove(plan, state, opts) {
+  if (opts.move === false) {
+    log.step('1) 跳过迁移（--no-move）');
+    return 0;
+  }
+  if (opts.squash) {
+    squashMove(plan, state);
+    return 0;
+  }
+  log.step(`1) 迁移 commit 到 ${plan.to}`);
+  git.checkout(plan.to);
+  const r = replay(plan.commits, 0, state, PHASES.MOVE);
+  if (r.conflict) return conflictFail(PHASES.MOVE, r.sha);
+  return 0;
+}
+
+function finishRewrite(plan, state, opts) {
+  const newTip = git.revParse('HEAD');
+  git.setBranch(plan.from, newTip);
+  git.checkout(plan.from);
+  state.phase = PHASES.DONE;
+  state.newTip = newTip;
+  state.finishedAt = new Date().toISOString();
+  backup.saveState(state);
+
+  log.step('完成');
+  log.ok(`${plan.from}: ${short(plan.fromTip)} -> ${short(newTip)}（历史已重写，选中的 commit 已从历史中消失）`);
+  if (opts.move !== false) log.ok(`${plan.to}: ${short(plan.toTip)} -> ${short(git.revParse(plan.to))}`);
+  log.plain('');
+  log.info('后续动作：');
+  log.plain(`    git switch ${plan.to}          # 检查迁移过去的提交`);
+  const remote = git.remoteBranchesContaining(plan.fromTip);
+  if (remote.length) log.plain(`    git push --force-with-lease origin ${plan.from}`);
+  log.plain(`    git push origin ${plan.to}`);
+  log.plain('');
+  log.info('撤销本次操作：git file-manager undo');
+  return 0;
+}
+
+function rewriteSource(plan, state, opts, startIndex = 0) {
+  log.step(`2) 重写源分支 ${plan.from}`);
+  state.phase = PHASES.REWRITE;
+  state.cursor = startIndex;
+  backup.saveState(state);
+  git.checkout(plan.base, { detach: true });
+  const r = replay(plan.keep, startIndex, state, PHASES.REWRITE);
+  if (r.conflict) return conflictFail(PHASES.REWRITE, r.sha);
+  return finishRewrite(plan, state, opts);
+}
+
+function execute(plan, opts) {
+  const id = backup.stamp();
+  const state = {
+    command: 'rescue',
+    id,
+    startedAt: new Date().toISOString(),
+    phase: PHASES.MOVE,
+    cursor: 0,
+    from: { name: plan.from, tip: plan.fromTip, backup: backup.createRef(plan.from, plan.fromTip, id) },
+    to: { name: plan.to, tip: plan.toTip, backup: backup.createRef(plan.to, plan.toTip, id) },
+    commits: plan.commits,
+    keep: plan.keep,
+    base: plan.base,
+    moved: [],
+  };
+  backup.saveState(state);
+  log.info(`安全网（backup ref）：${state.from.backup}`);
+
+  const step1 = doMove(plan, state, opts);
+  if (step1 !== 0) return step1;
+  return rewriteSource(plan, state, opts, 0);
+}
+
+function planFromState(state) {
+  return {
+    from: state.from.name,
+    fromTip: state.from.tip,
+    to: state.to.name,
+    toTip: state.to.tip,
+    commits: state.commits,
+    keep: state.keep,
+    base: state.base,
+    already: [],
+  };
+}
+
+function continueRescue(opts) {
+  const state = backup.readState();
+  if (!state || state.command !== 'rescue') throw new CliError('没有可以续跑的 rescue 现场');
+  if (state.phase === PHASES.DONE) {
+    log.ok('上一次 rescue 已经完成，无需续跑');
+    return 0;
+  }
+
+  const plan = planFromState(state);
+  const active = git.inProgress();
+  let cursor = state.cursor || 0;
+  const inRewrite = state.phase === PHASES.REWRITE || state.phase === PHASES.REWRITE_CONFLICT;
+  const list = inRewrite ? state.keep : state.commits;
+
+  if (active.includes('cherry-pick')) {
+    if (git.hasConflicts()) {
+      throw new CliError('仍有未解决的冲突', '先把冲突文件 git add 进来，再执行 rescue --continue');
+    }
+    const r = git.cherryPickContinue();
+    if (r.conflict) return conflictFail(inRewrite ? PHASES.REWRITE : PHASES.MOVE, list[cursor] || '');
+    log.ok(`冲突已解决并提交：${short(list[cursor])}`);
+    cursor += 1;
+    state.cursor = cursor;
+    backup.saveState(state);
+  } else if (state.phase.endsWith('-conflict')) {
+    log.warn('没有检测到进行中的 cherry-pick（可能你已经手工提交），按状态文件继续');
+    cursor += 1;
+    state.cursor = cursor;
+    backup.saveState(state);
+  }
+
+  if (inRewrite) {
+    const r = replay(plan.keep, cursor, state, PHASES.REWRITE);
+    if (r.conflict) return conflictFail(PHASES.REWRITE, r.sha);
+    return finishRewrite(plan, state, opts);
+  }
+  const r = replay(plan.commits, cursor, state, PHASES.MOVE);
+  if (r.conflict) return conflictFail(PHASES.MOVE, r.sha);
+  return rewriteSource(plan, state, opts, 0);
+}
+
+/** 把分支指针还原到 rescue 开始前（backup ref 记录的 sha） */
+function restoreFromState(state) {
+  const cur = git.currentBranch();
+  if (cur === state.from.name || cur === state.to.name) {
+    git.checkout(state.from.tip, { detach: true });
+  }
+  git.setBranch(state.from.name, state.from.tip);
+  git.setBranch(state.to.name, state.to.tip);
+  git.checkout(state.from.name);
+}
+
+function abortRescue() {
+  const state = backup.readState();
+  if (!state || state.command !== 'rescue') {
+    throw new CliError('没有可以回滚的 rescue 现场', '用 git file-manager undo --list 查看历史备份');
+  }
+  if (git.inProgress().includes('cherry-pick')) git.cherryPickAbort();
+  if (!git.isClean()) {
+    throw new CliError('工作区不干净，无法回滚', '先处理掉未提交的改动（git checkout -- . 或 git stash）再执行 --abort');
+  }
+  restoreFromState(state);
+  backup.clearState();
+  log.step('已回滚');
+  log.ok(`${state.from.name} -> ${short(state.from.tip)}`);
+  log.ok(`${state.to.name} -> ${short(state.to.tip)}`);
+  return 0;
+}
+
+function run(opts) {
+  guardRepo(opts);
+  if (opts.abort) return abortRescue(opts);
+  if (opts.continue) return continueRescue(opts);
+
+  const pending = backup.readState();
+  if (pending && pending.command === 'rescue' && pending.phase !== PHASES.DONE) {
+    throw new CliError(
+      `上一次 rescue 停在 ${pending.phase}，还没有收尾`,
+      '先执行 git file-manager rescue --continue 或 --abort',
+    );
+  }
+
+  const plan = buildPlan(opts);
+  printPlan(plan, opts);
+  if (opts.dryRun) {
+    log.ok('--dry-run：没有改动任何东西');
+    return 0;
+  }
+  return execute(plan, opts);
+}
+
+module.exports = { run, continueRescue, abortRescue, buildPlan, restoreFromState, PHASES };