try 项目的 POSIX Shell 编码规范:STYLE.md 全解析与实践指南

原创2026-10-14 10:44:161,608 阅读
文章标签:开发工具CLI

try 项目的 POSIX Shell 编码规范:STYLE.md 全解析与实践指南

try 是一个用单个 POSIX shell 脚本实现的"半隔离(semisolate)"工具,它借助 Linux 的 namespaces 与 overlayfs,让用户在执行命令后、提交改动前,先完整审查其对真实文件系统的影响。其主实现 try 是约 920 行的 #!/bin/sh 脚本,而 STYLE.md 正是约束这份脚本的编码规范。本文以 STYLE.md 为骨架,结合主脚本、lint 工具与测试用例,逐条讲解每一类规范背后的 POSIX 兼容性动机、具体写法以及它们在 try 仓库中的落地形态,帮助读者在编写可移植 shell 代码时直接复用这套实践。

try 与 STYLE.md:为什么一门"古老"的语言需要严苛的风格

POSIX shell 是一门出了名的"棘手"编程语言——它语法简洁、无处不在,但不同实现(dash、bash、ksh、zsh、busybox sh)之间存在大量行为分叉。STYLE.md 开篇就点明了这一点,并声明这是 try 项目的代码风格指南。

与多数项目把 STYLE.md 当作"锦上添花"不同,try 把风格规范当成了正确性的一部分:

  • 主脚本必须是纯 POSIX shell,才能在尽可能多的发行版上直接运行(README 列出的测试环境涵盖 Ubuntu、Debian、Fedora、CentOS、Arch、Alpine、Rocky、SteamOS);
  • 规范禁止的每一项语法,几乎都对应"某个常见 shell 支持、但 POSIX 未定义"的扩展;
  • 规范被显式纳入发布流程:Makefile.in 的 dist 目标在构建发行包时会复制 STYLE.md,与源码一同分发。

因此,阅读 STYLE.md 的正确姿势是:把它当作"POSIX shell 可移植性红线清单",而不仅是排版偏好。

缩进与空白:可读性的第一道防线

STYLE.md 对空白的要求非常具体:

  • 缩进使用四个空格,禁止 Tab;
  • 空行不得包含任何空白字符;
  • 行尾不得有尾随空白;
  • 尽量避免行继续符(\ 换行)。

理由是直白的:shell 对空白极其敏感,尾随空格、Tab 混用会在不同编辑器和 diff 工具间制造噪音,而行继续符在部分实现(如某些 busybox sh)或错误换行场景下会导致难以排查的解析错误。

关于 case 结构,STYLE.md 要求把各分支的命令对齐,并给出了规范示例:

case "$1" in
    (summary) : ${SANDBOX_DIR=$2}
              summary;;
    (commit)  : ${SANDBOX_DIR=$2}
              commit;;
    (explore) : ${SANDBOX_DIR=$2}
              try "$SHELL";;
    (--)      shift
              try "$@";;
    (*)       try "$@";;
esac

这段示例并非虚构——try 主入口的 case "$1" 结构几乎逐字复刻了它,包括 (summary)、(commit)、(explore)、(--)、(*) 五个分支与命令对齐方式。读者在阅读主脚本时可以看到规范与实现的直接呼应。

这些空白要求并非仅靠自觉,scripts/lint.sh 将其自动化:trailing_whitespace 用 grep -e '[[:blank:]]$' 检查行尾空白、tabs 检查 Tab(Makefile 文件豁免,因为 Make 语法本身需要 Tab)、trailing_newline 检查文件末尾是否有换行符。运行 make lint 即可并行扫描全仓库。

只写 POSIX 代码:禁用特性清单与原因

STYLE.md 用一整个章节列出禁止使用的语法。逐条理解它们为何被禁,是掌握该规范的关键:

