git-bug user 命令完全指南：身份创建、查看、采纳与 JSON 输出

git-bug user 命令完全指南：身份创建、查看、采纳与 JSON 输出

【免费下载链接】git-bugDistributed, offline-first bug tracker embedded in git项目地址: https://gitcode.com/GitHub_Trending/gi/git-bug

导读

本文是 git-bug 分布式缺陷跟踪器中身份（Identity）子系统最核心的一组 CLI 命令实战指南。git-bug 将 Bug 以 Git 对象的形式内嵌在仓库中，而每一次 Bug 操作（创建、评论、改标题、改状态）都必须由某个身份签名产生，因此“身份管理”是使用 git-bug 的第一步。读完本文，你将完整掌握git-bug user命令族（user、user new、user show、user adopt）的全部参数、默认行为、底层实现原理与常见用法，并学会用 JSON 输出对接脚本与自动化工具。

一、身份在 git-bug 中的地位

git-bug 的核心设计是“distributed, offline-first bug tracker embedded in git”（分布式、离线优先、内嵌于 Git 的缺陷跟踪器）。正如 git-bug 主命令文档 所描述的：

git-bug uses git objects to store the bug tracking separated from the files history. As bugs are regular git objects, they can be pushed and pulled from/to the same git remote you are already using to collaborate with other people.

Bug 数据与文件历史分离，以普通 Git 对象的形式存储，因此可以借助你已有的 Git 远端进行推送和拉取。而身份（Identity）就是这一模型中的“操作者”：

• 每一次 Bug 操作（如创建 Bug、添加评论、修改标题/状态/标签）都记录在操作对象（Operation）上，并带有一个作者身份；
• 身份本身也以 Git 引用（refs）的形式存储，从 entities/identity/identity.go 可以看到两个关键常量：

const identityRefPattern = "refs/identities/" const identityRemoteRefPattern = "refs/remotes/%s/identities/"

• 同一个身份可存在多个版本（versions []*version），身份修改会追加新版本而非覆盖，这与 Bug 的 DAG（有向无环图）数据结构一脉相承，保证了离线场景下的可合并性。

正因如此，git-bug 在底层 entities/identity/identity.go 定义了明确的前置条件错误：

var ErrNoIdentitySet = errors.New("No identity is set.\n" + "To interact with bugs, an identity first needs to be created using " + "\"git bug user new\" or adopted with \"git bug user adopt\"")

也就是说，没有身份就无法与 Bug 交互——user new与user adopt就是解决这个问题的两个入口。

二、git-bug user：列出所有身份

2.1 命令概览

git-bug user [flags]

user命令的作用是列出仓库中已知的所有身份。它是身份子命令族的根命令，下辖adopt、new、show三个子命令，命令结构在 commands/user/user.go 中注册：

cmd.AddCommand(newUserNewCommand(env)) cmd.AddCommand(newUserShowCommand(env)) cmd.AddCommand(newUserAdoptCommand(env))

2.2 完整参数

2.3 实现原理：default 与 json 两种格式

runUser的执行流程非常直观（见 commands/user/user.go）：

1. 通过env.Backend.Identities().AllIds()获取全部身份 ID；
2. 逐个调用ResolveExcerpt(id)解析出轻量摘要*cache.IdentityExcerpt；
3. 按--format分发到两种格式化器。

default 格式（commands/user/user.go）：每行输出“人类可读 ID + 显示名”，其中 ID 以青色高亮显示：

env.Out.Printf("%s %s\n", colors.Cyan(user.Id().Human()), user.DisplayName(), )

json 格式（commands/user/user.go）：将每个IdentityExcerpt转换为cmdjson.Identity后整体序列化输出：

jsonUsers := make([]cmdjson.Identity, len(users)) for i, user := range users { jsonUsers[i] = cmdjson.NewIdentityFromExcerpt(user) } return env.Out.PrintJSON(jsonUsers)

cmdjson.Identity的结构定义在 commands/cmdjson/json_common.go：

