科技 · 实用指南
Git 提示“pathspec did not match”？先判断参数究竟是什么
先证明失败参数应当是本地分支、远端分支、提交还是已跟踪路径，再执行 fetch、创建、切换或恢复。
Git 的“pathspec did not match any file(s) known to git”并不会说明你原本想写的是分支、提交还是路径。先保存原命令和仓库状态，因为安全修复取决于参数应落在哪个命名空间。
本指南先做只读 ref、对象、索引与树检查，再考虑抓取、建分支、恢复、重置或清理。仓库根目录或目标不明确时应立即停止。
冻结仓库与原始命令
复制完整命令、错误、工作目录、参数拼写与 shell 引号。更改 ref 或文件前记录 git rev-parse --show-toplevel、git status --short --branch、git remote -v 与 git --version。rev-parse 失败时先确认目录属于目标仓库。
不要先运行 git reset --hard、git clean、宽泛 fetch 或随手创建分支。这些动作会抹掉证据，或用一个新名字掩盖真正意图。
先说明参数本应代表什么
给失败参数标注一种预期类型：已有本地分支、远端分支、新分支、提交或标签、已跟踪路径。checkout 有多种模式，同一词会受 refs、索引、树与 -- 影响。
把标注当作假设，不是修复。像分支的词不证明分支存在，像文件的词不证明它受跟踪，复制的短哈希也不证明本地有对象。
证明本地与远端分支状态
本地分支用 git show-ref --verify refs/heads/NAME，并查看 git branch --all --no-color。远端分支可用 git ls-remote --heads REMOTE NAME 只读查询。记录结果是仅本地、仅远端、两者都有还是都没有。
仅远端存在时，先精确抓取该 ref，再明确建立跟踪分支。确实需要新分支时，只有证明 START 后才用 git switch -c NAME START；不要把建分支当诊断捷径。
检出前先证明提交或标签
用 git rev-parse --verify --end-of-options ARG^{commit} 检查参数能否在当前对象库解析为提交。--end-of-options 可防止前导短横线变成选项。失败只说明本地无法解析，并不证明哪个远端含有它。
抓取前先证明来源：远端 ref、标签、PR ref、子模块记录或另一个仓库。只抓取最小且已验证的 ref；宽泛 fetch 不是任意参数有效的证据。
在索引或指定树中证明路径
用 git ls-files --error-unmatch -- PATH 只读检查当前索引。要查指定提交或树中的路径，用 git ls-tree -r --name-only TREE -- PATH。核对大小写、分隔符、仓库相对拼写与 shell 展开。
明确处理路径时，在它前面放 --：git restore --source=TREE -- PATH；旧流程可用 git checkout TREE -- PATH。分隔符强制路径解释，避免同名分支改变含义。
把证据映射为一个最小动作
已有本地分支就切换；新分支只从已证明起点创建；仅远端分支先精确抓取再跟踪；提交仅在明确需要时分离检出；已跟踪路径用 -- 恢复。拼写或大小写错误应直接纠正。
若所有命名空间都没有该参数，停止并回到名称来源：文档、工单、CI 变量、脚本或同事。缺失本身就是结论；子模块、稀疏检出和浅克隆需要单独证据分支。
验证结果并保留回滚证据
用修正后的明确命令重做原意图，再检查 git status --short --branch、git rev-parse --verify HEAD，以及必要时的 git branch -vv 或 git ls-files --error-unmatch -- PATH。确认 HEAD、上游、索引和工作树都符合预期。
记录创建的 ref、抓取的精确 ref、恢复的路径、旧 HEAD 与命令。只有证明意外分支没有独有工作后才删除；只从已验证的源树恢复文件。
