# @gitkraken/sync-tools 中文文档

规范地址：https://npmcn.com/package/%40gitkraken/sync-tools/

版本：0\.6\.0
npm 元数据更新时间：2026-11-06T17:45:19.019Z
中文译文更新时间：2026-11-16T12:07:02.694Z
软件包许可：SEE LICENSE IN LICENSE

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40gitkraken/sync-tools
原文对照：https://npmcn.com/package/%40gitkraken/sync-tools/?lang=original

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：215 kB，69 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>= 22
- 运行依赖：1 个
- 首次发布：2026-06-18T18:55:51.954Z
- 最新版本发布：2026-11-06T17:45:18.843Z
- 近 30 天下载量：3314（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：22（近 12 个月 22 个）

## 中文简介

运行时-不可知分枝同步管弦:将分枝重新定位或合并到目标上,级联-合成一叠依赖分枝,并撤销.

## 安装

```sh
npm install @gitkraken/sync-tools
```

也可以使用：`pnpm add @gitkraken/sync-tools`、`yarn add @gitkraken/sync-tools`、`bun add @gitkraken/sync-tools`

## README

# @ gitkraken/ 同步工具

运行时- 不可知的管弦乐使 git 树枝保持同步 : rebase **或者说** 将一个分行合并到目标上,连环合成一整棵依附分行的树(“sack”),跳过已经应用的活字,并取消——全部在被隔离的工作树上,这样用户的工作树就永远不会被扰动. 这种隔离覆盖了工作树和分支参考,而不是寄存器:抓取工作树与repo共享 `.git`,所以钩子运行 完全按照它们会 手动运行的再基地(见 [隔离](https://npmcn.com/package/%40gitkraken/sync-tools/#readme-isolation)) (中文(简体) ).

软件包是 **端口和适配器**它从不直接说话。 消费者注入了git端口(以及可选的冲突处理器和隔离提供者);库将每个操作都建在顶上.

## 安装

```sh
pnpm add @gitkraken/sync-tools
```

2.31 (中文(简体) )`--end-of-options`,以及 `rev-parse --path-format=absolute` 用于默认的工作树隔离.

## Git 端口

万事俱备 `SyncGitPort`. 仅使用CLI消费者工具 `exec`数字 :

```ts
import { execFile } from 'node:child_process';
import { promisify } from 'node:util';
import type { SyncGitPort } from '@gitkraken/sync-tools';

const execFileAsync = promisify(execFile);

const cwd = '/path/to/repo';

const git: SyncGitPort = {
  async exec(args, opts) {
    // Forward every option git is given: `signal` (cancellation), `stdin`, and `env`.
    // `env` matters — the library sets e.g. GIT_EDITOR so `rebase --continue` / `commit`
    // never block on an editor. Merge it over the ambient environment, don't replace it.
    const { stdout } = await execFileAsync('git', args, {
      cwd,
      signal: opts?.signal,
      env: { ...process.env, ...opts?.env },
    });
    return stdout;
  },
};
```

Libgit2 消费者(例如 kepler)可以执行高级操作(`rebase`, (中文(简体) ), `revParse`, (中文(简体) ), `mergeHead`,)代替;混合式提供 `exec` 加上目标覆盖。 内部呼叫站点更喜欢提供行动,回到 `exec`,并提升 `SyncGitPortMissingOpError` 当两者都不可用时.

### 何处 `exec` 非可选

`SyncGitOps` 只能模拟有操作的管道 一些切入点到达它过去——堆栈元数据是一个手建对象图(L`hash-object` 编号 : `mktree` 编号 : `commit-tree` 编号 : `cat-file`),取消商店和默认的工作树隔离是相同的——所以它们需要 `exec` 这些行动是:

| 入境点 | `exec` |
| --- | --- |
| `createStack`, (中文(简体) ), `loadStackMeta` | 需要的——读取和写出元数据blob是git管道 |
| `syncStack` | 需要的——级联持续倒数 |
| `undoSync`, (中文(简体) ), `undoSession` | 所需——同一仓库 |
| `syncWorktreePath`, (中文(简体) ), `worktreeIsolationProvider`, (中文(简体) ), `DisposableWorktree` | ——但不在类型中:通过 `IsolationProvider`,其签名不能携带担保 |
| `syncBranch` | 要求,除非 `isolate` 提供者通过,并且总是由 `skipAlreadyApplied` 其他 `'off'` |
| `takeOursHandler`, (中文(简体) ), `takeTheirsHandler` | 所需时间 `ConflictContext.git` |
| `createGitPortConformanceSuite` | 需要的——病例用管道盖起固定装置 |
| `deleteStack`, (中文(简体) ), `listStacks`, (中文(简体) ), `getBranchState`, (中文(简体) ), `getEffectiveParent`, (中文(简体) ), `resumeOperation` | 不需要——单靠行动就够了 |

因此,只操作端口覆盖了单分支同步(有自己的) `isolate` 提供方和冲突处理方),恢复,注销登记和检查;它不能注册堆栈,读取其元数据,级联同步或撤销. 需要的切入点 `exec` 无条件接受 `ExecSyncGitPort` —— 说 `SyncGitPort` 与 `exec` 需要——所以编译器拒绝这些调用站点的只操作端口. 两条有条件的行仍然是道教: `syncBranch` 取决于它给出的选项,以及 `ConflictContext.git` 由任何活跃的隔离提供者构建。 运行时缺失的能力表面 `SyncGitPortMissingOpError`,包括 `skipAlreadyApplied`: 检测是最佳效果 _失败_而不是悄悄地重现每一个承诺.

## 快速启动——同步一个分支

```ts
import { syncBranch, takeTheirsHandler } from '@gitkraken/sync-tools';

// Rebase `feature/api` onto `main` (default strategy), resolving conflicts via the handler.
const result = await syncBranch(git, 'feature/api', 'main', {
  conflictHandler: takeTheirsHandler, // omit to abort on the first conflict
  skipAlreadyApplied: 'squash', // drop commits already squash-merged into main
});
// result: { branch, status: 'synced' | 'up-to-date' | 'failed', previousSha?, newSha?, publishedTo?, reason?, worktreePath? }

// Or merge `main` INTO the branch (a merge commit, no history rewrite, no force-push):
await syncBranch(git, 'feature/api', 'main', { conflictHandler: takeTheirsHandler, strategy: 'merge' });
```

`syncBranch` 工作内容 **任意** - 不需要登记。 复基/相接运行在一个孤立的离散的工作树上,而分行活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活 如果为了做到这一点,必须翻写局部变化,则分行被重接 `SyncError('CHECKOUT_REFRESH_BLOCKED')` 被抛出 —— 同步从不留下高级分支 后面的僵硬的检查.

它没有写任何折叠的明细表 `BranchSyncResult.undoManifestId` 仅由 `syncStack`,所以一个直接 `syncBranch` 电话收到 `undoManifestId: undefined` 即使它重置了树枝。 留着 `previousSha` 如果您想要倒带, 它会返回 .

检查与其父关系相关的分支 :

```ts
import { getBranchState } from '@gitkraken/sync-tools';

const state = await getBranchState(git, 'feature/api', 'main');
// state.state: 'up-to-date' | 'stale' | 'merged' | 'orphaned'
```

## 堆栈-登记和分级-树枝合成

堆栈是一棵树(“森林”),由附属树枝组成:每个树枝记录其母树. 登记一次,然后按照地形顺序(父母先于子女)同步整件事.

```ts
import { createStack, syncStack, undoSession } from '@gitkraken/sync-tools';

await createStack(git, {
  name: 'my-feature',
  branches: [
    { name: 'feature/api',    parent: 'main' },
    { name: 'feature/api-v2', parent: 'feature/api' },
  ],
});

const sync = await syncStack(git, {
  root: 'my-feature',
  conflictHandler: takeTheirsHandler,
  mode: 'parallel',        // independent subtrees concurrently (default 'sequential')
  concurrency: 4,          // cap for 'parallel'
  skipAlreadyApplied: 'squash',
});
// sync: { status: 'completed' | 'partial' | 'cancelled', results: BranchSyncResult[], undoSessionId }

// Undo the entire cascade in one call:
if (sync.undoSessionId) await undoSession(git, sync.undoSessionId);

// Or one branch of it — a per-branch result carries a manifest id, not a session id:
const branch = sync.results.find((r) => r.branch === 'feature/api');
if (branch?.undoManifestId) await undoSync(git, branch.undoManifestId);
```

失败语义: 失败的分支会自行中止并且 **跳过它的子树** (记录为 `skipped` 带有 `reason`);独立子树继续走. 没有任何全球性的回滚——已经存在的分支被保留. A 类 `signal` 中止优雅地停止:飞行中的分支被中止,完成的分支被保存,状态 `cancelled`。 。 。 .

你不必坚持一个堆-通过一个内层森林取而代之,和/或限制级联到子树上:

```ts
// Ad-hoc forest, no refs/gitkraken/stacks/* entity written:
await syncStack(git, { meta: { version: 1, name: 'adhoc', baseBranch: 'main', branches: [...] } });

// Cascade only the subtree rooted at a branch (inclusive):
await syncStack(git, { root: 'my-feature', from: 'feature/api' });
```

## 冲突处理

当一个同步触发冲突时,库中会呼叫消费者的 `ConflictHandler` 与未合并的文件并让它决定。 结果为二进制——消费者拥有内部的一切(AI分辨率,预览,回想,用户提示):

```ts
import type { ConflictHandler } from '@gitkraken/sync-tools';

const handler: ConflictHandler = {
  async handleConflicts(ctx) {
    // ctx: { git, worktreePath?, files, operation: 'rebase'|'merge'|'cherry-pick',
    //        sourceSha, targetSha, refs?, currentCommit?, sourceBranch, targetBranch, ... }
    // resolve files in ctx.git (scoped to wherever the conflict was materialised), then stage them
    return { resolved: true, report: { file: 'a.txt' } }; // or { resolved: false, reason: '...' } to abort this branch
  },
};
```

`ctx.git` 只能携带主动隔离提供者暴露的东西—— `exec` 单在默认脱落的工作树下, 可能是高层行动,没有 `exec` 在一个记忆提供者之下. `ctx.worktreePath` 冲突发生的绝对路径: `syncBranch`消费者自己的支票 `resumeOperation`。当冲突没有文件系统位置(一个内存隔离提供者)或端口无法报告时,它就不存在了,因此从磁盘上读取文件的处理器应该检查而不是假设.

处理者可附加任意 `report` 同步工具按呼号顺序载着它收到的每份关于行动结果的 `conflictReports`数字 : `BranchSyncResult` (每个分支,包括a类之下) `syncStack` 级联)和 `ResumeResult`同步工具的值不透明——从未检查、复制或解释过——因此,一个曾经在自己关闭时隐藏报告并在呼叫后读回报告的处理器可以将报告还给这里. `conflictReports` 未提供结果时缺席a `report`。 。 。 .

