CLI【免費(fèi)下載鏈接】bash-itA community Bash framework.項目地址https://gitcode.com/gh_mirrors/ba/bash-it點(diǎn)擊查看免費(fèi)下載Bash-it 是一個社區(qū)驅(qū)動的 Bash 框架倉庫根目錄見 bash_it.sh社區(qū)協(xié)作是該項目持續(xù)演進(jìn)的核心動力。本文以官方文檔 docs/contributing.rst 為骨架系統(tǒng)講解向 Bash-it 提交 Issues、Pull Request、代碼風(fēng)格規(guī)范、單元測試與 CI、功能集成原則以及主題與截圖貢獻(xiàn)的完整流程并深入對應(yīng)的倉庫源碼與測試用例進(jìn)行印證。讀完本文你將掌握一套可直接照做的 Bash-it 貢獻(xiàn)清單包括如何讓代碼通過 lint 白名單、如何運(yùn)行 bats 測試套件、以及如何規(guī)范化提交一個新主題。貢獻(xiàn)總覽先看 Issues再提 Pull Request官方指南開篇即強(qiáng)調(diào)提交任何新功能、Bug 修復(fù)、新主題或其他改動之前請先通讀貢獻(xiàn)規(guī)范。大部分條目屬于常識但務(wù)必遵守倉庫既定的約定避免維護(hù)者反復(fù)溝通。關(guān)于 Issue指南給出的核心建議是報告 Bug 或請求新功能時優(yōu)先考慮直接附帶一個 Pull Request——要么修復(fù)該問題要么作為新功能的起點(diǎn)。文檔原話提醒開發(fā)者不必害怕大多數(shù)事情并沒有那么復(fù)雜這與其learning project的定位一致詳見下文 Pull Request 部分。Pull Request 規(guī)范一 PR 一事鼓勵展示過程Pull Request 的提交流程有五個要點(diǎn)Fork 分支Fork Bash-it 倉庫從master創(chuàng)建新的功能分支在其中完成修改再從該功能分支向 Bash-it 的master分支發(fā)起 Pull Request。一 PR 一事限制每個 Pull Request 只包含一個功能。不要把多個改動例如一個新Theme加一個對既有插件的修復(fù)打包進(jìn)同一個 PR——主題單獨(dú)一個 PR修復(fù)單獨(dú)一個 PR。Squash 提交對于復(fù)雜改動推送前盡量把變更squash成單個提交推送并開 PR 之后請不要再對 PR 分支進(jìn)行 force-push——Bash-it 是分布式項目你的分支可能已經(jīng)被他人使用。寧多勿少拿不準(zhǔn)時寧可提交包含較多 commit 的 PR。Bash-it 對參與者而言是一個學(xué)習(xí)項目展示你的工作過程能為后來者留下寶貴的什么可行、什么不可行的歷史記錄。CI 是門檻任何推送到 PR 的代碼都會自動觸發(fā) GitHub Actions 上的持續(xù)集成構(gòu)建測試套件會在 Linux 和 macOS 上同時運(yùn)行PR 頁面會展示構(gòu)建結(jié)果。帶構(gòu)建問題的 PR 不會被合并務(wù)必關(guān)注 CI 狀態(tài)。代碼風(fēng)格從 lint 白名單到 Bash 3.2 兼容代碼風(fēng)格章節(jié)是貢獻(xiàn)者最容易踩坑的地方官方規(guī)范從以下六個維度給出了硬性要求。1. clean_files.txt 白名單與本地 lint新增文件時務(wù)必把新文件加入 clean_files.txt——這是項目中被 lint 檢查文件的不斷增長的清單修改既有文件時也建議將其加入清單并修復(fù)隨之而來的 lint 錯誤詳見下方本地運(yùn)行 lint一節(jié)。從倉庫實(shí)現(xiàn)看clean_files.txt 是一個允許清單Allow-list支持目錄引用如themes/powerline會展開為目錄下所有文件與根文件引用如 install.sh、uninstall.sh空行與#注釋行會被忽略。實(shí)際執(zhí)行器是 lint_clean_files.sh其邏輯為讀取clean_files.txt過濾空行與注釋行用xargs -I{} find {} -type f把目錄引用展開成具體文件列表隨后清空BASH_IT變量幫助 shellcheck 識別source包含規(guī)避 SC1090 警告最后執(zhí)行pre-commit run --files ${FILES[]}。也就是說本地驗(yàn)證 lint 只需運(yùn)行./lint_clean_files.sh2. 縮進(jìn)與 EditorConfig縮進(jìn)使用tabs而非空格——文檔特別指出代碼中大部分用 2 空格縮進(jìn)、少部分用 4 空格 tabs請盡量統(tǒng)一為 tabs。如果編輯器支持 EditorConfig會自動采用倉庫 .editorconfig 中的設(shè)置。從 .editorconfig 的源碼可以印證這套約定[*]全局段默認(rèn)indent_style space, indent_size 2對應(yīng)大部分代碼 2 空格而[{**.*sh,test/run,**.bats}]段則將 shell 腳本與 bats 測試統(tǒng)一為indent_style tab, indent_size tab并附帶shell_variant bash、binary_next_line、switch_case_indent等 shell 專屬選項[**.bats]段進(jìn)一步指定shell_variant bats。此外還有trim_trailing_whitespace true、insert_final_newline true等收尾約束。3. 用 command 內(nèi)建調(diào)用命令優(yōu)先使用 shell 內(nèi)建command直接調(diào)用命令保證執(zhí)行的永遠(yuǎn)是你想要的真實(shí)命令而不是被同名的 alias/函數(shù)覆蓋后的版本。例如用command rm而非rm。倉庫中 plugins/available/base.plugin.bash 的down4me函數(shù)就是標(biāo)準(zhǔn)示范command curl -Ls http://downforeveryoneorjustme.com/${site} | command sed /just you/!d;s/[^]*//g4. 函數(shù)命名短橫線分隔下劃線留給內(nèi)部新建函數(shù)時用短橫線-分隔單詞例如my-new-function不要用下劃線如my_new_function。不面向終端用戶使用的內(nèi)部函數(shù)應(yīng)以一個下劃線開頭例如_my-new-internal-function。對照 lib/helpers.bash 源碼可以看到項目自身嚴(yán)格執(zhí)行該約定_about、_enable-plugin、_disable-plugin、_command_exists等內(nèi)部函數(shù)均以下劃線開頭而對外暴露的_enable-plugin、_disable-plugin這類組件開關(guān)函數(shù)則用短橫線連接單詞。5. 使用 meta 函數(shù)文檔化代碼請使用項目提供的 meta 函數(shù)來為代碼編寫文檔包括about-plugin、about、group、param、example等這會大大方便其他人使用你的新功能。官方示例即 plugins/available/base.plugin.bash。從該文件開頭可以看到完整的元信息寫作范式cite about-plugin about-plugin miscellaneous tools url https://github.com/Bash-it/bash-it function ips() { about display all ip addresses for this host group base # ... }而 lib/helpers.bash 中_about、_param、_example等基礎(chǔ)設(shè)施函數(shù)如第 1084 行cite _about _param _example則負(fù)責(zé)把這類元信息注冊進(jìn) Bash-it 的組件注冊表支撐bash-it help、組件搜索等能力這正是meta 函數(shù)讓功能更易被他人使用的底層實(shí)現(xiàn)。6. 文件命名與安裝兼容新增文件時遵循既有命名約定例如插件文件必須以.plugin.bash結(jié)尾——這對安裝功能至關(guān)重要。倉庫中 plugins/available 下的全部插件、aliases/available 下的別名、completion/available 下的補(bǔ)全腳本都嚴(yán)格遵守這一命名規(guī)則。7. $BASH_IT 務(wù)必加雙引號凡使用$BASH_IT變量務(wù)必用雙引號包裹以保證 Bash-it 安裝在含空格的目錄時依然工作for f in ${BASH_IT}/plugins/available/*.bash ; do echo $f ; done8. 堅持 Bash 3.2 兼容必要時自禁用Bash-it 支持Bash 3.2 及以上版本請勿使用僅 Bash 4 才有的特性如關(guān)聯(lián)數(shù)組 associative arrays。如果你確有非 Bash 4 不可的酷插件或特性可以參考 plugins/available/pack.plugin.bash 的自禁用與原因記錄寫法讓 Bash 3.2 用戶不會卡在不必要的報錯上。從 plugins/available/pack.plugin.bash 源碼可以看到該模式的完整實(shí)現(xiàn)——它正是為 Bash 4 關(guān)聯(lián)數(shù)組而寫的packCLI 補(bǔ)全# Requires bash 4 for associative arrays # Skip loading if bash version is too old if [[ ${BASH_VERSINFO[0]} -lt 4 ]]; then _disable-plugin pack return 0 fi_disable-plugin的行為在 lib/helpers.bash 中定義第 966 行附近并配有專門測試見 test/lib/helpers.bats 中多組run _disable-plugin sdkman、run _disable-plugin nvm、run _disable-plugin all的用例分別覆蓋了按名稱禁用插件與一鍵禁用全部組件的場景。單元測試用 Bats 驗(yàn)證你的改動新增功能或修改/修復(fù)時務(wù)必運(yùn)行不斷增長的單元測試套件確認(rèn)沒有引入回歸。測試套件雖未覆蓋 Bash-it 的全部方面但請無論如何都運(yùn)行一遍。運(yùn)行測試套件在克隆 Bash-it 的目錄中直接執(zhí)行test/run從 test/run 源碼看該腳本的執(zhí)行邏輯非常清晰定位自身目錄并導(dǎo)出MAIN_BASH_IT_DIR與MAIN_BASH_IT_GITDIR兩個環(huán)境變量供測試使用執(zhí)行g(shù)it submodule init git submodule update確保本地test_lib目錄中存在 Bats 測試框架Bats 以 Git 子模塊形式引入對應(yīng) test_lib/bats-core、test_lib/bats-assert、test_lib/bats-file、test_lib/bats-support 四個子模塊目錄若工作區(qū)有未提交更改git diff非空會提示dirty worktree未提交的改動不會被測試無參數(shù)時默認(rèn)依次運(yùn)行test_directory下的bash_it、completion、install、lib、plugins、themes六個測試目錄也可以傳入目錄參數(shù)精確指定測試范圍檢測到 GNUparallel時啟用并行模式默認(rèn)通過nproc探測 CPU 核數(shù)至少按雙核處理也可用環(huán)境變量TEST_JOBS手動指定并發(fā)數(shù)在 CI 環(huán)境下CI變量非空會追加--tap參數(shù)輸出 TAP 格式結(jié)果便于 CI 解析。腳本會逐個執(zhí)行每個測試并打印每個用例的狀態(tài)。實(shí)際測試文件可參考 test/lib/helpers.bats、test/plugins/base.plugin.bats、test/bash_it/bash_it.bats 等既有用例。新增測試的最佳實(shí)踐修改代碼庫時請考慮為新增或變更的功能補(bǔ)充單元測試這是提升 Bash-it 測試覆蓋率的好機(jī)會修復(fù) Bug 時理想情況是同時新增一個驗(yàn)證該 Bug 不再復(fù)現(xiàn)的測試。新增測試用例前先看看既有測試的寫法。官方推薦使用以下 Bats 生態(tài)庫中的assert系列函數(shù)來校驗(yàn)測試結(jié)果測試框架Bats Corebats-coreBats-Assert 支撐庫bats-support通用assert函數(shù)bats-assert文件assert函數(shù)bats-file功能貢獻(xiàn)原則集成而非復(fù)制添加新的補(bǔ)全completion或插件plugin時不要把現(xiàn)有工具簡單地復(fù)制進(jìn) Bash-it 代碼庫而應(yīng)盡量加載/集成這些工具。官方給出的范例是nvmBash-it 不再內(nèi)置 nvm 腳本而是由 plugins/available/nvm.plugin.bash 嘗試加載用戶已有的 nvm 安裝。從 plugins/available/nvm.plugin.bash 源碼可以完整看到這一集成優(yōu)先的落地方式export NVM_DIR${NVM_DIR:-$HOME/.nvm} # first check if NVM is managed by brew NVM_BREW_PREFIX if _bash_it_homebrew_check; then NVM_BREW_PREFIX$(brew --prefix nvm 2 /dev/null) fi # This loads nvm if [[ -n $NVM_BREW_PREFIX -s ${NVM_BREW_PREFIX}/nvm.sh ]]; then source ${NVM_BREW_PREFIX}/nvm.sh else [[ -s $NVM_DIR/nvm.sh ]] source $NVM_DIR/nvm.sh fi if ! _command_exists nvm; then function nvm() { echo Bash-it no longer bundles the nvm script. Please install the latest version ... } nvm fi它的思路是優(yōu)先檢查 Homebrew 托管的 nvmbrew --prefix nvm其次回退到用戶$HOME/.nvm下的標(biāo)準(zhǔn)安裝如果都沒找到則定義一個提示性的nvm函數(shù)引導(dǎo)用戶自行安裝。這樣做的代價是用戶需要多一步從 nvm 自己的倉庫或通過包管理器安裝 nvm但好處是nvm 可以被輕松升級Bash-it 不會因捆綁舊版腳本而拖慢工具迭代。主題Theme貢獻(xiàn)截圖、描述與文檔缺一不可提交新主題時請在 PR 的描述description字段中附上截圖和一段簡述該主題獨(dú)特性的文字。不要把主題截圖提交進(jìn) PR 本體——它們會給主分支帶來不必要的體積膨脹。主題相關(guān)約定還有兩條項目文檔的 Themes 頁面 匯總了 Bash-it 內(nèi)置主題的截圖與文檔索引貢獻(xiàn)者應(yīng)在其中添加截圖添加方法見下文添加截圖一節(jié)。理想情況下應(yīng)在 docs/themes-list 目錄中新增一個theme_name.rst文件描述該主題及其配置選項。從倉庫現(xiàn)狀看該目錄下的 barbuk.rst、powerline.rst、nwinkler_random_colors.rst 等即是為各主題維護(hù)的文檔條目而 index.rst 通過.. toctree::的:glob:方式自動收錄目錄內(nèi)所有主題文檔并提供了按字母排序的截圖列表。添加截圖走 gh-pages 分支為新增主題添加截圖的正確姿勢是使用gh-pages分支把新截圖添加到docs/images文件夾打開一個 PR參照 Themes 頁面 中其他截圖的寫法確定你的鏈接格式。需要說明的是截圖實(shí)際托管在 gh-pages 分支而非 master 分支上文檔頁中的截圖均通過https://bash-it.github.io/bash-it/docs/images/...形式引用這正是不把截圖并入主分支、避免 master 膨脹的核心原因。結(jié)語一份可直接執(zhí)行的貢獻(xiàn)清單把以上規(guī)范濃縮成提交 Bash-it 前的自檢清單從master切出功能分支一個 PR 只做一件事新增/修改的文件已加入 clean_files.txt并運(yùn)行 lint_clean_files.sh 確認(rèn) lint 通過縮進(jìn)為 tabsshell 腳本與 bats 用例函數(shù)名用-分隔、內(nèi)部函數(shù)以下劃線開頭調(diào)用外部命令時使用command內(nèi)建用about-plugin/about/group/param/example等 meta 函數(shù)寫好文檔所有$BASH_IT均加雙引號避免 Bash 4 專屬特性運(yùn)行test/run為新增/變更功能補(bǔ)充 bats 測試用例確認(rèn) CILinux macOS通過新插件/補(bǔ)全優(yōu)先集成既有工具而非復(fù)制新主題在 PR 描述中附截圖與簡介并把theme_name.rst與截圖分別提交到對應(yīng)位置參照 docs/contributing.rst 與本文的源碼級注解即使是第一次向 Bash-it 提交代碼的貢獻(xiàn)者也能平穩(wěn)地走完從 fork 到合并的完整流程。贊分享CLI【免費(fèi)下載鏈接】bash-itA community Bash framework.項目地址https://gitcode.com/gh_mirrors/ba/bash-it點(diǎn)擊查看免費(fèi)下載相關(guān)推薦Powerline 代碼貢獻(xiàn)指南從分支規(guī)范、代碼風(fēng)格到測試與提交合并的完整工程實(shí)踐Powerline 代碼貢獻(xiàn)指南從分支規(guī)范、代碼風(fēng)格到測試與提交合并的完整工程實(shí)踐 Powerline 是一個用 Python 編寫的狀態(tài)欄插件框架為 vi開發(fā)工具CLILangChainGo 貢獻(xiàn)指南從代碼風(fēng)格、httprr 測試到 PR 提交流程的完整實(shí)戰(zhàn)手冊LangChainGo 貢獻(xiàn)指南從代碼風(fēng)格、httprr 測試到 PR 提交流程的完整實(shí)戰(zhàn)手冊 LangChainGo langchaingo 是使用 G人工智能大模型AI AgentRAG后端Anubis 貢獻(xiàn)指南實(shí)戰(zhàn)從構(gòu)建、測試到代碼風(fēng)格與提交規(guī)范Anubis 貢獻(xiàn)指南實(shí)戰(zhàn)從構(gòu)建、測試到代碼風(fēng)格與提交規(guī)范 本篇指南基于 Anubis 項目官方貢獻(xiàn)文檔 docs/docs/developer/CONTR后端網(wǎng)絡(luò)安全創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考