Spaceship Prompt 的 dir 工作目录 Section截断逻辑、Git 仓库适配与写保护提示完全指南【免费下载链接】spaceship-prompt✨ Minimalistic, powerful and extremely customizable Zsh prompt项目地址: https://gitcode.com/gh_mirrors/sp/spaceship-promptdir是 Spaceship Zsh 提示符中最基础的 section 之一用于在提示符中展示当前工作目录current working directory。本文以 docs/sections/dir.md 文档为骨架结合 sections/dir.zsh 源码与 tests/dir.test.zsh 测试用例深入讲解dirsection 的默认截断规则、Git 仓库内特化行为、写保护目录的锁符号提示以及全部 9 个配置选项的完整语义与底层实现原理。读完本文你将能够精确控制路径在提示符中的显示深度、前缀样式与颜色并理解这些行为在源码层是如何被实现的。dir section 是什么dirsection 负责渲染当前工作目录。它是提示符的路标让用户随时知道自己身处哪个目录。与其他按需显示的 section如检测到 Git 仓库才显示的git、检测到 Node 项目才显示的node不同dir始终显示——这是它在 sections/dir.zsh 中被实现为固定 section 的原因也是 lib/utils.zsh 中spaceship::is_section_async将dir列为必须同步渲染sync的 section 的原因路径信息必须第一时间呈现不能等待异步任务。默认情况下路径只显示末尾 3 层目录由SPACESHIP_DIR_TRUNC控制。例如在/home/user/projects/spaceship/docs/sections目录下提示符默认只展示docs/sections从末尾算起的 3 层而非完整路径。在默认的 提示符顺序 中dir位于user用户名之后、host主机名之前是提示符第二行最醒目的位置SPACESHIP_PROMPT_ORDER( time # Time stamps section user # Username section dir # Current directory section host # Hostname section # ... )仓库内的特化行为以仓库根为边界当用户身处 Git 仓库中时dirsection 会改变截断策略它只显示仓库根目录的名字root directory以及仓库内部的文件夹仓库之外的上级路径一律省略。例如假设仓库根为~/projects/spaceship即git rev-parse --show-toplevel的输出而当前目录是~/projects/spaceship/docs/sections那么提示符中只会显示spaceship/docs/sections而不是从~或/home开始的完整路径。这一行为在 tests/dir.test.zsh 的test_dir_trunc_git用例中得到了验证在临时目录.../dir1/dir2/dir3/dir4/dir5中执行git init后渲染出的路径预期为dir3/dir4/dir5——即从仓库根dir3开始而不是默认的末尾 3 层。该测试还覆盖了子模块场景tests/dir.test.zsh 的test_dir_trunc_git_submodule当处于子模块dir4中时提示符只显示dir4说明此行为对子模块同样生效子模块本身被视为一个独立的仓库边界。如果你不喜欢这种以仓库为边界的行为可以通过设置SPACESHIP_DIR_TRUNC_REPO为false来恢复普通的截断逻辑SPACESHIP_DIR_TRUNC_REPOfalse源码实现git root 的定位与参数展开在 sections/dir.zsh 中仓库边界的实现分三步判断是否在 Git 仓库调用spaceship::is_git定义于 lib/utils.zsh其内部执行git rev-parse --is-inside-work-tree并判断结果是否为true。获取仓库根执行git rev-parse --show-toplevel得到绝对路径若系统中存在cygpathWindows/Cygwin 环境还会执行cygpath -u $git_root将其转换为 Unix 风格路径保证跨平台一致性。拼接显示路径使用 Zsh 参数展开$git_root:t取根目录的 basename加上${${PWD:A}#$~~git_root}把当前目录PWD中与git_root相同的前缀剥离掉。其中${PWD:A}会将PWD中的符号链接解析为真实路径与git rev-parse返回的已解析路径对齐$~~用于关闭GLOB_SUBST防止git_root中的特殊字符被当作通配模式解释#前缀删除模式用于从变量值头部移除匹配的前缀这是 Zsh 标准的参数展开语法。另外当仓库根的直接父目录就是/时trunc_prefix会被显式设为/sections/dir.zsh保证像/repo这样直接挂在根下的仓库能正确显示前导斜杠否则trunc_prefix取SPACESHIP_DIR_TRUNC_PREFIX的值。写保护目录锁符号提示如果当前目录不可写——例如目录权限受限或当前用户没有写权限——dirsection 会在路径后面追加一个锁符号padlock作为后缀。在 sections/dir.zsh 中判断逻辑非常简单if [[ ! -w . ]]。当目录不可写时suffix 被替换为%F{$SPACESHIP_DIR_LOCK_COLOR}${SPACESHIP_DIR_LOCK_SYMBOL}%f${SPACESHIP_DIR_SUFFIX}即用锁符号的颜色默认红色red渲染锁符号默认 然后再接上正常的SPACESHIP_DIR_SUFFIX。%F{...}与%f是 Zsh 的前景色设置/重置转义序列确保只有锁符号本身是红色。锁符号与颜色均可配置# 自定义锁符号例如使用文字 [RO] SPACESHIP_DIR_LOCK_SYMBOL [RO] # 自定义锁符号颜色 SPACESHIP_DIR_LOCK_COLORyellow完整选项参考dirsection 的全部配置项定义于 sections/dir.zsh均为环境变量遵循SPACESHIP_SECTION_OPTION的命名约定参见 docs/config/prompt.md变量默认值含义SPACESHIP_DIR_SHOWtrue是否显示该 section设为false可隐藏SPACESHIP_DIR_PREFIXin·section 的前缀默认是in后接一个空格SPACESHIP_DIR_SUFFIX$SPACESHIP_PROMPT_DEFAULT_SUFFIXsection 的后缀默认继承提示符级默认后缀一个空格SPACESHIP_DIR_TRUNC3在提示符中显示的 cwd 目录层数0表示显示全部SPACESHIP_DIR_TRUNC_PREFIX空路径被截断时显示在前面的前缀例如…/或.../设为空可禁用SPACESHIP_DIR_TRUNC_REPOtrue在 Git 仓库内时只显示仓库根目录及仓库内文件夹SPACESHIP_DIR_COLORcyansection 的显示颜色SPACESHIP_DIR_LOCK_SYMBOL锁符号目录不可写时显示的后缀符号SPACESHIP_DIR_LOCK_COLORred锁符号的颜色注意表格中前缀默认值in·的·是中间点字符middle dot的可视化表示实际默认值就是in in加一个空格这在源码 sections/dir.zsh 中可以看到。常用配置示例# 显示完整路径不截断 SPACESHIP_DIR_TRUNC0 # 只显示末尾 2 层并用省略号标记截断 SPACESHIP_DIR_TRUNC2 SPACESHIP_DIR_TRUNC_PREFIX…/ # 改变颜色为蓝色 SPACESHIP_DIR_COLORblue # 隐藏整个目录 section SPACESHIP_DIR_SHOWfalse # 在 Git 仓库内禁用以仓库为边界的显示 SPACESHIP_DIR_TRUNC_REPOfalse截断前缀的 Zsh 提示符展开原理SPACESHIP_DIR_TRUNC_PREFIX并非简单地拼在路径前而是通过 Zsh 的**提示符展开Prompt Expansion**机制实现的。在 sections/dir.zsh 中trunc_prefix%($((SPACESHIP_DIR_TRUNC 1))~|$SPACESHIP_DIR_TRUNC_PREFIX|) dir$trunc_prefix%${SPACESHIP_DIR_TRUNC}~%~是 Zsh 提示符展开中显示当前路径的转义还会把$HOME替换为~%${SPACESHIP_DIR_TRUNC}~表示只显示路径末尾 N 层%(N~|TRUE|FALSE)是一个条件表达式当当前路径相对于根目录的层级数大于等于 N时输出TRUE分支否则输出FALSE分支。这里 N 取SPACESHIP_DIR_TRUNC 1因此当路径层数超过显示上限时trunc_prefix会被赋值为SPACESHIP_DIR_TRUNC_PREFIX如…/否则为空——这正是只在真的被截断时才显示省略号的实现原理。Zsh 手册将这一语法归类为 Prompt Expansion 章节与之配合的${NAME#PATTERN}、${PWD:A}、$~~等则属于 Parameter Expansion 章节二者是dirsection 的核心技术基础。渲染管线从 section 数据到最终提示符dir的输出通过 sections/dir.zsh 底部的spaceship::section函数打包spaceship::section \ --color $SPACESHIP_DIR_COLOR \ --prefix $SPACESHIP_DIR_PREFIX \ --suffix $suffix \ $dirspaceship::section定义于 lib/section.zsh使用zparseopts解析--color、--prefix、--suffix等选项将颜色、前缀、后缀、符号与内容打包成一个以·|·分隔的元组。随后spaceship::section::renderlib/section.zsh解析该元组并执行以下渲染规则若内容与符号均为空直接返回不渲染仅当SPACESHIP_PROMPT_PREFIXES_SHOW为true且前缀非空时才输出加粗的前缀内容部分用%F{color}上色并以加粗输出仅当SPACESHIP_PROMPT_SUFFIXES_SHOW为true且后缀非空时才输出加粗的后缀。这意味着dir的前缀/后缀是否显示还受到提示符级选项 SPACESHIP_PROMPT_PREFIXES_SHOW 与 SPACESHIP_PROMPT_SUFFIXES_SHOW 的全局开关约束同时也解释了为什么第一个 section 的前缀会被隐藏SPACESHIP_PROMPT_FIRST_PREFIX_SHOW控制默认false——dir通常不是第一个 section但在精简配置中若它位于首位前缀in会默认被省略。测试驱动的行为验证Spaceship 测试套件 为dirsection 的行为提供了自动化验证可作为自定义配置时的行为参考测试用例验证点test_dir_home在$HOME下默认渲染路径含%3~末尾 3 层test_dir_color修改SPACESHIP_DIR_COLOR后颜色随配置变化test_dir_prefix/test_dir_suffix自定义前后缀能正确渲染test_dir_truncSPACESHIP_DIR_TRUNC2时使用%2~截断test_dir_trunc_git在 Git 仓库内只显示仓库根到当前目录的部分test_dir_trunc_git_submodule在子模块内以子模块为边界显示测试通过spaceship::testkit::render_prompt来自 lib/testkit.zsh渲染提示符并断言其与期望的转义序列完全一致例如test_dir_home期望输出in ...%(4~||)%3~...。这清晰地展示了截断前缀的条件表达式%(4~||)在路径不足 4 层时输出空串路径达到 4 层及以上时才启用%3~截断。总结dirsection 以最小化、可配置为设计目标用约 50 行 Zsh 代码实现了三件事默认截断末尾 3 层路径SPACESHIP_DIR_TRUNC、Git 仓库内以仓库根为边界显示SPACESHIP_DIR_TRUNC_REPO以及写保护目录的锁符号警示SPACESHIP_DIR_LOCK_SYMBOL/SPACESHIP_DIR_LOCK_COLOR。其实现深度依赖 Zsh 的提示符展开%~、%(N~|...|)与参数展开${PWD:A}、$~~、#前缀删除并通过spaceship::section渲染管线与提示符级选项协同工作。理解这些机制后你可以通过 9 个环境变量精准定制路径提示也能举一反三地为自己的自定义 section 实现类似的截断与条件显示逻辑。【免费下载链接】spaceship-prompt✨ Minimalistic, powerful and extremely customizable Zsh prompt项目地址: https://gitcode.com/gh_mirrors/sp/spaceship-prompt创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考