`sourceSha` 编号 : `targetSha` 以同步命名, 而非以 git 命名: 哪一个是 git 的 `--ours` 取决于操作。 重基重放源到目标上,所以 **目标** 实值 `--ours`;合并运行在源头,所以 **来源** 实值 `--ours`。这些是树枝的花纹 **在此之前** 操作开始,并固定每起冲突 同步点击.

`refs` 财务报告和审定财务报表 `currentCommit` 描述停站本身: `refs.ours` 是停车站 `HEAD`, (中文(简体) ), `refs.theirs` 行动是对立的,并且 `refs.base` 当可以读取时,是它们的合并基。 两者都重算在每 `handleConflicts` 呼叫,包括停机 `continue` - 所以,不像这样 `sourceSha`编号 :`targetSha`他们追踪着一个重回原位或樱桃选手 从一个重回的承诺转移到另一个. `currentCommit` 命名在此站重播的承诺( n)`sha`附加时 `message` 当端口能够读取它的时候,合并没有这样的承诺,所以 `currentCommit` 正在缺席。 这种呼吁无法解决的任何领域——无法读取的参考文献、没有合并基础、无法读取承诺信息——只是被省略,而不是引起抛出。 如果你通过了同步工具 `ConflictHandler` 开始 `@gitkraken/conflict`解决者, `ctx.refs` 正是形状 `ResolutionContext.refs` 期待着 为了重建,请输入 `@gitkraken/conflict`参考集成检测 `ResolutionContext.detectionRefs = { ours: targetSha, theirs: sourceSha }` 稳定的重建前提示,而不是 `ctx.refs`数字 : `ctx.refs` 移动停止停止,因为再基重放每个承诺,而检测需要两个终点,整个再基正在接通. 合并没有这种区别,因为 `refs` 已经是终点了.

