Scion 本地建仓、拉分支、比对差异 / 一条命令链跑完最小闭环

第一次用 Scion 做本地仓库操作，卡住的地方往往不是命令本身，而是顺序和状态：建完仓不知道下一步该看什么，改完文件不知道差异为什么没出来，报错之后又分不清是哪一步断的。建议把动作固定成「建仓 → 拉分支 → 比对差异」这条最小链路，每步都留下一个肉眼可见的结果（退出码、状态输出、差异文本），出错时按同样顺序回放，就能把问题定位到具体某一步，而不是笼统地说跑不通。下面所有子命令名和参数都以你本机 scion `--help` 以及对应子命令的 `--help` 输出为准，不同版本的命名可能不一样。

适用场景：第一次在本地跑通 Scion 的建仓、建分支、看差异三步。操作动作：固定顺序执行，每步做完立刻用状态命令确认当前分支与工作区状态。验证方式：命令退出码为 0、状态命令显示的当前分支与预期一致、diff 输出里包含你改动的那一行。风险边界：子命令名与选项以本机帮助输出为准；目录里残留旧仓库元数据会让状态判断失真，必须在建仓前清干净。

选一个空目录，确认没有残留的旧仓库文件

先把工作目录固定下来，再谈建仓。残留的旧仓库文件会带来两种干扰：状态命令显示的是上一轮的分支，或者新仓库根本没法初始化，而报错信息看起来和目录无关。

cd /path/to/workspace    # 换成你自己的空目录
pwd                      # 确认当前位置
ls -la                   # macOS / Linux
dir /a                   # Windows 命令提示符

需要清理的目标通常是这几类：上一轮留下的隐藏元数据目录（常见形态是点开头的 .scion、.git 目录）；锁文件或临时文件（名字里带 .lock 或临时后缀）；只属于旧仓库的本地分支和配置。不要逐个文件去挑，直接删掉整个元数据目录更稳。

清理完成的确认标准有两条：ls -la 的输出里只剩 .、.. 和本次实验用得到的普通文件，看不到任何仓库元数据目录；在该目录执行状态类命令时，返回的是「不是仓库 / 尚未初始化」这类信息，而不是某个旧分支名。第二条比第一条更能说明问题。

建仓并查看初始状态

命令骨架如下，尖括号部分按 `--help` 替换成实际子命令：

scion `--help`                 # 看顶层子命令列表
scion <init> `--help`          # 看初始化子命令的参数
scion <init>                 # 在当前目录建仓
echo $?                      # POSIX shell 看退出码；PowerShell 用 $LASTEXITCODE
scion <status>               # 读当前状态

如果 scion `--help` 里根本没有 init、branch、diff 这类子命令，说明本机的 Scion 只承担生成或脚手架角色，版本控制动作由别的工具接管，这时把本文命令换成对应工具的同类子命令即可，判断顺序不变。

初始化完成后，通常能在目录里看到新增的隐藏元数据目录，可能还有一份默认配置或忽略规则文件，以及一个默认分支的引用。状态命令的输出一般覆盖这几个字段：当前分支或 HEAD 指向、工作区是否干净、已跟踪与未跟踪文件数量、是否有未完成的合并。字段名各版本可能不同，按关键词读即可。这一步的失败信号很直接：退出码非 0，或者目录里没有任何新增项，都说明初始化没有落在你 pwd 看到的那个目录上。

建分支、改一个已知文件、把差异调出来

scion <branch> <分支名>     # 部分工具只创建，不切换
scion <checkout> <分支名>   # 或 switch，以 `--help` 为准
scion <status>               # 确认当前分支已变成 <分支名>

建完分支先看状态，再动文件。不少工具的 branch 只负责创建，切换要另敲一条命令，这里漏掉一步，后面的差异就会落在旧分支上。

修改哪一行最容易验证：用初始化时自动生成的那个说明文件（通常是 README 一类），只改它第一行里的一个词。改动范围越小，diff 里越容易确认这就是刚才改的那一处。不要一次改多行或跨多个文件，那样出问题时反而分不清是工具没识别，还是自己改乱了。

scion <diff>

预期输出形态：先给出被改动的文件路径，再按块列出上下文，旧内容以 - 或 before 侧标记，新内容以 + 或 after 侧标记，并带行号。如果 diff 一条输出都没有，先确认文件是否真的保存了，再确认改动的文件是否位于仓库根目录管辖范围内——这两条比怀疑工具本身更常见。

按链路顺序回放，定位失败发生在哪一步

回放的方法是：把各步拆开，每步只跑一条命令、只读一个信号，出错就停在那一步，不要连着往下敲。每步的判定信号可以按下面这样对：

建仓：退出码为 0，且目录里出现元数据目录；状态命令返回分支信息，而不是「不是仓库」。
建分支与切换：命令退出码为 0，且状态命令里的当前分支从旧名变成新名。这是最容易漏的一环。
改文件与看差异：diff 输出里包含你改动的那一行；没有输出就回头查保存和路径。
退出码查询：POSIX shell 用 echo $?，PowerShell 用 $LASTEXITCODE，要在目标命令的下一条立即执行，中间插别的命令会覆盖它。

常见中断点集中在三处：分支未切换（状态里还是旧分支名）；文件未保存，或者编辑器把内容写到了另一个副本、另一个工作目录；路径写错，比如在子目录里执行了初始化，仓库实际建在子目录，或者 diff 时给了一个不存在的路径。还有一种顺序错误值得单独提：先改文件再建分支，本次改动会被算在旧分支上，看起来像是分支没生效，实际是操作顺序反了。

把可复现的三步写成一份最短操作清单

下面是可直接抄用的一份清单，把尖括号项替换成本机实际的子命令与分支名即可。

# 1) 建仓
cd <空目录> && ls -la          # 预期：看不到 .scion / .git 等元数据目录
scion <init>; echo $?          # 预期：退出码 0，目录新增元数据目录
scion <status>                 # 预期：显示默认分支，工作区干净
# 出错：退出码非 0 或目录无变化 → 重看 pwd 与 init `--help`，别急着建分支

# 2) 建分支并切换
scion <branch> <name>; scion <checkout> <name>; echo $?
scion <status>                 # 预期：当前分支 = <name>
# 出错：分支名没变 → 说明只创建未切换，补一条切换命令

# 3) 改一行并比对
# 编辑 README 第一行的某个词并保存
scion <diff>                   # 预期：输出该文件路径与那一行的 -/+ 对照
# 出错：无输出 → 先查是否保存，再查文件是否在仓库根目录内

把这份清单放在项目外的一份笔记里，比靠记忆可靠。每次只替换三个可变项：空目录路径、分支名，以及以本机帮助输出为准的子命令名。执行时保持一条命令、一个信号的节奏，出错就停在当前步解决，链路自然能跑完。