type Identity struct { Id string `json:"id"` HumanId string `json:"human_id"` Name string `json:"name"` Login string `json:"login"` }

可见--format json输出的每条记录包含四个字段：完整 ID（id）、人类可读短 ID（human_id）、姓名（name）与登录名（login）。这也是 Bug 快照中嵌套身份信息的统一结构（参见 commands/cmdjson/bug.go 中BugExcerpt对Author、Actors、Participants的复用）。

2.4 示例

# 默认格式：短 ID + 显示名 git-bug user # JSON 格式，便于脚本解析 git-bug user --format json

# 等价写法 git-bug user -f json

提示：--format支持 Tab 键自动补全，合法值default、json在命令注册时通过completion.From(...)绑定（commands/user/user.go）。

三、git-bug user new：创建新身份

3.1 命令概览

git-bug user new [flags]

user new用于在当前仓库中创建并注册一个新身份。它是绝大多数用户接触 git-bug 的第一个命令。

3.2 完整参数

3.3 交互式与非交互式行为

从 commands/user/user_new.go 的实现可以看出，命令会优先复用 Git 全局用户配置作为默认值：

• 交互模式下，若未提供--name，会先调用env.Backend.GetUserName()读取 Git 用户名作为预填值，再通过input.PromptDefault("Name", "name", preName, input.Required)弹出带默认值的必填输入框；
• 邮箱同理，读取GetUserEmail()作为默认值；
• 头像 URL 没有 Git 配置可参考，直接以input.Prompt("Avatar URL", "avatar")询问（可为空）。

这意味着：如果你已配置过git config --global user.name/user.email，交互式创建时直接回车即可，体验非常顺滑。

若指定--non-interactive，则三个字段全部依赖命令行参数传入，缺失即跳过询问。

3.4 底层原理：身份如何落地

身份创建的底层链路（commands/user/user_new.go）：

1. 调用env.Backend.Identities().NewRaw(name, email, "", avatarURL, nil, nil)构建原始身份（login 为空、无密钥）；
2. 调用id.CommitAsNeeded()将身份写入 Git 存储（refs/identities/...）；
3. 检查env.Backend.IsUserIdentitySet()，若当前尚未设置默认身份，则自动把新身份设为默认；
4. 最后在 stdout 输出新身份的完整 ID。

也就是说，user new创建的第一个身份会自动成为“当前用户”，用户无需额外执行user adopt。

对应的领域层实现在 entities/identity/identity.go：NewIdentity/NewIdentityFull通过newVersion生成身份的第一个版本，身份由name、email、login、avatarUrl、keys构成。

3.5 示例

# 交互式创建（自动预填 Git 用户名/邮箱） git-bug user new # 非交互式创建 git-bug user new --non-interactive \ --name "Alice" \ --email "alice@example.com" \ --avatar "https://example.com/alice.png"

四、git-bug user show：查看单个身份

4.1 命令概览

git-bug user show [USER_ID] [flags]

user show用于展示某个身份的详细信息。USER_ID为可选参数：

• 传入 USER_ID：显示指定身份；
• 不传参数：显示当前默认身份（即本机操作者）。

4.2 完整参数

4.3 字段取值详解

--field支持 8 个取值（commands/user/user_show.go），作用如下：

其中lastModification的时间格式为 Go 的Mon Jan 2 15:04:05 2006 -0700（如Mon Jan 2 15:04:05 2026 +0800）。Lamport 时钟是 git-bug 在无中心时钟的离线场景下为事件排序的核心机制（见 util/lamport/clock.go），这里输出的就是该身份最新修改在各命名空间的逻辑时钟值。

4.4 默认输出与 ID 前缀解析

不带--field时，user show会打印完整信息：Id、Name、Email、Login、Last modification、各命名空间 Lamport 时钟以及全部不可变元数据（commands/user/user_show.go）。

值得注意的两个实现细节：

1. USER_ID 支持前缀匹配：传入的 ID 通过env.Backend.Identities().ResolvePrefix(args[0])解析（commands/user/user_show.go），因此可以使用git-bug user列出的短 ID 进行查询；
2. 单次只能查看一个身份：若传入多于一个参数，直接返回错误only one identity can be displayed at a time（commands/user/user_show.go）。