通过它作为 `conflictHandler` 在选项包中——相同选项名称和相同 `abortOnConflict` 默认于 `syncBranch`, (中文(简体) ), `syncStack` 财务报告和审定财务报表 `resumeOperation`。 。 。 .

内置处理器 : `abortOnConflict` (违约), `takeOursHandler`, (中文(简体) ), `takeTheirsHandler` 最后两个阶段 `--ours` 编号 : `--theirs` 因此,他们所守的哪个分支遵循上述规则。 “应用前审查”流程只是解决、显示预览并等待用户决定然后返回的处理器.

## 隔离

默认情况下,每个复基/合并运行在图书馆创建和处理的离散的工作树上(`worktreeIsolationProvider`时,需要 `exec`) (中文(简体) ). 重放记忆的Libgit2消费者通过自己的 `isolate` 提供商所以没有创建工作树:

```ts
import { syncWorktreePath, worktreeIsolationProvider } from '@gitkraken/sync-tools';
// syncBranch(..., { isolate: myInMemoryProvider })   // default is worktreeIsolationProvider

// The path the default provider uses for a branch — same value on every call and across
// processes, for pointing at or reasoning about the directory a sync works in:
const path = await syncWorktreePath(git, 'feature/api');
// <git-common-dir>/sync-tools-worktrees/feature-api-<hash>
```