禁用写法 典型实现来源 为什么不可移植
<(进程替换) bash / ksh93 / zsh 未出现在 POSIX 规范中,多数 POSIX sh(如 dash)直接报语法错误
(( 算术表达式 )) ksh / bash POSIX 只定义了 $(( )) 算术展开,(( )) 作为复合命令是 ksh/bash 扩展
[[ 静态测试 ]] ksh / bash 扩展测试命令,POSIX 只有单括号 [
array=(赋值) / ${array[访问]} bash / ksh / zsh POSIX 不支持数组,只有位置参数
function 关键字 bash / ksh / zsh POSIX 函数定义只有 name() { ... } 一种形式
brace{expansion,} bash / zsh 大括号展开非 POSIX,行为在不同 shell 间差异大
${param:offset}、${!matching}、${pattern/substi/tution} bash / ksh 子串、间接展开与替换展开均为扩展语法;POSIX 只定义 ${param#word}、${param%word} 等模式删除类展开
source bash / ksh POSIX 的点号命令写作 .,source 仅部分 shell 支持

这些禁令的共同逻辑是:一旦脚本依赖上述任一语法,它就不再是严格意义上的 POSIX shell 脚本,换一个 shell 运行就可能整体失败。try 主脚本在实现中严格遵守了这份清单——例如 try 的 set_TRY_SHELL 函数里使用 POSIX 标准的 ${SHELL##*/} 删除前缀展开来判断 shell 是否为 fish,而不是借助任何 bash 专属写法。

规范还额外强调了一条容易踩坑的规则:

# 不要这样写
LOCAL_ASSIGNMENT=foo f
# 当 f 可能是函数时,应这样写
VAR_NAME=value
export VAR_NAME

原因在于:VAR=value 命令 这种前缀赋值对内建命令和外部命令是 POSIX 保证的行为,但对函数,是否生效、是否随调用传播,由各 shell 实现自行决定——dash 与 bash 的表现就不一致。当 f 是函数时,这行代码的可移植性就是未知数。try 中 set_TRY_SHELL 的 TRY_SHELL="$SHELL" + export TRY_SHELL 两行式写法,正是该规范的实践样例。

引号:宁可安全

STYLE.md 对引号只写了一句话:"It is better to be safe than sorry."(多引总比少引好)。这背后是 shell 最经典的两类陷阱:

  • 未加引号的变量展开会经历 IFS 字段分割与通配符展开:$file 若包含空格或 *,语义即刻改变;
  • 空参数丢失:"$@" 在零参数时保持零个参数,而 $@ 会静默退化。

try 脚本是引号纪律的活教材:<a href="https://link.gitcode.com/i/3b49ae57b217e5941d09037bd41c074d" target="_blank"> -x "$SHELL" ]、"$SANDBOX_DIR"/mount.log、summary() 里 try-summary -E "$EXCLUDE_FILE" -I "$INCLUDE_FILE" "$SANDBOX_DIR",以及 chmod "$(stat -c %a /)" "$SANDBOX_DIR/temproot"([try),几乎每个变量引用都带引号。同时规范也提醒"不要忘记引号"——比如 [ "..." ] 判断非空时,[ $var ] 与 [ "$var" ] 在 var 为空时结果完全不同。

变量命名与作用域

STYLE.md 的变量规则可以归纳为三点:

  1. 命名:使用字母加下划线的组合(alphabetical names with underscores),如 sandbox_dir、mountpoint,避免驼峰或其他分隔符;
  2. 大小写即作用域标签:存活期超出当前作用域的变量用 CAPITALIZED_LIKE_THIS(如 SANDBOX_DIR、TRY_SHELL、HIDE_FILE),局部变量用 lowercase_like_this(如函数内的 sandbox_dir、exclude_file);
  3. 禁用 local 关键字:local 在 POSIX 中未定义,即使 bash/ksh 支持,dash 等实现并不支持。

由于不能用 local,try 脚本通过两条途径实现"局部化":一是在函数开头把位置参数重命名为带语义的小写变量(如 process_changes() 中的 sandbox_dir="$1"、changed_files="$2"),二是依赖子 shell 隔离(如 while 循环从 heredoc 读取时)。

花括号方面,规范给出了一个常被误解的细节:

# 每个 POSIX shell 都能正确解析,SANDBOX_DIR 是完整变量名
"$SANDBOX_DIR/workdir"
# 仅当需要与合法变量名字符粘连时才需要花括号
"${SANDBOX_DIR}2"

也就是说:"$VAR/suffix" 中 shell 天然知道变量名止于 /,不必画蛇添足。try 源码多数位置遵循该约定(如 try 的 "$SANDBOX_DIR"/mount.log),少数位置(如 try 的 ${SANDBOX_DIR}/upperdir/${mountpoint})为统一风格仍使用花括号——读者可自行对照,理解两种写法都是合法的。

命令替换:$(...) 永远是答案

STYLE.md 的规定言简意赅:"Always use $(...); never use backticks."(永远用 $(...),绝不用反引号)。

反引号的历史包袱在于嵌套与转义:内部再套反引号时必须用 \`` 转义,内部的反斜杠规则也随实现漂移,极易出错。而 $(...)` 支持任意嵌套、内部可正常使用引号与反斜杠,且所有现代 shell(含 POSIX sh)都支持。

try 主脚本从第一行起就贯彻此规则:try 用 EXECID="$(date +%s%3N)" 生成执行 ID,SANDBOX_DIR="$(mktemp -d --suffix ".try-$EXECID")" 创建沙箱目录,tmpfstype=$(df --output=fstype "$SANDBOX_DIR" | tail -n +2) 探测文件系统类型。测试用例 test/command_substitution.sh 专门验证了在 try 隔离环境中 mypwd="$(pwd)" 这类命令替换能够正确展开并与宿主环境结果一致——这也从侧面说明:命令替换在 overlay + namespace 的复杂环境下依然可靠。

函数定义:命名、注释头与参数纪律

函数是 try 脚本组织逻辑的基本单元(全脚本约十余个函数:set_TRY_SHELL、try、summary、commit、prompt_commit、process_changes、sandbox_valid_or_empty 等)。STYLE.md 对函数提出四条规定:

  • 函数名一律小写(in_lowercase_please);
  • 函数定义上方必须有函数头注释(generated scripts 可精简,但重要注释仍要保留);
  • 函数体用花括号包裹,左花括号与函数名同行、前面留一个空格:name() {;
  • 除非使用 $@,否则必须重命名位置参数(parameter="$1"),避免 $1、$2 这种模糊的调用约定。

函数头注释的标准格式是一行 80 个 # 的分隔线加一行描述、再一行分隔线,例如 STYLE.md 中的模板:

################################################################################
# Summarize an overlay
################################################################################

summary() {
    ...
}

这种"注释横幅"在 try 中大量出现:set_TRY_SHELL(try)、try(try)、summary、commit、prompt_commit、exclude_changes、process_changes、sandbox_valid_or_empty 等每个函数都配有同类头部注释,同时内部还夹着大量解释性注释(如 try 对 unshare 各旗标含义的逐行说明)。函数内位置参数重命名的样例见 process_changes() 开头的 sandbox_dir="$1"、changed_files="$2"(try)。

值得一提的例外:try 运行时通过 heredoc 生成的脚本(mount_and_execute.sh、chroot_executable.sh,见 try)属于规范中"generated scripts can be terser"的豁免范畴,可适当精简注释,但仍保留了关键说明。

命令用法细则

STYLE.md 对具体命令的书写习惯有一组硬性规定:

  1. 重定向放在命令末尾,且重定向上不得有空格:写 2>/dev/null,不写 2> /dev/null;
  2. 优先使用 echo(但只用 POSIX 旗标)。规范的本意是避免非必要地引入 printf 的格式化开销与歧义;当然当确实需要格式化或 -n 之外的输出控制时,try 源码大量使用了 printf(如 try 的 printf "\nCommit these changes? [y/i/N] " >&2),这也符合"在需要时使用"的精神;
  3. 调用 [ 而不是 test(两者虽等价,但统一风格);在 [ ... ] 内部使用 && / || 而不是 -a / -o——POSIX 已把 -a/-o 标记为过时且行为未定义(受参数个数影响),而 &&/|| 是明确的 shell 运算符。try 源码中 [ -x "$SHELL" ] && [ "${SHELL##*/}" != "fish" ](try)、<a href="https://link.gitcode.com/i/4cbbbf31fe0e8b549e1f561caa757fe2" target="_blank"> -t 0 ] && set -m([try)都是典型写法;
  4. 但对于 find,反而要用 -a / -o——因为 find 的表达式语言里 -a/-o 才是标准形式,&&/|| 在 find 中并不适用;
  5. 用 [ "..." ] 判断变量是否为空,没有理由再用 -n;同时绝不能忘记引号;
  6. case 的 ;; 放在最后一条命令的同一行(不是独占一行),最后一个分支也不能省略 ;;,每个分支都写全左右两个括号(虽然左括号 ( 可省略)。

try 主脚本中 case "$1" 的完整结构((summary) : ${SANDBOX_DIR=$2} 后接对齐命令与同行 ;;)就是这些细则的组合示范;completions/try.bash 的补全函数内部同样采用了 (try)、(*) 带括号的 case 风格。主脚本 getopts 循环中的 case(try)也保持了 (y)、(n)、(E)、(h|*) 等统一写法,且每个分支末端的 ;; 无一省略。

分号:让 shell 呼吸

STYLE.md 的最后一节专门对付分号滥用:

  • 控制流中避免分号,写成多行:
if [ ... ]
then
    ...
fi
  • 不写 c1; c2,而是分行:
c1
c2

理由是直白的:"The shell is terse enough without any effort on your part."(shell 本身已经够简洁了,无需你再压缩。)分号压缩行数在 if/then、for/do 等结构上尤其危险——then 与 if 同行的写法在部分实现上解析不稳定,多行结构则与 POSIX 文法一一对应、毫无歧义。try 主脚本中 if <a href="https://link.gitcode.com/i/6ef476d34ef75ff35285aff1c6b316dd" target="_blank"> -d "$SANDBOX_DIR" ] / then / else / fi 全部采用多行形式(如 [try),while、for、case 同理,通篇找不到 if ...; then 的压缩写法。

规范如何被自动化保障:lint 与测试

STYLE.md 的规范不是纸上谈兵,仓库配套了完整的自动化保障体系:

1. 静态风格检查——scripts/lint.sh

make lint 会并行扫描仓库全部文本文件,执行三项检查:尾随空白(trailing_whitespace)、文件末尾换行(trailing_newline)、Tab 字符(tabs,Makefile* 因语法需要而豁免)。任一违规都会以高亮红块标出并最终返回非零退出码。

2. 注释纪律——scripts/check_trycase.sh

STYLE.md 的"函数头注释"精神延伸出了更严格的 TRYCASE 注释规范:try 脚本的 process_changes()(try)、utils/try-summary.c、utils/try-commit.c 与 test/all-commit-cases.sh 中用 // TRYCASE(改变类型, 本地类型) 形式的注释枚举每种变更组合(如 TRYCASE(file, file)、TRYCASE(whiteout, *)、TRYCASE(dir, nonexist))。check_trycase.sh 会反向验证:构建一个覆盖所有文件类型 × 本地类型组合的临时目录,检查源码中声明的 TRYCASE 是否完备、有无多余或缺失——把"注释与行为一致性"变成了可机械检查的约束。

3. 行为测试——test/check_shell.sh 等

test/check_shell.sh 验证 set_TRY_SHELL 的探测逻辑:当 TRY_SHELL 指向可执行文件时优先采用;否则回退到 SHELL(排除 fish);再否则查 /etc/passwd 的登录 shell。这与规范中"环境变量导出"、"<a href="https://link.gitcode.com/i/d598fb47389cb75f253c5d151b70878c" target="_blank"> -x ] 判断"的写法相互印证。整个测试套件由 [scripts/run_tests.sh 驱动,make test 一键执行,覆盖命令替换、隐藏/排除旗标、unzip、merge 多目录等数十个场景。

4. 构建期约束——Makefile.in

dist 目标把 STYLE.md 与 try、utils、test、docs 一起打入发行包(Makefile.in),意味着风格指南随每一份源码发行版交付,成为项目的公开契约。

结语

STYLE.md 表面上是一份缩进与命名的风格文档,实质上是 POSIX shell 可移植性的红线清单:空白消除解析噪音,禁用特性清单拦住不可移植语法,引号与分号规则消解最经典的语义陷阱,而 try 主脚本、lint.sh、check_trycase.sh 与测试套件则让每一条规范都有了活的范例与自动化裁判。对任何需要以 #!/bin/sh 交付、希望在 dash/busybox/ksh 等任意 shell 下稳定运行的脚本项目而言,这套规范都值得直接照搬。若想看到规范与实现的完整对照,最直接的路径就是通读 try 主脚本与 scripts/lint.sh,再对照 STYLE.md 逐条验证。

登录后查看全文
try