另外，user show的PreRunE是execenv.LoadBackendEnsureUser(env)，与user new、user adopt的LoadBackend不同——它要求当前环境必须已设置默认身份，否则会报错（对应上文提到的ErrNoIdentitySet）。

4.5 示例

# 显示当前默认身份的完整信息 git-bug user show # 显示指定身份的完整信息（支持短 ID） git-bug user show 3a9f1b2c # 只取邮箱字段 git-bug user show --field email # 只取人类可读短 ID git-bug user show -f humanId

五、git-bug user adopt：采纳现有身份

5.1 命令概览

git-bug user adopt USER_ID [flags]

user adopt用于将仓库中已存在的某个身份采纳为自己的当前身份。典型场景：

• 你 clone 了一个团队仓库，里面已有其他人推送上来的身份，希望直接用其中一个作为本机操作身份；
• 你换了一台机器，想让本机默认身份与之前的身份保持一致，从而在离线/分布式同步时保持作者一致。

5.2 完整参数

注意：USER_ID是必填位置参数，源码通过cobra.ExactArgs(1)强制校验（commands/user/user_adopt.go），少传、多传都会直接报错。

5.3 实现原理

runUserAdopt只有三步（commands/user/user_adopt.go）：

1. env.Backend.Identities().ResolvePrefix(prefix)：按前缀解析出目标身份（同样支持短 ID）；
2. env.Backend.SetUserIdentity(i)：将默认身份设置为本地的git-bug.identity配置项（对应 entities/identity/identity.go 中的identityConfigKey）；
3. 输出确认信息：Your identity is now: <显示名>。

与user new一样，adopt的命令参数也支持 Tab 自动补全（completion.User(env)，commands/user/user_adopt.go），交互体验友好。

5.4 示例

# 列出所有身份，找到要采纳的短 ID git-bug user # 采纳指定身份 git-bug user adopt 3a9f1b2c # 输出示例 # Your identity is now: Alice <alice@example.com>

六、命令族完整速查表

子命令的 SEE ALSO 导航：四份命令文档互相链接，完整结构见 git-bug_user.md、git-bug_user_adopt.md、git-bug_user_new.md、git-bug_user_show.md，对应的 roff 手册页位于 git-bug-user.1 及同目录其他.1文件。

七、最佳实践与注意事项

1. 先创建身份，再操作 Bug：git-bug 要求必须先有身份才能交互（ErrNoIdentitySet），首次使用请先执行git-bug user new或git-bug user adopt。
2. 复用 Git 用户配置：交互式user new会自动预填 Git 的user.name/user.email，保持与 Git 提交者信息一致可以降低团队协作时的识别成本。
3. 短 ID 前缀匹配：user show与user adopt都支持 ID 前缀解析，日常使用git-bug user列出的短 ID 即可，无需复制完整哈希。
4. 脚本化集成首选 JSON：git-bug user --format json输出结构化数据，字段固定为id、human_id、name、login，可直接交给jq、Python、Node 等工具处理，用于自动化巡检身份列表。
5. 分布式协作下的身份一致：在多机/多人协作时，通过git-bug user adopt采纳同一身份，可以保证来自同一作者的操作在合并（push/pull）后归属正确，这是离线优先模型下避免作者错乱的关键一步。

结语

git-bug user命令族虽小，却是整个 git-bug 工作流的地基：user new负责创建、user show负责查询、user adopt负责切换、user负责总览，配合--format json可以无缝接入脚本生态。其底层实现清晰体现了 git-bug“身份即 Git 对象、离线可合并、Lamport 时钟排序”的设计哲学。掌握了这组命令，你就具备了在任意 git-bug 仓库中安全开展 Bug 协作管理的前提条件。

【免费下载链接】git-bugDistributed, offline-first bug tracker embedded in git项目地址: https://gitcode.com/GitHub_Trending/gi/git-bug