抓取活树是同一寄存处的普通活树: 它住在地底 `--git-common-dir` 份额 `.git`,因此 `.git/hooks`没有通过 `--no-verify`这样 `pre-rebase`, (中文(简体) ), `post-rewrite`, (中文(简体) ), `pre-commit` 财务报告和审定财务报表 `commit-msg` 同步时开火 就像他们要手动运行 重新定位或合并一样 隔离是指工作树和分行参考,而不是压制整个寄存器的副作用.

分馆认为一半是保证 因为这个图书馆的重设基础 `exec`\- 后端口: `syncBranch` 财务报告和审定财务报表 `syncStack` 更新否 `refs/heads/*` 除了他们出版的,随便什么 `rebase.updateRefs` 设置在仓库、全球或系统配置中。 每一个这样的再基地都使用 `rebase.updateRefs=false` 扎根在git进程上——不是出于谨慎而压制的副作用,而是因为git的版本的设定与同步正在做的事情相冲突. 有了它,Git强制更新 每一个分支指向重播范围,包括正在同步的分支,所以 `syncBranch`比较和游览的发布会输掉一场与git的比赛 `syncStack` 最后,树枝被移出其倒数表。 消费者供应 `rebase` 行动是用来代替的,不是围绕着它,所以没有什么是代表它的,它欠它自己的保证:除了由它命名的外,它没有更新任何参考文件 `source`。这是一项义务 `createGitPortConformanceSuite()` 检查。 例外的是 `resumeOperation` (下方),它完成了一个其他工具的再基准开始 —— git settled that rebase's ref restauring when it write the todo list, 没有库针在 `--continue` 有时间带他们回去.

抓取路径仅从分支名称中衍生出,因此在每个跑道和每个过程中都是一样的. 中跑时被杀死的同步将目录留在磁盘上 **财务报告和审定财务报表** 登记在册 `git worktree list`,以及 `worktree add` 没有超过现有目录的强制级——因此在有人清除之前,分支不能再次同步. 图书馆的字号 而不是通过git's `fatal: '<path>' already exists` 通过: 同步失败 `SyncError('WORKTREE_PATH_OCCUPIED')`,则信息带有路径.

澄清这是你的决定,而不是图书馆的决定——同样的路径是另一个过程中该分支的活同步正在使用的东西,除了一个忙碌的目录之外,这里没有任何东西可以告诉一个被废弃的目录:

