keep-git-work-recoverable

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Keep Git Work Recoverable

确保Git工作可恢复

Core principle. Nothing that cannot be recovered is destroyed to make a command succeed.

The refusal you are looking at is the tool protecting work that exists nowhere else.
The weight sits in Tag every claim that rests on the remote. Every removal downstream rests on whether that tag was honest.
You opened this in the middle of something. This is how to do that work, not a replacement for it. Name what you were doing before you start, and return to it when this is done.

核心原则。为了让命令执行成功，绝不会销毁任何无法恢复的内容。

你看到的执行失败提示，是工具在保护仅存于本地的工作内容。
重点在于为所有基于远程仓库的声明添加标签。 后续的每一项删除操作都取决于该标签是否准确。
你是在某项操作进行到一半时打开本指南的。 本指南是完成该操作的方法，而非替代操作。请先说明你之前正在执行的操作，完成当前步骤后再回到原操作。

A refused command is information

执行失败的命令是一种信息

Retrying it unchanged is the failure this skill exists to prevent. The second attempt fails for the reason the first one already gave you.
Classify the state, then make the one legal move from it.
Where no legal move exists without discarding someone's work, the decision leaves you. It goes to the human.

重复执行相同命令是本技能旨在避免的错误。 第二次失败的原因与第一次完全相同。
先归类当前状态，再执行该状态下唯一合法的操作。
若不存在不丢弃任何工作内容的合法操作，则该决策交由用户决定。 最终由人工判断。

What is yours to do, and what is the human's

你的职责与用户的职责

You MUST NOT discard work to make an operation succeed.
Each of these is the human's decision.
- Committing uncommitted changes.
- Parking them.
- Abandoning them.
- Deleting a branch.
- Removing a workspace holding tracked edits.
- Rewriting history.
- Forcing anything at a remote.
You MAY read state freely. You MAY create a workspace or a branch when the task needs one.
Everything that destroys is proposed with what would be lost named. It stops there.
Where the human approves a history rewrite, record the tree hash of the original tip first. Compare it after.
- Same tree. The content survived and only the history moved.
- A different tree. Something was lost. It is found now rather than after the push.

绝对不得为了让操作成功而丢弃工作内容。
以下决策均由用户做出：
- 提交未提交的变更。
- 暂存未提交的变更。
- 放弃未提交的变更。
- 删除分支。
- 删除包含已追踪编辑内容的工作区。
- 重写历史。
- 对远程仓库执行任何强制操作。
你可自由读取仓库状态。 当任务需要时，你可创建工作区或分支。
所有具有破坏性的操作都需明确说明会丢失的内容。 仅提出建议，不执行操作。
若用户批准重写历史，请先记录原始分支顶端的树哈希值。 操作完成后进行对比。
- 树哈希值相同：内容得以保留，仅历史记录发生变动。
- 树哈希值不同：有内容丢失。需立即找回，而非在推送后再处理。

Establish before acting

操作前先确认状态

Read these from the repository rather than assuming them.

Which checkout this is. The main one, a linked workspace, or a submodule pretending to be one.
Whether a branch is checked out at all. An empty branch name means a detached head.
Which remote is configured, and what the trunk is actually called.
Whether the environment points the tools somewhere other than the current directory.

Get any of these wrong and every later observation describes a different repository.

从仓库中读取以下信息，而非主观假设。

当前是哪个检出环境：主工作区、关联工作区，或是伪装成工作区的子模块。
是否已检出分支：分支名称为空意味着处于detached head状态。
配置的远程仓库是什么，主干分支的实际名称是什么。
环境是否将工具指向当前目录以外的位置。

若以上任何信息判断错误，后续所有观察结果都将对应错误的仓库。

Say which state you are in

说明当前所处状态

Report it every time. Each state licenses only what it names, and acting from a state you have not established is how work that existed nowhere else stops existing.

State	Means	Licenses
`UNLOCATED`	the checkout, the head, or the remote is still unnamed	reading, and nothing that writes
`LOCATED`	all four of the above are read from the repository	inspecting refs, proposing a move
`SECURED`	everything uncommitted is recoverable without this command succeeding	the move that was refused
`CONFIRMED`	the work is observed to exist somewhere it survives this checkout	removing the local copy

