bash-it开发指南从编写组件到提交PRComposure元数据与shellcheck规范详解【免费下载链接】bash-itA community Bash framework.项目地址: https://gitcode.com/gh_mirrors/ba/bash-itbash-it 是一个社区维护的 Bash 框架A community Bash framework为 Bash 3.2 提供别名aliases、插件plugins、补全completions和主题themes四类可独立启用的组件。本文是一份面向新贡献者的 bash-it 开发指南带你走通从编写一个组件、补充 Composure 元数据、通过 shellcheck 代码规范检查到提交 PR 并被 CI 验证的完整流程。快速认识项目结构组件存放位置一览bash-it 采用available enabled的软链接设计所有可用组件放在available/目录用bash-it enable启用后会在enabled/中生成指向源文件的软链接由 scripts/reloader.bash 统一加载。组件类型存放目录命名规范别名aliases/available/name.aliases.bash插件plugins/available/name.plugin.bash补全completion/available/name.completion.bash主题themes/name/name.theme.bash开发前建议先阅读贡献规范docs/contributing.rst开发文档docs/development.rst架构说明CLAUDE.md安装与入口install.sh、bash_it.sh编写组件文件命名与 Bash 3.2 兼容性新建组件时文件名必须遵循{name}.{type}.bash约定如mytool.plugin.bash否则安装和启用机制会失效。几条硬性约束 只支持 Bash 3.2不要使用关联数组等 Bash 4 特性确需新版特性时参考 plugins/available/pack.plugin.bash 的自禁用 日志提示写法调用$BASH_IT变量时务必加双引号${BASH_IT}以兼容带空格的路径公开函数名用连字符my-new-function内部函数加下划线前缀_my-internal-function为组件添加 Composure 元数据Composure 是 bash-it 使用的轻量元数据框架源码见 vendor/github.com/erichs/composure/composure.sh。元数据会被bash-it help、bash-it search实现见 lib/search.bash等命令读取是让用户发现你组件的关键。支持的关键字共 6 个about author example group param version可用_composure_keywords查看测试见 test/lib/composure.bats。以 plugins/available/base.plugin.bash 为范例标准写法是cite about-plugin about-plugin miscellaneous tools # 文件级组件一句话简介 function down4me() { about checks whether a website is down for you, or everybody # 函数级简介 param 1: website url or domain # 参数说明 example $ down4me google.com # 使用示例 group base # 分组归类 # ... 函数体 ... } 补充元数据的小技巧给补全组件补元数据时描述要写工具本身做什么而不是为 XX 提供 tab 补全。待办清单和格式示例见 docs/TODO_COMPOSURE_METADATA.md。通过 shellcheck 检查渐进式 Lint 机制bash-it 采用渐进式代码治理不是要求所有历史文件立即达标而是用白名单 clean_files.txt 逐步扩大检查范围。核心规则新增或修改的 bash 文件必须通过全部 lint 检查并把文件路径加入clean_files.txt该文件要求按字母序排列由 hooks/check-clean-files-txt.sh 校验。本地运行检查有两种方式# 只对 clean_files.txt 白名单内的文件跑 pre-commit 钩子 ./lint_clean_files.sh # 临时检查所有文件 pre-commit run --all-files项目的钩子配置在 .pre-commit-config.yaml除 shellcheck、shfmt 外还有两个 bash-it 专属校验钩子hooks/dot-bash.sh检查.bash文件是否符合 bash-it 约定hooks/dot-sh.sh检查.sh文件两个高频避坑点CLAUDE.md 代码标准章节有详细解释用command前缀调用敏感命令如command mv、command grep避免被用户的 alias 干扰核心逻辑可能未定义的变量用${VAR-}默认展开如${BASH_VERSION-}防止用户开了set -u时脚本报错运行单元测试test/run 一步到位提交前务必跑一遍测试套件测试框架为 BATS内置于 test_lib/git submodule init git submodule update test/run # 全量测试 test/run test/plugins # 只跑某个测试目录测试文件命名规则为{component}.bats与组件一一对应例如插件测试在 test/plugins/ 下。修复 bug 时最好同步补一个证明 bug 已消失的测试用例断言优先使用内置的 assert 函数库test/test_helper.bash。提交 PR 的完整流程从master拉出功能分支一个 PR 只包含一个特性新主题和修 bug 要拆成两个 PR本地依次完成补全 Composure 元数据 →./lint_clean_files.sh通过 → 新文件加入 clean_files.txt →test/run全绿推送分支并发起 PRCI 会在 Linux 和 macOS 上自动跑测试与 lint构建失败的 PR 不会被合并提交后避免对 PR 分支 force-push复杂改动可先 squash 再推送需要本地环境时仓库地址为git clone https://gitcode.com/gh_mirrors/ba/bash-it 提交新主题时截图和主题说明请写进 PR 描述字段不要直接塞进主分支并考虑在docs/themes-list/下新增theme_name.rst文档页格式可参考 docs/themes-list/radek.rst。常见返工点检查清单✅ 文件名符合{name}.{type}.bash命名约定✅ 文件头有cite about-xxx与about-xxx简介函数带about/param/example/group✅ 新文件已加入 clean_files.txt 且./lint_clean_files.sh通过✅ 未使用 Bash 4 特性$BASH_IT已加双引号✅ 敏感命令用command前缀变量用${VAR-}展开✅test/run测试全绿CI 构建通过遵循以上规范你的 bash-it 组件就能顺利并入社区框架被全球开发者的终端所使用。【免费下载链接】bash-itA community Bash framework.项目地址: https://gitcode.com/gh_mirrors/ba/bash-it创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考