```ts
import { listSyncWorktrees, removeSyncWorktree } from '@gitkraken/sync-tools';

// Pass the same options to both calls — e.g. { worktreeDir } if you configured one — so
// removeSyncWorktree judges against the same scratch base directory listSyncWorktrees did:
const opts = { worktreeDir };
const scratch = await listSyncWorktrees(git, opts);   // [{ path, branch, prunable }, ...]

// Once you have established that no other sync owns it:
await removeSyncWorktree(git, scratch[0].path, opts); // uncommitted work included
```

`removeSyncWorktree` 拒绝任何路径 `isSyncWorktreePath(git, path)` 无法识别 `SyncError('INVALID_OPTIONS')` 而不删除任何内容:只有刮痕底部的直生子,拼写时没有沿途的任何横断面,是本套件的其中之一,所以寄存器根,基目录本身,一个被嵌入更深层的兄弟姐妹和任何事物都遭到拒绝——这是一个路径形状规则,而不是一个注册查询,因此它也去除了消费者自己在共享下创建的工作树 `worktreeDir`。 。 。 . `removeSyncWorktree` 然后超越了路径形状规则,解决了路径本身,在它不真正直接坐落在刮痕底部时拒绝它——因此植入于叶子上,指向别处的同系物被拒绝而不是遵循. `isSyncWorktreePath` 仅保留路径形状的上游:它必须回答路径问题,但目前还没有产生任何东西,因此它无法解决任何问题,这就使得 `removeSyncWorktree` 故意将两者更严格. `prunable` 表示目录已经丢失 `worktree add --force` 但是它也为一个只是失去自己的目录而燃烧 `.git` 在内容完好无损的情况下标出标记——一个仍会阻断同步,仍会表面为 `SyncError('WORKTREE_PATH_OCCUPIED')`。 。 。 .

写入自己的提供者需要一个 tsconfig 设置 : `IsolatedRebase` 扩展全局 `AsyncDisposable`,这需要 TypeScript \\\\ 5.2 和 `esnext.disposable` 在你身边 `lib` (此软件包汇编为 `"lib": ["ES2022", "ESNext.Disposable"]`) (中文(简体) ). 没有它,你的供应商失败了 `Cannot find name 'AsyncDisposable'`。 。 。 .

### 保存失败的操作

默认情况下,失败的冲突会中止操作并去掉工作树,重播的承诺会随之丢失. 过 `abortOnFailure: false` 改为 `syncBranch` 保存它们:失败的结果随即携带 `worktreePath`,一个工作树,在工作树中,处理器在失败的站点解决的文件正在重新建立基础或合并。 源枝未发. 写完 `resumeOperation` 在根植于该路径的端口上,自己移动分支 `git update-ref refs/heads/<branch> <newSha> <previousSha>`和去除工作树 `removeSyncWorktree`。或者中止该路径中的操作并删除它。 下一个是工作树 `syncBranch` 同一分支拒绝使用 `WORKTREE_PATH_OCCUPIED`· ; `listSyncWorktrees` 找到剩下的东西 习惯 `isolate` 没有可选选项的提供者 `keep()` 钩子照常处理 结果没有 `worktreePath`。一个被扔出的错误(手推,中止信号)仍然会中止并删除工作树.

### 重放调用选择版本( E)`source`(中文(简体) )

`syncBranch(git, branch, onto, { source, isolate })` 重播 `source` 改为 `refs/heads/<branch>`时 `branch` 保留用于进度事件、默认合并消息和抓取-工作树命名的人造标签。 这是用于审查前的流程,它已经有一个修订要重播(例如,先前的审查结果),并希望它看起来像 `branch`不为它创建丢掉的分枝的提示.

`source` 在建立孤立的工作树之前,一旦解决,实行与下列政策相同的分支政策: `onto`。只有在 `opts.isolate` 声明 `publishesToCustomTarget: true` (例如, `createWorktreeIsolationProvider({ publishTo: ... })`),这样 `source` 无资格 `isolate` 筹集 `SyncError('INVALID_OPTIONS')` 在任何修订得到解决或存储器被触及之前。 这个声明是信任边界,不是检查 `syncBranch` 它相信提供商确实保留 `refs/heads/<branch>` 离开写道. `createWorktreeIsolationProvider` 获得这种信任的途径是,在援引时拒绝 `publishTo` 解析为 `refs/heads/<branch>` (a) 一个手写提供者,宣布该标记本身欠同一担保。 因为 `refs/heads/<branch>` 永远不读, `branch` 无需作为参考. `BranchSyncResult.previousSha` 永远是真实重播的版本 `source` 当一个供给, `refs/heads/<branch>`否则就是小费.

