git-bug 命令模式约定详解可预测、可脚本化的 CLI 设计规范【免费下载链接】git-bugDistributed, offline-first bug tracker embedded in git项目地址: https://gitcode.com/GitHub_Trending/gi/git-bug导读git-bug 是一个内嵌于 git 的分布式、离线优先的 bug 跟踪器其全部能力都通过命令行暴露。为了让这套命令体系可被猜中、可被记忆、可被脚本化git-bug 在 doc/design/cli-convention.md 中定义了一条精炼的命令模式约定Pattern从list列出、new创建、rm删除、show查看到select/deselect隐式选择每个动词都有固定的语义。本文以该规范为骨架结合commands/目录下的真实实现逐条拆解每条模式的源码依据、参数细节与底层机制帮助读者掌握 git-bug 命令的设计哲学并能在实际使用中快速推断任意未学过的子命令用法。一、为什么需要一套命令约定git-bug 与传统的集中式 bug 跟踪器不同bug 数据以 git 对象形式存储天然支持 push/pull 同步与离线使用。这带来了一个直接后果——实体Entity种类多、操作组合多实体有bugbug 及其评论、标签、状态、标题、user身份、label标签、bridge与 GitHub/GitLab/Jira 等外部跟踪器的桥接等每个实体又有创建、删除、查看、修改、隐式选择等大量操作。如果每个命令都各自起名学习成本会急剧上升。因此 git-bug 在项目设计文档中明确规定所有 CLI 命令必须一致地遵循同一套模式让猜命令变成一件可靠的事。从架构上看所有 CLI 命令都集中在 commands/ 包中基于 cobra 的commands一节这也让命令约定的执行有了统一的载体。二、约定骨架一行一种模式原规范文档给出了完整骨架逐条如下xxx -- list xxx things if list, otherwise show one xxx new -- create thing xxx rm -- delete thing xxx show ID -- show one xxx show -- show one with select implied ID xxx yyy -- action commands for that thing, or subcommand xxx select|deselect -- select/deselect implied ID其中xxx是实体名如bug、userID是实体 ID 前缀yyy是动作动词。下面逐条对照源码验证。三、裸命令xxx默认列出规范不带子命令时若该实体可列举则列出否则显示这一个。git-bug 的裸命令全部承担列出职责且无一例外命令源码中的 Short 描述文件git bug [QUERY]List bugscommands/bug/bug.gogit userList identitiescommands/user/user.gogit labelList valid labelscommands/label.gogit bridgeList bridges to other bug trackerscommands/bridge/bridge.go以bug为例它是唯一支持查询参数的实体命令Use: bug [QUERY]可以传入status:open sort:edit-desc这类查询语言、--status/--by等过滤 flag或直接做全文搜索三者可组合随后通过env.Backend.Bugs().Query(q)查询并渲染。输出格式由--format/-f控制合法值为default、plain、id、json、org-modecommands/bug/bug.go便于脚本消费。注意bug的裸命令不承担show one的角色——因为 bug 是可列举的所以展示单个的职责交给了show子命令见第四节这与规范中 list xxx things if list 的分支完全吻合。四、xxx new与xxx rm创建与删除规范new创建实体rm删除实体。这两条在所有实体上高度一致git bug newUse: newShort Create a new bugcommands/bug/bug_new.go。支持--title/-t、--message/-m、--file/-F从文件或 stdin 读取正文-表示标准输入、--non-interactive。不带任何参数时会打开编辑器交互式输入commands/bug/input/input.go创建后打印xxxxxxxx createdgit user newShort Create a new identitycommands/user/user_new.go。支持--name/-n、--email/-e、--avatar/-a、--non-interactive交互模式下会用 git 已有的 user.name/user.email 作为默认值GetUserName()/GetUserEmail()并在首次创建时自动将该身份设为当前身份SetUserIdentitygit bridge newShort Configure a new bridgecommands/bridge/bridge_new.go。交互模式会引导选择 targetgithub/gitlab/jira/launchpad-preview、命名、选择项目与凭证也可全 flag 化--name/-n、--target/-t、--owner/-o、--project/-p、--url/-u、--base-url/-b、--login/-l、--token或--token-stdin从标准输入安全读取、--credential/-c复用已存凭证。删除侧git bug rm BUG_IDUse: rm BUG_IDShort Remove an existing bugcommands/bug/bug_rm.go。源码注释明确提醒经 bridge 导入的 bug 被删除只会移除本地副本不会删除远端跟踪器上的 buggit bridge rm移除已配置的桥接。五、xxx show ID与xxx show查看一个实体规范show后跟 ID 显示指定实体不跟 ID 时显示隐式选择select的实体。git-bug 中show类命令统一把目标 ID 声明为可选参数git bug show [BUG_ID]Short Display the details of a bugcommands/bug/bug_show.go。默认格式渲染头部ID、状态、标题、作者、编辑时间、labels、actors、participants 以及全部评论也支持--format/-fdefault/json/org-mode和--field可单选author、title、status、labels等 13 个字段git user show [USER_ID]Short Display a user identitycommands/user/user_show.go同样支持--field/-f更细粒度的单字段查看也遵循同样的可选 ID 模式git bug status [BUG_ID]、git bug title [BUG_ID]、git bug label [BUG_ID]、git bug comment [BUG_ID]都声明Use: xxx [BUG_ID]其中 comment 的语义是列出某 bug 的评论。当[BUG_ID]被省略时这些命令统一走隐式选择机制ResolveSelected这正是下一条模式的核心。六、xxx select|deselect隐式 ID 机制规范select设置隐式 IDdeselect清除之后所有需要 ID 的命令都可省略该参数。源码中的完整流程示例见 commands/bug/bug_select.go 与 commands/bug/bug_deselect.gogit bug select 2f15 git bug comment git bug status git bug deselect其底层实现在 commands/select/select.go机制非常直接存储Select把所选实体的完整 ID 写入本地存储中的select/namespace文件repo.LocalStorage().OpenFile(filename, ...)bug实体的 namespace 即bug.NamespaceClear则直接删除该文件读取与校验selected读取该文件校验长度应小于 100 字节、校验 ID 合法性再通过resolver.Resolve(id)解析出缓存实体若文件内容非法会自动删除并报错回退解析Resolve的优先级是先尝试把命令的第一个参数当作实体 ID 前缀解析resolver.ResolvePrefix(args[0])解析成功即使用并从参数中移除该前缀返回args[1:]仅当第一个参数不是合法 ID 前缀entity.IsErrNotFound时才回退到已选择的实体错误语义两者都没有时返回ErrNoValidId错误信息为you must provide a {typename} id or use the select command first若已选择的实体已失效则自动清除选择并报同样的错误。这套设计让git bug show、git bug comment new、git bug status close等命令在专注操作当前 bug的交互式工作流中完全免去重复输入 ID 的负担同时在脚本里又能随时用显式 ID 覆盖隐式选择。七、xxx yyy动作动词与子命令树的组织规范yyy是该实体上的动作命令或进一步的下级子命令。这是模式中弹性最大的一条git-bug 用它构建了两层树7.1 动作子命令直接挂在实体下git bug comment new/git bug comment edit新增评论AddComment后Commit()与编辑评论commands/bug/bug_comment_add.go、commands/bug/bug_comment_edit.gogit bug label new/git bug label rm给 bug 增删标签commands/bug/bug_label.gogit bug status open/git bug status close改变 bug 状态commands/bug/bug_status.go 挂载 bug_status_open.gogit bug title edit修改标题commands/bug/bug_title.gogit user adopt USER_ID采用某个已有身份作为当前身份commands/user/user_adopt.goArgs: cobra.ExactArgs(1)git bridge auth及其add-token/rm/show子命令、git bridge pull、git bridge pushcommands/bridge/bridge.go。注意这里查看动作与修改动作的边界status、title、label、comment这类词本身既是查看子命令无参数时查看可选 ID又是修改动作的命名空间xxx yyy如status close完美呼应了规范中 xxx yyy -- action commands for that thing, or subcommand 的或字——同一个词在两层含义间复用靠有无下级子命令来区分语义。7.2 顶层命令按职责分组在 commands/root.go 中所有顶层命令被归入三组方便用户按意图检索帮助分组命令Entities实体git bug、git user、git labelInteractive interfaces交互界面git termui、git webuiInteraction with the outside world与外部世界交互git pull、git push、git bridge另有不属于任何组的git version、git wipe。其中pull/push直接对应 git-bug 的分布式本质git bug pull [REMOTE]会先Fetch(remote)再从该 remoteMergeAll合并新数据远程默认从 git 配置项git-bug.remote读取、缺省为origincommands/pull.go。八、约定带来的工程收益从实现与测试两个层面这套约定都持续产生价值可预测性见到新实体如未来的新 bridge 目标就能直接推断xxx、xxx new、xxx rm、xxx show、xxx select的存在与语义脚本友好所有列表命令都支持--formatjsonbug还支持plain/id/org-mode展示命令支持--field单字段提取配合select/deselect可写出稳定的自动化流水线一致的隐式选择错误处理ResolveSelected被show、status、title、label、comment、comment new等多个命令共用见 commands/bug/bug_show.go 对ResolveSelected(env.Backend, args)的调用保证缺 ID时所有命令报出同一条可预期的错误文档自动生成由于全部基于 cobra 实现见 doc/design/architecture.mdbash/zsh 补全、man page、markdown 文档均可自动生成——仓库 doc/man/ 与 doc/md/ 下的git-bug-bug-*、git-bug-bridge-*等文档文件正是由同一套命令定义生成的约定的一致性也同步到了帮助文档与补全中。九、小结git-bug 用一份不足 15 行的规范 doc/design/cli-convention.md 约束住了整套 CLI 的形态裸命令列出、new/rm创建与删除、show [ID]/show显式与隐式查看、yyy动作或子命令、select/deselect管理隐式 ID。对照commands/源码可以看到bug、user、label、bridge四大实体无一例外地遵循该模式隐式选择机制由 commands/select/select.go 统一实现。对使用者而言记住这一条模式就等于记住了 git-bug 的大半命令对二次开发者而言新增实体或命令时只需照此模式在commands/下添加 cobra 命令并挂载到 commands/root.go 即可且能自动获得补全、文档与一致的交互体验。【免费下载链接】git-bugDistributed, offline-first bug tracker embedded in git项目地址: https://gitcode.com/GitHub_Trending/gi/git-bug创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 git-bug 命令模式约定详解：可预测、可脚本化的 CLI 设计规范
git-bug 命令模式约定详解可预测、可脚本化的 CLI 设计规范【免费下载链接】git-bugDistributed, offline-first bug tracker embedded in git项目地址: https://gitcode.com/GitHub_Trending/gi/git-bug导读git-bug 是一个内嵌于 git 的分布式、离线优先的 bug 跟踪器其全部能力都通过命令行暴露。为了让这套命令体系可被猜中、可被记忆、可被脚本化git-bug 在 doc/design/cli-convention.md 中定义了一条精炼的命令模式约定Pattern从list列出、new创建、rm删除、show查看到select/deselect隐式选择每个动词都有固定的语义。本文以该规范为骨架结合commands/目录下的真实实现逐条拆解每条模式的源码依据、参数细节与底层机制帮助读者掌握 git-bug 命令的设计哲学并能在实际使用中快速推断任意未学过的子命令用法。一、为什么需要一套命令约定git-bug 与传统的集中式 bug 跟踪器不同bug 数据以 git 对象形式存储天然支持 push/pull 同步与离线使用。这带来了一个直接后果——实体Entity种类多、操作组合多实体有bugbug 及其评论、标签、状态、标题、user身份、label标签、bridge与 GitHub/GitLab/Jira 等外部跟踪器的桥接等每个实体又有创建、删除、查看、修改、隐式选择等大量操作。如果每个命令都各自起名学习成本会急剧上升。因此 git-bug 在项目设计文档中明确规定所有 CLI 命令必须一致地遵循同一套模式让猜命令变成一件可靠的事。从架构上看所有 CLI 命令都集中在 commands/ 包中基于 cobra 的commands一节这也让命令约定的执行有了统一的载体。二、约定骨架一行一种模式原规范文档给出了完整骨架逐条如下xxx -- list xxx things if list, otherwise show one xxx new -- create thing xxx rm -- delete thing xxx show ID -- show one xxx show -- show one with select implied ID xxx yyy -- action commands for that thing, or subcommand xxx select|deselect -- select/deselect implied ID其中xxx是实体名如bug、userID是实体 ID 前缀yyy是动作动词。下面逐条对照源码验证。三、裸命令xxx默认列出规范不带子命令时若该实体可列举则列出否则显示这一个。git-bug 的裸命令全部承担列出职责且无一例外命令源码中的 Short 描述文件git bug [QUERY]List bugscommands/bug/bug.gogit userList identitiescommands/user/user.gogit labelList valid labelscommands/label.gogit bridgeList bridges to other bug trackerscommands/bridge/bridge.go以bug为例它是唯一支持查询参数的实体命令Use: bug [QUERY]可以传入status:open sort:edit-desc这类查询语言、--status/--by等过滤 flag或直接做全文搜索三者可组合随后通过env.Backend.Bugs().Query(q)查询并渲染。输出格式由--format/-f控制合法值为default、plain、id、json、org-modecommands/bug/bug.go便于脚本消费。注意bug的裸命令不承担show one的角色——因为 bug 是可列举的所以展示单个的职责交给了show子命令见第四节这与规范中 list xxx things if list 的分支完全吻合。四、xxx new与xxx rm创建与删除规范new创建实体rm删除实体。这两条在所有实体上高度一致git bug newUse: newShort Create a new bugcommands/bug/bug_new.go。支持--title/-t、--message/-m、--file/-F从文件或 stdin 读取正文-表示标准输入、--non-interactive。不带任何参数时会打开编辑器交互式输入commands/bug/input/input.go创建后打印xxxxxxxx createdgit user newShort Create a new identitycommands/user/user_new.go。支持--name/-n、--email/-e、--avatar/-a、--non-interactive交互模式下会用 git 已有的 user.name/user.email 作为默认值GetUserName()/GetUserEmail()并在首次创建时自动将该身份设为当前身份SetUserIdentitygit bridge newShort Configure a new bridgecommands/bridge/bridge_new.go。交互模式会引导选择 targetgithub/gitlab/jira/launchpad-preview、命名、选择项目与凭证也可全 flag 化--name/-n、--target/-t、--owner/-o、--project/-p、--url/-u、--base-url/-b、--login/-l、--token或--token-stdin从标准输入安全读取、--credential/-c复用已存凭证。删除侧git bug rm BUG_IDUse: rm BUG_IDShort Remove an existing bugcommands/bug/bug_rm.go。源码注释明确提醒经 bridge 导入的 bug 被删除只会移除本地副本不会删除远端跟踪器上的 buggit bridge rm移除已配置的桥接。五、xxx show ID与xxx show查看一个实体规范show后跟 ID 显示指定实体不跟 ID 时显示隐式选择select的实体。git-bug 中show类命令统一把目标 ID 声明为可选参数git bug show [BUG_ID]Short Display the details of a bugcommands/bug/bug_show.go。默认格式渲染头部ID、状态、标题、作者、编辑时间、labels、actors、participants 以及全部评论也支持--format/-fdefault/json/org-mode和--field可单选author、title、status、labels等 13 个字段git user show [USER_ID]Short Display a user identitycommands/user/user_show.go同样支持--field/-f更细粒度的单字段查看也遵循同样的可选 ID 模式git bug status [BUG_ID]、git bug title [BUG_ID]、git bug label [BUG_ID]、git bug comment [BUG_ID]都声明Use: xxx [BUG_ID]其中 comment 的语义是列出某 bug 的评论。当[BUG_ID]被省略时这些命令统一走隐式选择机制ResolveSelected这正是下一条模式的核心。六、xxx select|deselect隐式 ID 机制规范select设置隐式 IDdeselect清除之后所有需要 ID 的命令都可省略该参数。源码中的完整流程示例见 commands/bug/bug_select.go 与 commands/bug/bug_deselect.gogit bug select 2f15 git bug comment git bug status git bug deselect其底层实现在 commands/select/select.go机制非常直接存储Select把所选实体的完整 ID 写入本地存储中的select/namespace文件repo.LocalStorage().OpenFile(filename, ...)bug实体的 namespace 即bug.NamespaceClear则直接删除该文件读取与校验selected读取该文件校验长度应小于 100 字节、校验 ID 合法性再通过resolver.Resolve(id)解析出缓存实体若文件内容非法会自动删除并报错回退解析Resolve的优先级是先尝试把命令的第一个参数当作实体 ID 前缀解析resolver.ResolvePrefix(args[0])解析成功即使用并从参数中移除该前缀返回args[1:]仅当第一个参数不是合法 ID 前缀entity.IsErrNotFound时才回退到已选择的实体错误语义两者都没有时返回ErrNoValidId错误信息为you must provide a {typename} id or use the select command first若已选择的实体已失效则自动清除选择并报同样的错误。这套设计让git bug show、git bug comment new、git bug status close等命令在专注操作当前 bug的交互式工作流中完全免去重复输入 ID 的负担同时在脚本里又能随时用显式 ID 覆盖隐式选择。七、xxx yyy动作动词与子命令树的组织规范yyy是该实体上的动作命令或进一步的下级子命令。这是模式中弹性最大的一条git-bug 用它构建了两层树7.1 动作子命令直接挂在实体下git bug comment new/git bug comment edit新增评论AddComment后Commit()与编辑评论commands/bug/bug_comment_add.go、commands/bug/bug_comment_edit.gogit bug label new/git bug label rm给 bug 增删标签commands/bug/bug_label.gogit bug status open/git bug status close改变 bug 状态commands/bug/bug_status.go 挂载 bug_status_open.gogit bug title edit修改标题commands/bug/bug_title.gogit user adopt USER_ID采用某个已有身份作为当前身份commands/user/user_adopt.goArgs: cobra.ExactArgs(1)git bridge auth及其add-token/rm/show子命令、git bridge pull、git bridge pushcommands/bridge/bridge.go。注意这里查看动作与修改动作的边界status、title、label、comment这类词本身既是查看子命令无参数时查看可选 ID又是修改动作的命名空间xxx yyy如status close完美呼应了规范中 xxx yyy -- action commands for that thing, or subcommand 的或字——同一个词在两层含义间复用靠有无下级子命令来区分语义。7.2 顶层命令按职责分组在 commands/root.go 中所有顶层命令被归入三组方便用户按意图检索帮助分组命令Entities实体git bug、git user、git labelInteractive interfaces交互界面git termui、git webuiInteraction with the outside world与外部世界交互git pull、git push、git bridge另有不属于任何组的git version、git wipe。其中pull/push直接对应 git-bug 的分布式本质git bug pull [REMOTE]会先Fetch(remote)再从该 remoteMergeAll合并新数据远程默认从 git 配置项git-bug.remote读取、缺省为origincommands/pull.go。八、约定带来的工程收益从实现与测试两个层面这套约定都持续产生价值可预测性见到新实体如未来的新 bridge 目标就能直接推断xxx、xxx new、xxx rm、xxx show、xxx select的存在与语义脚本友好所有列表命令都支持--formatjsonbug还支持plain/id/org-mode展示命令支持--field单字段提取配合select/deselect可写出稳定的自动化流水线一致的隐式选择错误处理ResolveSelected被show、status、title、label、comment、comment new等多个命令共用见 commands/bug/bug_show.go 对ResolveSelected(env.Backend, args)的调用保证缺 ID时所有命令报出同一条可预期的错误文档自动生成由于全部基于 cobra 实现见 doc/design/architecture.mdbash/zsh 补全、man page、markdown 文档均可自动生成——仓库 doc/man/ 与 doc/md/ 下的git-bug-bug-*、git-bug-bridge-*等文档文件正是由同一套命令定义生成的约定的一致性也同步到了帮助文档与补全中。九、小结git-bug 用一份不足 15 行的规范 doc/design/cli-convention.md 约束住了整套 CLI 的形态裸命令列出、new/rm创建与删除、show [ID]/show显式与隐式查看、yyy动作或子命令、select/deselect管理隐式 ID。对照commands/源码可以看到bug、user、label、bridge四大实体无一例外地遵循该模式隐式选择机制由 commands/select/select.go 统一实现。对使用者而言记住这一条模式就等于记住了 git-bug 的大半命令对二次开发者而言新增实体或命令时只需照此模式在commands/下添加 cobra 命令并挂载到 commands/root.go 即可且能自动获得补全、文档与一致的交互体验。【免费下载链接】git-bugDistributed, offline-first bug tracker embedded in git项目地址: https://gitcode.com/GitHub_Trending/gi/git-bug创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考