No state is reached by assumption. Each one names a reading you performed.
Removal is licensed by
CONFIRMED
alone. The absence of a signal never reaches it.

每次都需报告状态。 每种状态仅允许执行其指定的操作，若在未确认状态的情况下执行操作，可能导致仅存于本地的工作内容丢失。

状态	含义	允许操作
`UNLOCATED`	尚未确定检出位置、HEAD或远程仓库	仅可读取，不可执行任何写入操作
`LOCATED`	已从仓库中读取上述四项信息	检查refs，提出操作建议
`SECURED`	所有未提交内容无需依赖当前命令即可恢复	执行之前被拒绝的操作
`CONFIRMED`	已确认工作内容存在于可在本次检出后保留的位置	删除本地副本

任何状态都需通过实际读取确认，而非主观假设。 每个状态都对应你执行过的一次读取操作。
仅当处于
CONFIRMED
状态时，才允许执行删除操作。信号缺失永远无法达到该状态。

Which rules to read

需遵循的规则

This table is a gate, not a checklist. Match the left column against the refusal you got, or against the state you cannot name.

One rule per row. Enter at the matched row.
The match sets where to start. The claim status sets what you may then assert.
Locating yourself precedes everything else. Every other rule assumes you can name the state you are in.
Removing anything requires positive evidence, never the absence of a signal.
Where the refusal could be either row, read both. Guessing which one produces the illegal move.

If you see...	Read
you cannot say which checkout you are in, whether a branch is checked out, or whether this is a linked workspace at all	`rules/locate-yourself.md`
the task needs a second place to work, or the environment already handed you one	`rules/isolate-or-work-in-place.md`
a switch refused: local changes would be overwritten, or the branch is already checked out somewhere else	`rules/switch-refused.md`
a name will not resolve: it may be remote-only, a tag, a commit, or a typo, and you are about to try it again	`rules/resolve-the-ref.md`
the sync failed, was denied, or never ran, and a claim about the remote depends on it	`rules/stale-refs.md`
a workspace or branch is to be removed, or is believed already merged	`rules/removing-work.md`

Discriminators.

Locate against isolate. Locate answers where you are. Isolate decides whether you should be somewhere else.
Refused against resolve. Refused means the name was found and the move was blocked. Resolve means the name was never found.
Stale refs against removing work. The first downgrades a claim. The second is where an unverified claim does real damage.

Default stance.

Establish where you are before acting. Every later observation depends on it.
Read state freely, and change nothing that cannot be undone.
Hand every destructive move to the human, with what it would cost named.

下表是决策入口，而非检查清单。 将左列内容与你遇到的执行失败提示或无法确定的状态进行匹配。

每行对应一条规则。 从匹配的行进入。
匹配结果决定起始位置。 声明状态决定你可做出的断言。
确定自身位置是所有操作的前提。 其他所有规则都假设你能明确当前所处状态。
删除任何内容都需要确切证据，而非信号缺失。
若执行失败提示可能匹配多行，请阅读所有匹配的规则。 猜测可能导致非法操作。

若你遇到...	请阅读
无法确定当前是哪个检出环境、是否已检出分支，或是否为关联工作区	`rules/locate-yourself.md`
任务需要第二个工作区，或环境已提供了一个工作区	`rules/isolate-or-work-in-place.md`
分支切换被拒绝：本地变更将被覆盖，或分支已在其他位置检出	`rules/switch-refused.md`
名称无法解析：可能仅存在于远程仓库、是标签、提交记录或拼写错误，且你打算再次尝试	`rules/resolve-the-ref.md`
同步失败、被拒绝或从未执行，且有关远程仓库的声明依赖于同步结果	`rules/stale-refs.md`
需删除工作区或分支，或认为该分支已合并	`rules/removing-work.md`

区分要点

定位与隔离的区别：定位回答“你在哪里”，隔离决定“你是否应在其他位置”。
切换被拒绝与名称无法解析的区别：切换被拒绝意味着找到名称但操作被阻止，无法解析意味着从未找到名称。
过期refs与删除工作内容的区别：前者会降低声明的可信度，后者中未验证的声明会造成实际损害。