`syncStack` 不接受 `source`它总是重放每个分支自己的小费 所以级联的下个分支有东西可以重放.

## 适用前的审查

默认 `syncBranch` 直接发布到 `refs/heads/<branch>`。通过 `createWorktreeIsolationProvider({ publishTo })` 作为 `isolate` 而不是将结果存放在复议员身上,而让该分会无动于衷,因此,复议员可以在承诺成为分会历史之前检查承诺. 结果报告它降落的地点 `publishedTo` - 打电话的人再也不需要重新评价 `publishTo` 找到参考者:

```ts
import {
  applyPublishedSync,
  createWorktreeIsolationProvider,
  discardPublishedSync,
  syncBranch,
  undoSync,
} from '@gitkraken/sync-tools';

const isolate = createWorktreeIsolationProvider({
  publishTo: (branch) => `refs/sync-tools/review/${branch}`,
});

const result = await syncBranch(git, 'feature/api', 'main', { isolate });
// result.status === 'synced': feature/api is still at result.previousSha, and
// result.publishedTo (refs/sync-tools/review/feature/api) now holds result.newSha.

if (result.status === 'synced' && result.publishedTo) {
  // Inspect result.publishedTo however you like — diff it against the branch, show it to a
  // reviewer — then apply it: fast-forwards feature/api to the reviewed commit, refreshing a
  // checkout that is on it, and records an undo manifest.
  const { undoManifestId } = await applyPublishedSync(git, result);

  // Changed your mind after applying? Undo the branch move (and any checkout it refreshed) like
  // any other sync:
  await undoSync(git, undoManifestId);

  // The review ref itself outlives both apply and undo — clean it up once you're done with it:
  await discardPublishedSync(git, result);
}
```

两次行动都拒绝一个停滞的结果: `applyPublishedSync` 比较和扫描 `refs/heads/<branch>` 从 `result.previousSha` 改为 `result.newSha` 仅在确认后 `result.publishedTo` 仍决心 `result.newSha`,以及 `discardPublishedSync` 删除 `result.publishedTo` 只是当它仍然做。 或分行 `SyncError('BRANCH_HAS_NEW_COMMITS')`,同样的代码 一个普通同步的发布 提高同一种族—— 或复议 拒绝别人更改或删除, 失败的呼叫 而不是默默地做 打电话者从未要求的东西。 预查显示一名真正缺席的裁判(仍在) `SyncError('REVIEW_REF_STALE')`除此以外,它完全不能读到,因为它宣传为潜在的失败,而不是被报告为迟钝。 两项行动都拒绝其结果,即: `publishedTo` 实值 `refs/heads/<branch>` 本身,与 `SyncError('INVALID_OPTIONS')`: 这是真正的分支, 一个普通的同步和没有 `publishTo` (或一个解决回向的提供者)报告的方式完全相同,因此这种结果从未公布供审查,而应用或抛弃它会移动或删除该处自己的历史,而不是停放的审查承诺——a `publishTo` 名称 a _不同_ 分行的裁判员没有受到影响 仍然被接受. `applyPublishedSync` 需求 `exec` (单位:千美元)`ExecSyncGitPort`——坚持"倒行逆施",以同样方式衡量工作树木的清洁性 `syncStack` 在一个级联上, 在触摸到任何裁判之前检查一下, 所以一个港口丢失了它, 而不是在移动分支之后。 两次操作都不删除您的审查参考文件 : `discardPublishedSync` 只有这样,所以一个经过审查但尚未确定的结果可以继续检查,直到你明确应用或放弃它.

