try 项目的 POSIX Shell 编码规范:STYLE.md 全解析与实践指南
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 的变量规则可以归纳为三点:
- 命名:使用字母加下划线的组合(
alphabetical names with underscores),如sandbox_dir、mountpoint,避免驼峰或其他分隔符; - 大小写即作用域标签:存活期超出当前作用域的变量用
CAPITALIZED_LIKE_THIS(如SANDBOX_DIR、TRY_SHELL、HIDE_FILE),局部变量用lowercase_like_this(如函数内的sandbox_dir、exclude_file); - 禁用
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 对具体命令的书写习惯有一组硬性规定:
- 重定向放在命令末尾,且重定向上不得有空格:写
2>/dev/null,不写2> /dev/null; - 优先使用
echo(但只用 POSIX 旗标)。规范的本意是避免非必要地引入printf的格式化开销与歧义;当然当确实需要格式化或-n之外的输出控制时,try源码大量使用了printf(如 try 的printf "\nCommit these changes? [y/i/N] " >&2),这也符合"在需要时使用"的精神; - 调用
[而不是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)都是典型写法; - 但对于
find,反而要用-a/-o——因为find的表达式语言里-a/-o才是标准形式,&&/||在 find 中并不适用; - 用
[ "..." ]判断变量是否为空,没有理由再用-n;同时绝不能忘记引号; 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 逐条验证。