git-extras 的 git contrib 命令：按作者名或邮箱统计并展示个人贡献清单

本篇技术指南围绕 git-extras 项目中的 git contrib 命令展开，讲解如何基于提交作者名称或邮箱（支持部分匹配）快速列出某位开发者对当前仓库的全部贡献记录，并深入其底层实现原理、Shell 补全配置及同族统计命令的配合使用。读完本文，你将掌握 git contrib 的完整用法，并理解它是如何基于原生 git shortlog 构建的。

命令定位：一键输出某个用户的提交贡献

git contrib 是 git-extras 提供的众多 Git 效率工具之一，其功能定位清晰：按提交作者（author）的姓名或邮箱，输出该用户对当前项目的全部贡献列表。它非常适合在以下场景使用：

• 代码评审前快速回顾某个开发者最近提交过哪些改动；
• 排查某行功能或模块的变更时，确认某位贡献者涉及的所有提交；
• 为技术文档、发布说明整理特定作者的贡献清单。

该命令在 man/git-contrib.md 中有完整的手册页定义，在 Commands.md 的命令总览中也有对应示例，同时在 man/git-extras.md 的工具列表中登记为 “Show user's contributions”。

语法与参数说明

git contrib 的命令语法非常简洁，只有一个可选位置参数：

git-contrib [<username>|<email>]

参数	说明
<username>	提交作者的姓名或邮箱，用于定位贡献所属用户；既支持完整姓名，也支持邮箱的部分匹配（例如 tj@）

核心行为：

• 按作者名或邮箱筛选提交：命令会把传入的字符串作为 author 过滤条件，交给底层 Git 提交统计逻辑处理；
• 多匹配返回：如果仓库中存在多个姓名或邮箱都匹配该字符串的提交作者，命令会分别列出每个作者的贡献条目，不会只取第一个；
• 缺参报错：不带任何参数调用时，命令会向标准错误输出提示信息并退出（详见下文源码分析）。

使用示例：按用户名与邮箱检索

手册页 man/git-contrib.md 给出了两类典型用法。

按用户名搜索

$ git contrib visionmedia
visionmedia (18):
  Export STATUS_CODES
  Moved help msg to node-repl
  Added multiple arg support for sys.puts(), print(), etc.
  Fix stack output on socket error
  ...

输出以 作者名 (提交数): 开头，随后逐行列出自该作者的提交摘要。这里 “visionmedia (18)” 表示该用户名下有 18 条提交，每条缩进一行展示。

按部分邮箱搜索

$ git contrib tj@
visionmedia (18):
  Export STATUS_CODES
  Moved help msg to node-repl
  Added multiple arg support for sys.puts(), print(), etc.
  Fix stack output on socket error
  ...

传入 tj@ 这样的邮箱前缀片段，同样能命中该邮箱对应的作者并列出全部贡献。这说明过滤条件对邮箱字符串执行的是包含式部分匹配，无需输入完整的邮箱地址。

在 Commands.md 中收录的示例与此一致，是项目文档层面验证过的标准输出格式。

源码原理：一行核心命令包装 git shortlog

git contrib 的实现极其精简，完整源码位于 bin/git-contrib，全文如下：

#!/usr/bin/env bash

user="$*"

test -z "$user" && echo "user name required." 1>&2 && exit 1

git shortlog --format=format:"%h %s" --author="$user"

从源码结构可以拆解出它的三个关键实现环节：

1. 参数收集：使用 user="$*" 收集所有位置参数拼接成一个字符串。这意味着用户名中含空格（如 John Smith）时，可以不加引号直接传入，多个词会自动合并为完整姓名，这正是 History.md 中记录的 “Fixed handling off spaces in contributor's name” 修复成果；
2. 空参数校验：test -z "$user" 检测参数是否为空，为空时向 1>&2（标准错误）输出 user name required. 并以退出码 1 结束，保证错误信息不混入正常输出流；
3. 核心统计委托给原生 Git：真正执行统计的是 git shortlog 命令，--author="$user" 传入筛选条件，--format=format:"%h %s" 让每条提交以「短哈希 + 提交摘要」的格式呈现。git shortlog 原生就具有按作者分组、自动统计每人提交次数的能力，git contrib 通过这一调用直接复用了它，从而天然支持多作者匹配时分别列出各组的输出格式（作者名 (提交数): 的头部正是 shortlog 的分组摘要格式）。

