Git pathspec 精确选文件：加了引号和双横线，路径仍可能被当成模式
仓库里同时有 report[1].txt 和 report1.txt，给文件名加上引号再交给 Git，结果仍可能选中后者。原因是命令经历了两层解释：shell 先处理参数，Git 再按 pathspec 规则选择路径。引号保护了第一层，并不会自动关闭第二层的模式匹配。
双横线用于把后面的路径参数与选项或版本参数分开，也不表示每个字符都按字面理解。需要精确指向带特殊字符的名字时，应使用字面路径规则。要选一组文件时，则明确选择 glob、根目录锚点和排除条件，别把两种意图混在一起。
从只读列举开始验证选择范围
下面保存为 demo.sh，用 Bash 和 Git 运行。脚本创建全新的临时仓库，只把演示文件加入索引，不创建提交。所有选择都通过只读的 ls-files 显示，并用断言核对；在把类似规则用于暂存、恢复等操作之前，先照这种方式预览。
例子还切到 docs 子目录，使用 top 把匹配起点固定在仓库根部，并用 full-name 让输出保持根目录相对路径。这样可以把“在哪儿执行”和“想选哪些文件”分开观察，避免依赖当前工作目录碰巧正确。
AI概念示意图：以抽象物件说明本文主题，不代表真实界面或运行结果。
set -euo pipefail
pathspec_demo=$(mktemp -d)
git init -q -b main "$pathspec_demo/repo"
cd "$pathspec_demo/repo"
mkdir -p src/vendor docs
printf 'literal\n' > 'report[1].txt'
printf 'pattern\n' > report1.txt
printf 'app\n' > src/app.js
printf 'library\n' > src/vendor/lib.js
printf 'guide\n' > docs/guide.txt
git add .
pattern=$(git ls-files -- 'report[1].txt')
literal=$(git ls-files -- ':(literal)report[1].txt')
all_literal=$(git --literal-pathspecs ls-files -- 'report[1].txt')
test "$pattern" = $'report1.txt\nreport[1].txt'
test "$literal" = 'report[1].txt'
test "$all_literal" = "$literal"
printf 'pattern=%s\nliteral=%s\n' "${pattern//$'\n'/|}" "$literal"
cd docs
selected=$(git ls-files --full-name -- \
':(top,glob)src/**/*.js' \
':(top,exclude,glob)src/vendor/**')
test "$selected" = src/app.js
printf 'selected=%s\n' "$selected"
only_exclude=$(git ls-files --full-name -- \
':(top,exclude,glob)src/**')
test "$only_exclude" = docs/guide.txt
printf 'exclude-only-from-docs=%s\n' "$only_exclude"三个保护动作分别解决不同问题
前两行应为 pattern=report1.txt|report[1].txt 和 literal=report[1].txt。默认选择同时包含字面同名文件与模式匹配的文件，竖线只是把两条输出并排显示。方括号的字符集合含义让普通名字也被纳入。引号让这串字符完整进入 Git，literal 才使 Git 把方括号当成文件名的一部分。
全局 --literal-pathspecs 对这个命令的路径参数统一采用字面解释。脚本接收外部提供的精确路径时，这种形式往往更容易保持一致；若命令同时需要字面路径和模式选择，就应逐个表达意图，并检查使用的子命令是否支持相应规则。
不要去掉示例中的引号。即使有 magic 前缀，shell 仍可能先展开通配字符。两个解释层都要处理：参数边界交给 shell 引号，Git 的选择语义交给 pathspec。只修好其中一层，某些目录内容变化后仍会出现意外。
排除规则从已选范围里扣除
第三行是 selected=src/app.js。glob 模式中的双星号覆盖中间目录层级，排除条件再去掉 vendor 下的文件。top 让这两条规则从仓库根部理解，因此即使当前位于 docs，仍能选择到 src 内的目标。
第四行特别展示只有排除条件的情况：它从这个命令原本会使用的范围中排除匹配项，未必自动扩成整个仓库。当前在 docs，结果仍是 docs/guide.txt。不要把“top 出现在排除规则里”误认为其他默认选择范围也一起变成了根目录。
文件选择与输出编码还是两个问题。这个演示刻意使用没有换行的名称，便于人眼核对；自动脚本处理任意文件名时，应另行选择 NUL 分隔输出，按真实参数边界读取。正确选中路径，并不能保证后续按行拆分也正确。
实际采用规则时，保留一个容易混淆的反例，例如带方括号名字旁边放一个普通名字，再验证纳入与排除清单。把工作目录也加入测试条件，随后才把同一选择逻辑交给会改变状态的命令，能显著减少选多、选少或选错目录的问题。