`syncStack` 拒绝 `isolate` 配置为 `publishTo` 直接(见 [隔离](https://npmcn.com/package/%40gitkraken/sync-tools/#readme-isolation)() 申请前审查是 `syncBranch` 流动.

## 恢复在建行动

`resumeOperation` 这是上述隔离的明显例外. `syncBranch` 总是在一个孤立的工作树上运行, 并且只移动真正的分支 裁判成功; `resumeOperation` 转而驱动一个再基,合并,或樱桃点 **已经从库外开始** ——通过平地git或一个IDE,目前暂停在冲突中——完成 **到位**在真正的工作树和树枝上 没有孤立的工作树,也没有反动/推倒步骤:自行完成操作(`rebase --continue`, (中文(简体) ), `commit --no-edit`,或 `cherry-pick --continue`消费者已经检查过了.

因此,消费者必须已经知道一项操作正在进行中,并告诉图书馆是哪一种(`'rebase' | 'merge' | 'cherry-pick'`,加任意 `sourceSha`编号 :`targetSha`编号 :`sourceBranch`编号 :`targetBranch` 处理器需要 —— 库不会从 git 状态检测或重建这些 . `ConflictContext.refs`编号 :`currentCommit` 属于例外: 命名 `operation` 足够库本身读取匹配的伪ref(`REBASE_HEAD`, (中文(简体) ), `MERGE_HEAD`,或 `CHERRY_PICK_HEAD`以同样的方式注入它们 `syncBranch` 已经.

```ts
import { resumeOperation, takeTheirsHandler } from '@gitkraken/sync-tools';

// A rebase/merge/cherry-pick is already paused on a conflict in the real repo.
const result = await resumeOperation(git, { operation: 'rebase', conflictHandler: takeTheirsHandler });
// result: { status: 'completed' | 'failed', newSha?, reason? }
```

默认情况下,同样的"从未离开过中操作"的保证适用:任何失败——未解决的冲突,留下冲突已上演的处理器,或出乎意料的错误——在结果(或出错)返回前中止在建操作,留下干净的工作树.

过 `abortOnFailure: false` \* 进行交易,为行动本身提供担保:未解决的冲突随后返回 `{ status: 'failed', reason }` 操作仍在进行,工作树没有被破坏,所以消费者可以检查冲突,用手完成冲突,或者自行终止。 后别有清净. 旗帜只覆盖冲突解决结果——缺失的端口操作,无效选项,或处理器所抛出的错误仍然被抛出,因为否 `ResumeResult` 可以诚实地描述这些.

文件已经设置到 `resumeOperation` 接管被尊重:一个已暂停且没有未合并路径的操作( 用户解决了冲突并运行) `git add`但从不 `--continue`)直接驱动完成,无需咨询处理者.

## 进展活动

过 `onProgress` 接收 `SyncProgressEvent` 流-操作级别(`operation:started`, (中文(简体) ), `operation:conflict-detected`, (中文(简体) ), `operation:conflict-resolved`, (中文(简体) ), `operation:conflict-failed`, (中文(简体) ), `operation:commits-skipped`, (中文(简体) ), `operation:completed`, (中文(简体) ), `operation:aborted`级级(`sync:started`, (中文(简体) ), `sync:branch-started`, (中文(简体) ), `sync:branch-completed`, (中文(简体) ), `sync:branch-up-to-date`, (中文(简体) ), `sync:branch-skipped`, (中文(简体) ), `sync:branch-failed`, (中文(简体) ), `sync:completed`)和堆放寿命周期(`stack:registered`, (中文(简体) ), `stack:deregistered`) (中文(简体) ).

`operation:started` 完全被其中之一关闭 `operation:completed` 或者说 `operation:aborted`,因此一个进度 UI 可以对等它们:一个分支最终不需要再播放完成,一个被拒绝的冲突或一个出乎意料的错误中止,以及任何在同步开始前拒绝同步(一个无法使用的端口,一个无效的回放,一个已经更新的分支)都会输出两个事件. 唯一的例外是 `resumeOperation` 返回时 `failed` 下级 `abortOnFailure: false`,在行动被故意仍在进行中的地方——没有任何东西关闭了溪流,因为没有任何东西关闭了行动. 扔到那条道上仍然会关闭.

## 验证自定义端口

```ts
import { createGitPortConformanceSuite } from '@gitkraken/sync-tools/testing';

for (const testCase of createGitPortConformanceSuite()) {
  // run testCase against your port in your own test runner; it throws on failure
}
```

增加了一些案件作为担保,因此,与早先版本相悖的港口可能会与后来版本相悖。 现在的套房 `rebase` 说明 [隔离](https://npmcn.com/package/%40gitkraken/sync-tools/#readme-isolation) ——它配置 `rebase.updateRefs=true` 并失败执行让分支指向重放区域移动.

套房靠自己过活 `@gitkraken/sync-tools/testing` 切入点,所以它不出现在生产导入的模块图中. 每起案子都需要一次新的回购 至少一次 **和一棵工作树** - 退房、工作树和 `refreshCheckout` 案件在一号线上运行——正在测试的港口必须提供 `exec` ——案例用不涵盖的管道来建立固定装置. 因此,只操作端口必须添加 `exec` 该套间无法告诉你其他图书馆是否在没有端口的情况下接受端口(见 [何处 `exec` 非可选](https://npmcn.com/package/%40gitkraken/sync-tools/#readme-where-exec-is-not-optional)) (中文(简体) ).

## 选项参考

-   `conflictHandler` 解决冲突;默认为 `abortOnConflict` 所有三个入口.
-   `strategy: 'rebase' | 'merge'` 单处; `rebase` (默认)重写历史, `merge` 添加合并承诺( e)`--no-ff`) (中文(简体) ).
-   `mergeMessage` – 合并后输入信件( 主体, 加上空白行后的正文); 默认为 `Merge branch '<onto>' into <branch>`。通过它的时候 `branch` 合并所要记录的不是名称, 例如抓取调试同步运行 。 要求数 `strategy: 'merge'` 绝不能是空白的 `SyncError('INVALID_OPTIONS')` 在任何工作开始前就已经长大了.
-   `skipAlreadyApplied: 'off' | 'squash' | 'squash+subject'` ——跳过特性承诺已经应用到目标上(只重放).
-   `mode: 'sequential' | 'parallel'` + 键 `concurrency` 级联时间安排(`syncStack`) (中文(简体) ). `concurrency` (违约4)要求 `mode: 'parallel'` 和一个整数 qq 1; 其他的都是 `SyncError('INVALID_OPTIONS')` 而不是无声回落.
-   `from` 将级联限制在树下.
-   `isolate` ——隔离机制(默认:去除活树).
-   `source` —— 说 `syncBranch` 仅: 修改以重放 `refs/heads/<branch>`需要; 需要 `isolate` 声明 `publishesToCustomTarget: true`。见 [重放调用选择版本](https://npmcn.com/package/%40gitkraken/sync-tools/#readme-replaying-a-caller-chosen-revision-source)。 。 。 .
-   `abortOnFailure` —— 说 `syncBranch` 财务报告和审定财务报表 `resumeOperation`· ; `false` 使操作失败而非中止。 打开 `syncBranch` 还保留了工作树和名字 `worktreePath`; 见 [保存失败的操作](https://npmcn.com/package/%40gitkraken/sync-tools/#readme-keeping-a-failed-operation)。 。 。 .
-   `previousResolutions` ——每个文件的决议,由呼叫者携带和手交给自己的处理者;同步工具通过它们不受侵犯.
-   `sessionId`, (中文(简体) ), `signal`, (中文(简体) ), `onProgress`。 。 。 .

## 常见问题

### @gitkraken/sync-tools 是什么？

运行时-不可知分枝同步管弦:将分枝重新定位或合并到目标上,级联-合成一叠依赖分枝,并撤销\.

### 如何安装 @gitkraken/sync-tools？

在项目目录运行 npm install @gitkraken/sync-tools，或使用 pnpm add / yarn add / bun add。

### @gitkraken/sync-tools 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @gitkraken/sync-tools 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @gitkraken/sync-tools 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>= 22。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @gitkraken/sync-tools 可以商用吗？

@gitkraken/sync-tools 使用 SEE LICENSE IN LICENSE 许可。许可条款写在包内的独立文件中，请阅读该文件确认可否商用。以上为概括，不构成法律意见，请以许可原文为准。

### @gitkraken/sync-tools 的下载量有多少？

根据 npm 官方下载统计，@gitkraken/sync-tools 在 2026/10/17 – 2026/11/15 这 30 天内被下载 3,314 次，日均约 110 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @gitkraken/sync-tools 还在维护吗？

最新版本 0\.6\.0 发布于 2026/11/07（9 天前）；至今共发布 22 个版本，其中过去 12 个月发布了 22 个；首次发布于 2026/06/19。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。