此外，History.md 记录了 git-contrib 曾经历 “refactor, and conform to git” 的重构，使其更贴合原生 Git 的行为习惯；History.md 还修复过 “username is in a commit msg” 的误匹配问题，说明作者过滤始终锁定在 commit 的 author 字段而非消息文本。

便捷补全：Bash / Zsh / Fish 三端支持

git contrib 在 git-extras 的三套 Shell 补全脚本中都注册了针对作者名的补全，输入时可以少敲很多键。

Bash 补全

在 etc/bash_completion.sh 中，_git_contrib() 通过 git shortlog -s | cut -f2 提取仓库中所有出现过作者的姓名列表作为候选词，再交由 compgen 按当前输入做模糊匹配：

_git_contrib(){
  contributors="$(git shortlog -s | cut -f2)"
  local all c s=$'\n' IFS=$'\n'
  local cur="${COMP_WORDS[COMP_CWORD]}"
  for c in $contributors; do
    all="$all$c $s"
  done
  COMPREPLY=($(compgen -W "$all" -- "$cur"))
}

值得注意，这里取作者名用的同样是 git shortlog -s——与命令本身的核心统计同源，保证补全候选与实际可查询对象一致。

Zsh 补全

在 etc/git-extras-completion.zsh 中，_git-contrib() 将参数绑定到 __gitex_author_names 这一作者名校验函数上，提供类型化补全；同时该文件在第 427 行把命令描述登记为 contrib:'show user contributions'，与手册页定义保持一致。

Fish 补全

在 etc/git-extras.fish 中，命令被描述为 "contrib:Show user's contributions"，沿用 fish 的补全描述体系。

与同族统计命令的配合

git contrib 关注的是「某一位作者的贡献明细」，而 git-extras 中还有一组从不同维度做贡献统计的命令，可以组合起来形成完整的贡献分析视角：

命令	关注维度	对应文档
git contrib	指定作者的全部提交列表	man/git-contrib.md
git summary	全仓库各作者提交数汇总与仓库概览	man/git-summary.md
git effort	每个文件被修改的次数与活跃天数	man/git-effort.md
git guilt	每个文件各行由哪位作者贡献	man/git-guilt.md
git authors	生成 AUTHORS/contributors 文件	man/git-authors.md

例如，先用 git summary 看整体提交分布，再用 git contrib <作者> 下钻到某个作者的具体提交，配合 git effort 定位其改动集中度最高的文件，即可快速完成一次完整的贡献分析。

使用注意事项

• 必须在 Git 仓库内运行：命令依赖 git shortlog 读取当前仓库的提交历史，在非仓库目录下执行会得到 Git 的原生报错；
• 匹配的是 author 而非 committer：--author 过滤对应提交的作者身份字段，不区分大小写地做包含匹配；
• 部分邮箱匹配的代价：过短的前缀（如 a@）可能同时命中多个邮箱，命令会按 shortlog 的分组格式分别列出各组，这是设计预期行为而非错误；
• 输出可进一步管道处理：由于输出就是标准文本，可以继续用 grep、head、wc -l 等做二次加工，例如 git contrib tj@ | wc -l 统计输出行数。

小结

git contrib 是 git-extras 中「小而美」的典型命令：它没有自己重造统计逻辑，而是精妙地包装了原生的 git shortlog，通过 --author 过滤与 %h %s 格式声明，让作者贡献清单的输出变得一行即可获得。配合 Bash、Zsh、Fish 三端的作者名补全，以及 git summary、git effort、git guilt 等同族命令，你可以快速构建一套从仓库整体到个人明细的完整贡献分析工作流。更多命令索引可查阅 man/git-extras.md 与 Commands.md。