默认立场

操作前先确定自身位置。 后续所有观察结果都依赖于此。
自由读取状态，不做任何无法撤销的变更。
所有破坏性操作都交由用户决定，并明确说明操作成本。

Tag every claim that rests on the remote

为所有基于远程仓库的声明添加标签

Attach one to every statement about a branch or a remote or a merge.

Observed. A command you ran in this session produced it.
Unverified. It rests on remote state you did not successfully refresh.
- A sync that failed, was denied, or never ran leaves every remote claim unverified.
- That covers "the branch exists" and "it is already merged" and "you are up to date".
Unknown. The state could not be determined at all. Name what would determine it.
An unverified claim is reported as unverified. It is not retried in a loop.
An unverified claim never becomes the basis for removing anything.

每条关于分支、远程仓库或合并的声明都需添加标签。

Observed（已观测）：由你在本次会话中执行的命令生成。
Unverified（未验证）：依赖于未成功刷新的远程仓库状态。
- 同步失败、被拒绝或从未执行，会导致所有关于远程仓库的声明处于未验证状态。
- 这包括“分支存在”“已合并”“已同步至最新状态”等声明。
Unknown（未知）：无法确定状态。说明可确定状态的方法。
未验证的声明需标注为未验证。 不得循环重试。
未验证的声明永远不能作为删除任何内容的依据。

Output contract

输出约定

State        which checkout, which branch or detached, which remote, sync status
Refusal      what was refused and the exact reason the tool gave
Options      each legal move, with what it costs and what it risks losing
Blocked on   the decision that is the human's, stated as a question
Claims       each remote-dependent statement tagged Observed or Unverified

Name the reason a command refused, in the tool's own terms.
"It did not work" is not a state. It is the one report that cannot be acted on.

State        which checkout, which branch or detached, which remote, sync status
Refusal      what was refused and the exact reason the tool gave
Options      each legal move, with what it costs and what it risks losing
Blocked on   the decision that is the human's, stated as a question
Claims       each remote-dependent statement tagged Observed or Unverified

使用工具自身的术语说明命令执行失败的原因。
“操作失败”不是一种状态。 该报告无法作为操作依据。

Follow the names already in use

遵循已有的命名规则

Take the naming from the repository, in this order.

The trunk's real name.
The remote's real name.
The pattern the existing branches and workspace directories already show.

Where nothing is established you SHOULD ask rather than invent a scheme. A second convention beside the first is worse than either.

按以下顺序从仓库中获取命名规则。

主干分支的实际名称。
远程仓库的实际名称。
现有分支和工作区目录已遵循的命名模式。

若未确定任何命名规则，应询问用户而非自行创建方案。 同时存在两种命名规范比单独使用任何一种都更糟糕。

Do not skip this when

以下情况不得跳过本指南

A force flag would make it work. That is the moment this skill is for.
The branch is obviously merged. Squashed work is not an ancestor of the trunk.
You are only cleaning up. Cleanup is where unrecoverable loss happens.
The workspace looks abandoned. Provenance is what tells you, not appearance.

添加强制参数可使操作成功。 此时正是本指南发挥作用的时刻。
分支明显已合并。 被压缩的工作内容并非主干分支的祖先。
你仅在进行清理操作。 清理操作是发生不可恢复损失的高发场景。
工作区看似已被废弃。 需通过来源确认，而非仅凭外观判断。

Routing

规则路由

The table above selects the rule. Read a selected rule in full. Say which one you opened, in one line.
A direct instruction from the user outranks anything here, including a proposal this skill would otherwise leave open.
Judging the content of a change belongs to a review of the diff. This skill only establishes and repairs the state that review runs in.

由上表选择需遵循的规则。 完整阅读选中的规则。用一句话说明你打开了哪条规则。
用户的直接指令优先级高于本指南的任何内容，包括本指南原本会保留的操作建议。
判断变更内容属于差异评审的范畴。 本指南仅用于确定和修复差异评审所需的仓库状态。