git-extras 命令手册:从仓库统计到多仓批量操作的 80+ 个 Git 增强命令实战指南

原创2026-09-30 23:38:441,953 阅读
文章标签:开发工具CLI版本控制

git-extras 命令手册:从仓库统计到多仓批量操作的 80+ 个 Git 增强命令实战指南

git-extras 是一套以 Bash 脚本形式实现的 Git 增强工具集,为原生 Git 补充了仓库统计、分支/标签管理、多仓库批量操作、提交历史改写、变更日志生成、交互式 REPL 等高频场景的便捷命令。本文以仓库根目录下的 Commands.md 为核心骨架,逐一讲解每个命令的用法、参数与输出示例,并结合 bin/ 目录下的真实实现源码(如 git-summary、git-bulk、git-repl、git-changelog)揭示底层原理。读完本文,你将能熟练使用 git-extras 的绝大多数命令,并理解其配置项与实现机制。

安装方式可参考 Installation.md;每个命令的完整 man 手册位于 man/ 目录(如 git-force-clone.md)。

总览与主命令 git extras

git extras 是工具集的入口命令(对应实现 bin/git-extras),提供版本查询、帮助与自更新三种能力:

# 输出当前版本
$ git extras --version

# 列出所有可用命令
$ git extras --help

# 更新到最新版 git-extras
$ git extras update

从源码 bin/git-extras 可以看到其分发逻辑:-v/--version 直接输出内置的 VERSION 常量(当前仓库版本为 7.6.0-dev);update 分支会先通过 uname -s 检测是否运行在 Cygwin/MINGW/MSYS 等 Windows 兼容环境,若是则走 updateForWindows(克隆仓库后用 install.cmd 安装),否则执行 update(),即用 curl 拉取 install.sh 并通过管道交给 bash 执行,随后打印更新前后的版本号;其余参数一律回退到 git extras --help。

仓库信息与统计类命令

这类命令是 git-extras 最核心、最被高频使用的部分,用来回答"仓库现在是什么状态、谁贡献了多少"。

git summary:仓库与作者统计

git summary 输出整个仓库或指定提交区间的概要信息,包括项目名、仓库年龄、当前分支、最近活跃时间、活跃天数、提交数、文件数、未提交变更数,以及按提交数排序的作者百分比列表:

$ git summary

project     : git-extras
repo age    : 10 months ago
branch      : master
last active : 3 weeks ago
active on   : 93 days
commits     : 163
files       : 93
uncommitted : 3
authors     :
   97   Tj Holowaychuk          59.5%
   37   Jonhnny Weslley         22.7%
    8   Kenneth Reitz           4.9%
    5   Aggelos Orfanakos       3.1%
    3   Jonathan "Duke" Leto    1.8%
    2   Gert Van Gool           1.2%
    ...

git summary 还可以接收一个 committish(提交引用),只统计该提交区间内的提交:

$ git summary v42..

--line 选项改为按代码行数统计作者占比,即对仓库每个文件的每一行执行 blame,再按作者聚合:

$ git summary --line

project  : git-extras
 lines    : 8420
 authors  :
 2905 Tj Holowaychuk            34.5%
 1901 Jonhnny Weslley           22.6%
 1474 nickl-                    17.5%
  ...

--line 还可以接一个路径参数,只统计该目录或文件的作者行数分布。--output-style 选项则把概要信息压缩成两种紧凑的表格/单行样式,便于脚本解析:

$ git summary --output-style tabular
# Repo     | Age       | Last active | Active on | Commits | Uncommitted | Branch
git-extras | 13 years  | 7 hours ago | 807 days  | 1703    | 3           | master

$ git summary --output-style oneline
git-extras / age: 13 years / last active: 7 hours ago / active on 807 days / commits: 1703 / uncommitted: 3 / branch: master

源码级补充:实现位于 bin/git-summary,其参数解析循环还支持 --full-path(项目名显示为完整路径)、--dedup-by-email(按邮箱合并同一作者的多重身份,实现为 dedup_by_email 函数,但该选项与 --line、--no-merges 组合时会报错退出)、--no-merges(统计时排除合并提交)。tabular/oneline 样式分别由 print_summary 函数 与 print_summary_by_line 函数 实现;作者百分比由 format_authors 用 awk 计算并借 column 对齐。注意:传入 committish 时 files 字段不会显示,因为文件计数(git ls-files)无法针对历史引用统计。

git effort:文件投入度统计

git effort 显示每个文件的"投入度"——即每个文件的提交次数,并按活跃天数着色提示活动最密集的文件(active days 列为对该文件产生过修改的总天数):

node (master): git effort --above 15 {src,lib}/*

--above 过滤掉提交数小于等于指定值的文件:

$ git effort --above 5

--since 只统计最近一段时间内的提交,语法与 git log --since 一致:

$ git effort -- --since='last month'

默认遍历 git ls-files 列出的所有文件,也可以直接传入一个或多个文件路径缩小范围:

$ git effort bin/* lib/*

git brv:按最近提交排序的分支列表

git brv 对分支按最后一次提交日期排序做漂亮展示:

$ git brv
2020-01-14 adds-git-brv fork/adds-git-brv 1ca0d76 Fixes #700: Adds git-brv
2020-01-08 master       origin/master     265b03e Merge pull request #816 from spacewander/git-sed-pathspec

分支很多时逆序查看更顺手,可通过 git-extras.brv.reverse 配置项将其设为默认:

$ git brv --reverse
2020-01-08 master       origin/master     265b03e Merge pull request #816 from spacewander/git-sed-pathspec
2020-01-14 adds-git-brv fork/adds-git-brv 1ca0d76 Fixes #700: Adds git-brv

git contrib:单个作者的贡献明细

git contrib <author> 列出指定作者的全部提交标题:

$ git contrib visionmedia
visionmedia (18):
  Export STATUS_CODES
  Replaced several Array.prototype.slice.call() calls with Array.prototype.unshift.call()
  Moved help msg to node-repl
  Added multiple arg support for sys.puts(), print(), etc.
  Fix stack output on socket error
  ...

git count:提交总数

不带参数输出仓库提交总数:

$ git count

total 1844

--all 输出按作者分组的详细提交计数:

$ git count --all

visionmedia (1285)
Tj Holowaychuk (430)
Aaron Heckmann (48)
...
total 1844

git authors:自动生成 AUTHORS 文件

git authors 按每位作者的提交数,把作者名单写入匹配 authors|contributors(大小写不敏感)的文件(通常是 AUTHORS):

$ git authors && cat AUTHORS

TJ Holowaychuk <tj@vision-media.ca>
hemanth.hm <hemanth.hm@gmail.com>
Jonhnny Weslley <jw@jonhnnyweslley.net>
nickl- <github@jigsoft.co.za>
Leila Muhtasib <muhtasib@gmail.com>

--list 只在终端列出作者而不写文件;--list --no-email 则省略邮箱。若希望把同一人的多个邮箱合并为一人,可参考 git-shortlog 的 "MAPPING AUTHORS" 机制配置 .mailmap。本仓库的 AUTHORS 文件即可视为该命令的产物示例。

git info:仓库全景信息

git info 一次性输出远程 URL、远程分支、本地分支、子模块、最近一次提交和 .git/config 配置:

$ git info

    ## Remote URLs:

    origin              git@github.com:sampleAuthor/git-extras.git (fetch)
    origin              git@github.com:sampleAuthor/git-extras.git (push)

    ## Remote Branches:

    origin/HEAD -> origin/master
    origin/myBranch

    ## Local Branches:

    myBranch
    * master

    ## Submodule(s):

      a234567 path2submodule1/submodule1 (branch/tag)
    + b234567 path2submodule2/submodule2 (branch/tag)
    - c234567 path2submodule3/submodule3 (branch/tag)

    ## Most Recent Commit:

    commit e3952df2c172c6f3eb533d8d0b1a6c77250769a7
    Author: Sample Author <sampleAuthor@gmail.com>

    Added git-info command.

    ## Configuration (.git/config):

    color.diff=auto
    ...

子模块行首的 +/-/空白分别表示"有新增内容""落后于记录版本""与记录一致"。不需要配置段落时使用 --no-config:

$ git info --no-config

时间窗口类:git commits-since 与 git standup

git commits-since [date] 列出某个日期以来的提交,日期默认是"last week":

$ git commits-since
... changes since last week
TJ Holowaychuk - Fixed readme
TJ Holowaychuk - Added git-repl

$ git commits-since yesterday
... changes since yesterday
TJ Holowaychuk - Fixed readme

git standup 用于回顾自己(或某人)在指定时间范围内做了什么。例如回顾 John 最近 7 天的提交:

git standup -a John -d 7

git local-commits:尚未推送的本地提交

列出本地分支上尚未发送到 origin 的所有提交;额外的参数会直接透传给 git log 用于过滤。

git missing:两侧独有提交对比

打印"只存在于其中一个分支"的提交:< 表示仅当前检出分支有,> 表示仅目标分支(如 master)有:

$ git missing master
< d14b8f0 only on current checked out branch
> 97ef387 only on master

可附加路径把比较限定到某个目录或文件:

$ git missing master -- src/
< ed52989 only on current branch, in src/ directory
> 7988c4b only on master, in src/ directory

git delta:与另一分支差异的文件列表

git delta 列出与另一分支相比发生变化的文件(含未暂存、已暂存两种状态):

$ touch README.md
$ git setup
$ git checkout -b hello
$ echo hello >> README.md
$ git delta
README.md
$ touch Makefile
$ git add Makefile
$ git delta
Makefile
README.md

git guilt:两次修订之间的 blame 变化

git guilt 计算两个 revision 之间 blame 归属的增减量(以 +/- 号表示新增/减少的行数归属):

$ git guilt `git log --until="3 weeks ago" --format="%H" -n 1` HEAD
Paul Schreiber                +++++++++++++++++++++++++++++++++++++++++++++(349)
spacewander                   +++++++++++++++++++++++++++++++++++++++++++++(113)
Mark Eissler                  ++++++++++++++++++++++++++
CJ                            +++++
nickl-                        -
...

分支合并状态:git show-merged-branches / git show-unmerged-branches

分别列出已合入当前 HEAD 的所有分支,以及尚未合入当前 HEAD 的所有分支,用于清理合并前的状态确认。

git show-tree:全分支装饰图

以装饰图形式展示所有分支的一行摘要提交,效果类似 git log --graph 的紧凑版本:

$ git show-tree
*   4b57684 (HEAD, develop) Merge branch upstream master.
|\
|| *   515e94a Merge pull request #128 from nickl-/git-extras-html-hyperlinks
|| |\
|| | * 815db8b (nickl/git-extras-html-hyperlinks, git-extras-html-hyperlinks) help ronn make hyperlinks.
|| * | 7398d10 (nickl/develop) Fix #127 git-ignore won't add duplicates.
...

分支与标签管理类命令

git feature:功能分支工作流

git feature <name> 创建并检出一个功能分支;第二次运行同一命令则直接检出该分支:

$ git feature dependencies

-r <remote> 让分支在远端建立跟踪关系(不指定远端名时默认推送 origin):

$ git feature dependencies -r upstream

切回主分支后再执行 git feature dependencies 就会检出已有的功能分支:

$ git checkout master
$ git feature dependencies

功能开发完成,用 git feature finish <name> 把它合并进当前分支;若该分支配置了远端跟踪,合并后远端分支也会被删除:

$ git checkout master
$ git feature finish dependencies

git create-branch / git delete-branch

创建本地分支 name:

$ git create-branch development

-r 在创建本地分支的同时,在 origin 建立远端跟踪分支:

$ git create-branch -r development

指定远端名则跟踪 upstream:

$ git create-branch -r upstream development

git delete-branch <name> 同时删除本地与远端分支:

$ git delete-branch integration

批量清理分支三兄弟

git delete-gone-branches 删除所有"远端跟踪分支已被删除"的本地分支(即 git branch -vv 中显示 [gone] 的分支)。--dry-run 可先预览将要删除的分支而不真正执行:

$ git delete-gone-branches
Deleted branch feature-123 (was abc1234).
Deleted branch feature-456 (was def5678).

$ git delete-gone-branches --dry-run
Would delete the following branches:
  feature-123
  feature-456

git delete-merged-branches 删除所有出现在 git branch --merged 中的已合并分支:

$ git delete-merged-branches
Deleted feature/themes (was c029ab3).
Deleted feature/live_preview (was a81b002).
Deleted feature/dashboard (was 923befa).
...

git delete-squashed-branches [branch] 删除已被 squash 合并进指定分支的分支(默认当前检出分支),执行时会把指定分支检出来作为副作用:

$ (feature-branch) git delete-squashed-branches main
Deleted branch dependabot/bundler/kramdown-2.3.1 (was 1d3fb00).
Deleted branch dependabot/bundler/rexml-3.2.5 (was a7e4052).
$ (main) git ...

git fresh-branch:空分支

创建一个不含父提交历史的空本地分支:

$ git fresh-branch docs

重命名三件套:git rename-branch / git rename-remote / git rename-tag

git rename-branch 重命名分支并同步到远端(git push)。传两个参数重命名任意分支,传一个参数重命名当前分支:

# renames any branch
$ git rename-branch old-name new-name

# renames current branch
$ git rename-branch new-name

git rename-remote 重命名远端(可覆盖已有名字冲突),随后列出当前全部远端:

$ git remote -v
origin	git@myserver.com:myuser/foo.git (fetch)
origin	git@myserver.com:myuser/foo.git (push)
upstream	git@myserver.com:myuser/bar.git (fetch)
upstream	git@myserver.com:myuser/bar.git (push)
$ git-rename-remote upstream origin
origin	git@myserver.com:myuser/bar.git (fetch)
origin	git@myserver.com:myuser/bar.git (push)

git rename-tag 同时重命名本地与远端的标签:

$ git tag test
$ git push --tags
Total 0 (delta 0), reused 0 (delta 0)
To git@myserver.com:myuser/myrepository.git
    * [new tag]         test -> test
$ git tag
test
$ git rename-tag test test2
Deleted tag 'test' (was 1111111)
...
$ git tag
test2

标签删除:git delete-tag

同时删除本地与远端标签:

$ git delete-tag 0.0.1

分支合并类:git merge-into / git graft / git squash

git merge-into [src] dest 把 src 分支合并进 dest,但停留在当前分支;省略 src 则把当前分支合并进 dest:

$ git merge-into [src] dest

git graft src-branch dest-branch 把 src-branch 的提交合并进 dest-branch:

$ git graft new_feature master

git squash 把某分支的全部提交(或当前分支上从某提交引用起的一段提交)压缩成一个提交合入当前分支。给定 [msg] 时会以该消息调用 git-commit(1)——当主题分支内的小提交无意义、想把它当作一次整体变更时非常有用:

$ git squash fixed-cursor-styling
$ git squash fixed-cursor-styling "Fixed cursor styling"
$ git squash 95b7c52
$ git squash HEAD~3
$ git squash HEAD~3 "Work on a feature"

git psykorebase:一次冲突处理的变基

以一次 merge commit 为桥梁完成变基,全程只需处理一次冲突。将当前分支变基到 master:

$ git psykorebase master

冲突解决后继续:

$ git psykorebase --continue

也可显式指定源分支,把 feature 变基到 master 之上:

$ git psykorebase master feature

git sync:本地与远端同步

不带参数把本地分支与它的跟踪远端分支同步:

$ git sync

也可显式同步到 origin/master:

$ git sync origin master

git merge-repo:合并两个仓库历史

把另一个仓库的某个分支合并进当前仓库的指定目录:

$ git merge-repo other-repo.git master new_dir

上面把 other-repo.git 的 master 分支并入当前仓库的 new_dir 目录。下面把远端仓库的 master 并入当前仓库根目录,且不保留历史:

$ git merge-repo git@github.com:tj/git-extras.git master .

远程仓库与协作类命令

git fork:一键 Fork + Clone

git fork <repo> 相当于"先 Fork 再 Clone":

$ git fork https://github.com/LearnBoost/expect.js
# 或简写为
$ git fork LearnBoost/expect.js

它的完整流程是:Fork 该仓库(提示输入 GitHub 用户名和密码)→ 克隆到当前目录 → 把原仓库添加为 upstream 远端以便跟踪上游变更;若已配置 SSH,所有远端 refs 使用 git over SSH,否则使用 HTTPS。克隆后可见双远端结构:

$ cd expect.js && git remote -v
origin          git@github.com:<user>/expect.js (fetch)
origin          git@github.com:<user>/expect.js (push)
upstream        git@github.com:LearnBoost/expect.js (fetch)
upstream        git@github.com:LearnBoost/expect.js (push)

git force-clone:强制重置式克隆

若目标目录已存在且是 git 仓库,则把其内容重置为远端克隆:

$ git force-clone [-b {branch_name}] {remote_url} {destination_path}
$ git force-clone -b master https://github.com/tj/git-extras ./target-directory

警告:如果仓库已存在,该命令会摧毁全部本地改动——被修改的文件会被重置、本地分支会被删除。更多细节见 git-force-clone.md。

git get:克隆到配置目录

把仓库克隆到配置好的目录下的子目录中。先配置克隆路径:

$ git config --global --add git-extras.get.clone-path "$HOME/some-dir"

随后克隆(支持完整 URL 或 owner/repo 简写):

$ git get 'https://github.com/hyperupcall/bake'

git pr:检出 GitHub Pull Request

$ git pr 226
From https://github.com/tj/git-extras
 * [new ref]       refs/pulls/226/head -> pr/226
Switched to branch 'pr/226'

使用非 origin 远端(例如在 fork 中想用 upstream)时,把远端名作为第二参数:

$ git pr 226 upstream

也可以直接传 Pull Request 的完整 GitHub URL:

$ git pr https://github.com/tj/git-extras/pull/453

传入神奇的 clean 参数可清除所有本地 pr/ 分支(需确保当前分支不是其中之一):

$ git pr clean
Deleted branch 'pr/226' (was 1234567).

git mr:检出 GitLab Merge Request / Forgejo Pull Request

用法为 git mr <ID|URL> [REMOTE],默认远端是 origin:

$ git mr 51
From gitlab.com:owner/repository
 * [new ref]         refs/merge-requests/51/head -> mr/51
Switched to branch 'mr/51'

传完整 URL 时,会从指向 base URL 的临时远端抓取 head:

$ git mr https://gitlab.com/owner/repository/merge_requests/51

Forgejo/Codeberg 的 Pull Request URL 同样支持:

$ git mr https://codeberg.org/owner/repository/pulls/51
From codeberg.org:owner/repository
 * [new ref]         refs/pull/51/head -> mr/51
Switched to branch 'mr/51'

与 git pr 一样,git mr 也接受 clean 参数清空所有 mr/ 分支。该命令的行为有测试用例覆盖,见 git-mr.bats。

git pull-request

通过命令行创建 Pull Request。实现位于 bin/git-pull-request。

git paste:提交分享到 pastebin

把提交发送到 pastebin 站点(依赖 pastebinit)。默认发送当前分支与其上游分支之间的提交:

$ git paste
https://paste.debian.net/1234567/

所有选项会透传给 git format-patch --stdout,因此也可以用 git-rev-parse(1) 理解的参数选择不同的提交集合:

$ git paste @^
https://paste.debian.net/1234567/

git scp / git rscp:rsync 式文件同步

git scp <remote> [<commits>...] 把当前工作树的文件复制到远端仓库的工作目录;若提供 <commits>...,只复制该提交范围内有变更的文件。内部实际使用 rsync 而非 scp(如命令名所示)。git rscp 是反向操作:把远端工作目录中的指定文件复制回当前工作目录。

以下选项必须位于 <remote> 之前:

  -v, --verbose             Print what will be synced before syncing
  -i, --interactive         Prompt for confirmation before syncing (implies --verbose)
  -n, --dry-run             Show what would be synced, change nothing (implies --verbose)

典型用法:

# 复制未暂存文件到远端(无需提交即可快速测试)
$ git scp staging

# 复制已暂存与未暂存文件
$ git scp staging HEAD

# 复制最近一次提交变更过的文件 + 暂存/未暂存文件
$ git scp staging HEAD~1

# 复制自某个 tag 以来的变更文件
$ git scp staging v1.2.3

# 复制指定文件
$ git scp staging index.html .gitignore .htaccess

# 复制指定目录
$ git scp staging js/vendor/

该命令的交互、dry-run 等行为有测试覆盖,见 git-scp.bats。

git browse / git browse-ci:浏览器打开仓库/CI 页面

git browse [remote] 在默认浏览器中打开当前仓库的网页(upstream 等参数指定远端):

$ git browse
$ git browse upstream

git browse-ci [remote] 类似,但打开的是 CI 页面(GitHub Actions、GitLab CI、Bitbucket Pipelines 等):

$ git browse-ci
$ git browse-ci upstream

提交历史与重写类命令

git coauthor:为最近一次提交追加共同作者

git coauthor <user> <email> 修改最近一次提交,追加 Co-authored-by 行:

$ git coauthor user user@email.com

[master b62ceae] Add documentation files
 Date: Sat Aug 17 17:33:53 2019 -0500
 2 files changed, 145 insertions(+), 0 deletions(-)
 create mode 100644 README.md
 create mode 100644 CONTRIBUTING.md

$ git log -1

commit b62ceae2685e6ece071f3c3754e9b77fd0a35c88 (HEAD -> master)
Author: user person <userperson@email.com>
Date:   Sat Aug 17 17:33:53 2019 -0500

    Add documentation files

    Co-authored-by: user <user@email.com>

git reauthor:批量改写作者身份

git reauthor 重写历史以改变作者身份。把 Jack 的个人邮箱/名字替换为工作邮箱/名字:

$ git reauthor --old-email jack@perso.me --correct-email jack@work.com --correct-name 'Jack Foobar'

用 Git 配置中定义的身份替换:

$ git reauthor --old-email jack@perso.me --use-config

只替换邮箱、保留原名:

$ git reauthor --old-email jack@perso --correct-email jack@perso.me

只改 committer 邮箱、保留 author 邮箱:

$ git reauthor --old-email jack@perso.me --correct-email jack@work.com --type committer

把 Jack 设为整个仓库唯一作者:

$ git reauthor --all --correct-email jack@perso.me --correct-name Jack

把 Jack 设为整个仓库唯一 committer(保留 authors):

$ git reauthor --all --correct-email jack@perso.me --correct-name Jack --type committer

git undo:撤销最近提交

撤销最近一次提交:

git undo

撤销最近 3 次提交:

git undo 3

git stamp:为最近提交追加标注

git stamp 把任意文本追加到最近一次提交的 message 尾部。结合 bug 跟踪编号使用:

$ git stamp Issue FOO-123

commit 787590e42c9bacd249f3b79faee7aecdc9de28ec
Author: Jack <jack@work.com>
Commit: Jack <jack@work.com>

    Fix timezone bug

    Issue FOO-123

也支持带状态后缀的编号(注意 shell 中 # 需转义为 \#):

$ git stamp Issue FOO-456 \#close
...
    Issue FOO-123

    Issue FOO-456 #close

链接到评审页面:

$ git stamp Review https://reviews.foo.org/r/4567/
...
    Review https://reviews.foo.org/r/4567/

--replace 用新条目替换之前的条目(匹配大小写不敏感):

$ git stamp --replace issue BAR-123
...
    Review https://reviews.foo.org/r/4567/

    issue BAR-123

git wip / git unwip:工作进行中提交

git wip 把工作目录的全部变更(修改、新增、删除)打包成一个 WIP 提交:

$ git wip

git unwip 撤销该 WIP 提交并把所有变更放回工作目录:

$ git unwip

git magic:自动生成提交消息的提交

git magic 用自动生成的消息提交当前变更,免去手写 commit message。

git obliterate:彻底抹除文件

把文件从仓库中完全移除,包括过去的提交与标签:

git obliterate secrets.json

git rebase-patch:为过期补丁找基址变基

当补丁无法直接应用到当前 HEAD、但你知道它曾经应用于某个历史提交时,git rebase-patch 会帮你找到那个提交并完成变基:

$ git rebase-patch test.patch
Trying to find a commit the patch applies to...
Patch applied to dbcf408dd26 as 7dc8b23ae1a
First, rewinding head to replay your work on top of it...
Applying: test.patch
Using index info to reconstruct a base tree...
Falling back to patching base and 3-way merge...
Auto-merging README.txt

变基后最近一次提交即包含补丁内容,且以补丁文件名命名。

git sed:跨提交内容替换

类似 grep 定位,但会把匹配到的文件内容用给定模式替换:

$ git sed 'this' 'that'
$ git sed 'this' 'that' g
$ git sed 'this' 'that' -- path/ path2/

git reset-file:单文件重置

把单个文件重置到 HEAD 或某个指定提交:

# 重置到 HEAD
$ git reset-file .htaccess

# 重置到指定提交
$ git reset-file .htaccess dc82b19

git cp:保留历史的文件复制

把文件复制为另一个文件,同时保留其历史并支持合并冲突处理:

$ git cp README.md README.rst

git utimes:文件时间戳对齐提交日期

把文件修改时间改为其最后一次提交的日期;不改动工作树或索引中的文件。--newer 只触碰那些比提交日期更新的文件,从而保留本地提交文件的原始修改时间:

git-extras$ git utimes --newer
+ touch -d 2020-05-22T10:40:29+08:00 bin/git-archive-file
+ touch -d 2017-05-05T16:02:09+08:00 bin/git-authors
+ touch -d 2020-02-23T11:41:54+08:00 bin/git-back
[...]

git-extras$ ls -l bin | head
...
-rwxr-xr-x 1 vt vt  1043 May 22 05:40 git-archive-file
-rwxr-xr-x 1 vt vt   970 May  5  2017 git-authors

注意上例中 git-alias 因修改时间早于提交日期而未被触碰——这正是 --newer 的效果。

仓库初始化与维护类命令

git setup

初始化 git 仓库(若不存在)、添加全部文件并完成首次提交。dir 默认是当前工作目录。

git gh-pages

一键设置 gh-pages 分支,用于托管 GitHub Pages 站点。参见 GitHub Pages 官方文档了解站点构建方式。

git archive-file

把当前 git 仓库打包成 zip 归档,归档名取决于当前 HEAD:

$ git archive-file

git root

输出仓库根目录的绝对路径,便于在深层子目录快速回到根:

$ pwd
.../very-deep-from-root-directory
$ cd `git root`
$ git add . && git commit

git clear / git clear-soft

git clear 执行 hard reset 并删除工作目录中所有未跟踪文件(包括 .gitignore 中列出的文件):

$ git clear

git clear-soft 同样 hard reset 并删除未跟踪文件,但排除 .gitignore 中的文件,保留被忽略的资源:

$ git clear-soft

忽略与文件管理类命令

git ignore:快速维护 .gitignore

把模式追加进 .gitignore(自动去重),懒人福音:

$ git ignore build "*.o" "*.log"
... added 'build'
... added '*.o'
... added '*.log'

不带任何模式时,同时显示全局与本地 .gitignore 的当前内容:

$ git ignore
Global gitignore: /Users/foo/.gitignore_global
*~
.metadata
---------------------------------
Local gitignore: .gitignore
build
*.o
*.log

可用选项分别只看某一份文件:

  • -g / --global:只看全局文件
  • -l / --local:只看本地文件
  • -p / --private:只看仓库文件
$ git ignore -g
Global gitignore: /Users/foo/.gitignore_global
*~
.metadata

$ git ignore -l
Local gitignore: .gitignore
build
*.o
*.log

源码级补充:实现见 bin/git-ignore。其中 global_ignore() 会优先使用 git config --global core.excludesFile 指定的全局忽略文件;若未配置,则回退到 $HOME/.gitignore,再回退到 ${XDG_CONFIG_HOME:-$HOME/.config}/git/ignore。命令用一段 awk 脚本基于"精确行匹配"在写回前剔除重复模式,避免把同一模式写入两遍。

git ignore-io:从模板库生成 gitignore

git ignore-io <type> 从 GitHub 官方的 gitignore 模板库抓取指定类型的示例内容并显示在屏幕上:

$ git ignore-io vim

    # Created by https://raw.githubusercontent.com/github/gitignore/main/Global/Vim.gitignore

    # Swap
    [._]*.s[a-v][a-z]
    # comment out the next line if you don't need vector files
    !*.svg
    ...

写入 .gitignore 的选项:

  • -a / --append:把结果追加到 .gitignore
  • -r / --replace:用结果整体替换 .gitignore

一次请求多个类型:

$ git ignore-io vim python

出于效率考虑,git ignore-io 会把全部可用类型缓存到 ~/.gi_list。-l / -L 以两种不同格式列出全部可用类型;-s <word> / --search <word> 在列表里搜索:

$ git ignore-io -s ja

    django
    jabref
    java
    ninja

git lock / git locked / git unlock:本地文件锁

锁住本地文件(防止自己被意外提交敏感配置):

$ git lock config/database.yml

列出当前被锁的文件:

$ git locked
config/database.yml

解锁:

$ git unlock config/database.yml

git touch:创建文件并入索引

对给定文件执行 touch 并立即加入索引,一步完成新文件创建:

$ git touch newfile.txt

多仓库批量操作:git bulk

git bulk 为"对多个 git 仓库执行同一条命令"的场景提供便利:

  • 注册包含多个 git 仓库的工作区(workspace,即一个目录树)
  • 一条命令对注册工作区内的所有仓库执行任意 git 命令
  • 可启用"守卫模式"(guarded mode),每次执行前询问确认

完整用法:

usage: git bulk [-g] ([-a]|[-w <ws-name>]) <git command>
       git bulk --addworkspace <ws-name> <ws-root-directory> (--from <URL or file>)
       git bulk --removeworkspace <ws-name>
       git bulk --addcurrent <ws-name>
       git bulk --purge
       git bulk --listall

注册工作区

$ git bulk --addworkspace personal ~/workspaces/personal

<ws-root-directory> 必须是绝对路径(或指向绝对路径的环境变量)。若用单引号包裹环境变量,则会在 git-bulk 运行时才解引用,适合动态工作区(例如在 .bashrc 中定义):

$ git bulk --addworkspace personal '$PERSONAL_WORKSPACE'

--from 可附带单个仓库 URL 或一个包含多行 URL 的文件,注册时直接把仓库克隆进工作区,适合多仓库项目的初始搭建:

$ git bulk --addworkspace projectX ~/workspaces/projectx --from https://github.com/x/project-x.git

# 或者用一个每行一个仓库的文件:
$ git bulk --addworkspace projectX ~/workspaces/projectx --from ~/workspaces/repositories.txt

repositories.txt 内容示例:

https://github.com/x/project-x-1.git
https://github.com/x/project-x-2.git
https://github.com/x/project-x-3.git

把当前目录注册为工作区:

$ git bulk --addcurrent personal

列出所有已注册工作区:

$ git bulk --listall
bulkworkspaces.personal /Users/niklasschlimm/workspaces/personal

执行批量命令

在当前工作区内的所有仓库上执行命令(git 会自动补全):

$ git bulk fetch

指定某个工作区:

$ git bulk -w personal fetch

对所有工作区执行:

$ git bulk -a fetch

守卫模式:每个仓库执行前都询问确认:

$ git bulk -g fetch

移除工作区

# 移除单个工作区
$ git bulk --removeworkspace personal

# 移除全部工作区
$ git bulk --purge

源码级原理

实现位于 bin/git-bulk(231 行 Bash)。几个关键机制:

  • 存储:工作区注册在全局 .gitconfig 的 bulkworkspaces.<ws-name> 段(addworkspace/addcurrent/removeworkspace/purge/listall 分别对应 git config --global 的 set/add/unset/remove-section/get-regexp 操作)。--addworkspace 带 --from 时,脚本会用正则 http(s)?://|ssh://|(git@)?.*:.*/.* 判断来源是 URL 还是本地文件,前者直接 git clone,后者逐行读取并 git clone 每一行(每行整体作为一个参数,因此可以携带自定义目录名)。
  • 环境变量解引用:parseWsName 检测到工作区路径以 $ 开头时,用间接展开 ${!varname} 在运行时解析环境变量,并校验变量非空。
  • 仓库发现:executBulkOp 在遍历每个工作区后,用 find -L/-P . -name .git 递归查找所有 git 仓库,并支持 --no-follow-symlinks(-P)与 --no-follow-hidden(跳过隐藏目录下的 .git)两个开关;找到的仓库目录通过截掉结果尾部 .git 得到。
  • 命令合法性校验:checkGitCommand 先查 git help -a 是否为 git 核心命令,再查 git config --get-regexp alias 是否为已定义别名,否则报 unknown GIT command 并退出。
  • 守卫模式:guardedExecution 中若启用了 -g,从 /dev/tty 读取一个 y/n 决定是否执行。-w 与 -a 互斥,同时给出会直接报错退出。

交互式 REPL:git repl

git repl 是一个 git 读取-求值-打印循环(REPL),让你不用敲 git 前缀就能连续执行 git 命令:

  • 命令以 ! 开头时作为普通 shell 命令解释执行
  • 输入 exit、quit 或 q 结束会话(^D、^C 亦可)
  • 传给 git repl 的任何参数会作为进入会话后的第一条命令执行
$ git repl
git version 2.34.1
git-extras version 7.3.0
Type 'ls' to ls files below current directory; '!command' to execute any command or just 'subcommand' to execute any git subcommand; 'quit', 'exit', 'q', ^D, or ^C to exit the git repl.

git (master)> ls-files
History.md
Makefile
Readme.md
bin/git-changelog
bin/git-count
bin/git-delete-branch
bin/git-delete-tag
bin/git-ignore
bin/git-release

git (master)> !echo Straight from the shell!
Straight from the shell!

git (master)> quit

注意提示符 git (master)> 中的 (master) 是当前分支名;若命令以非零状态退出,提示符中还会以红色显示退出码(如 [1])。

REPL 配置项

会话命令会写入历史文件,并在后续会话中可用,类似 shell/编程语言 REPL。默认使用全局历史文件;可以让每个项目拥有独立的历史文件(保存在仓库根目录的 .git_extras_repl_history,需要加入 .gitignore):

# 去掉 --global 可仅对单个项目生效
git config --global git-extras.repl.use-local-history "true"

设置回车时的默认命令:

git config --global git-extras.repl.on-enter-command "git status -sb"

设置提示符末尾字符(默认 >):

git config --global git-extras.repl.prompt-character "±"

设置提示符前缀或移除它(默认 git):

git config --global git-extras.repl.prefix ""

让当前仓库名出现在提示符中(默认 false):

git config --global git-extras.repl.show-project-name "true"

源码级补充:实现见 bin/git-repl。各配置项均通过 git config --get --default '...' git-extras.repl.<key> 读取并带默认值(use-local-history 默认 false,prompt-character 默认 >,prefix 默认 git,show-project-name 默认 false,见 bin/git-repl)。历史文件路径:局部历史为仓库根的 .git_extras_repl_history,全局历史遵循 XDG 规范(${XDG_STATE_HOME:-$HOME/.local/state}/git_extras_repl_history)。ls 是 ls-files 的内置别名,history -a 保证命令实时落盘;! 开头命令经 eval ${cmd:1} 执行,git* 开头命令直接 eval,其余命令自动补 git 前缀。历史会忽略重复条目(HISTCONTROL=ignoredups)。

发布与变更日志类命令

git release:一键发布提交

git release <tag> 以给定标签发布:

$ git release 0.1.0

如果项目遵循语义化版本,也可用 --semver major|minor|patch(运行 git help release 可查看详细说明):

$ git release --semver major/minor/patch

git release 依次完成:

  1. 若存在 .git/hooks/pre-release.sh,执行它并传入给定标签及剩余参数
  2. 以消息 Release <tag> 提交变更(如 changelog 等)
  3. 打上给定 <tag> 标签
  4. 推送分支与标签
  5. 若存在 .git/hooks/post-release.sh,执行它并传入给定标签及剩余参数

git changelog:从标签与提交生成变更日志

git changelog 从 git 标签(annotated 或 lightweight)和提交消息生成变更日志。文件名以 Change 或 History 开头(大小写不敏感匹配)的既有变更日志文件会被自动识别,其内容会追加到新输出之后——可用 -p|--prune-old 禁用此行为。生成的日志文件会在设置了 $EDITOR 时自动用编辑器打开。

如果没有标签存在,则输出全部提交;有标签时只输出到最近一个标签为止的最新提交。可通过 -f|--final-tag 与 -s|--start-tag 改变这一范围行为。

可用选项:

  -a, --all                 Retrieve all commits (ignores --start-tag, --final-tag)
  -l, --list                Display commits as a list, with no titles
  -t, --tag                 Tag label to use for most-recent (untagged) commits
  -f, --final-tag           Newest tag to retrieve commits from in a range
  -s, --start-tag           Oldest tag to retrieve commits from in a range
  -n, --no-merges           Suppress commits from merged branches
  -p, --prune-old           Replace existing Changelog entirely with new content
  -x, --stdout              Write output to stdout instead of to a Changelog file
  -h, --help, ?             Usage help

输入 git changelog --help 查看基本用法,或 man git-changelog 获取完整信息。

注意:默认情况下 git changelog 会把检测到的既有 changelog 内容拼接到输出尾部;用 -p 可阻止该行为。

示例

用标签名 1.5.2 作为最近提交区块的标题(日期自动取当天),生成自上个标签以来的全部提交:

$ git changelog --tag 1.5.2 && cat History.md

1.5.2 / 2015-03-15
==================

* Docs for git-ignore. Closes #3
* Merge branch 'ignore'
* Added git-ignore
* Fixed <tag> in docs
* Install docs
* Merge branch 'release'
* Added git-release
* Passing args to git shortlog
* Added --all support to git-count

以列表形式列出上个标签以来的全部提交:

$ git changelog --list

列出自仓库初始提交以来的全部提交:

$ git changelog --list --all

源码级补充:实现位于 bin/git-changelog(609 行 Bash),其 _usage() 还额外支持 --start-commit(用提交代替 tag 作为区间起点)、-m|--merges-only(只使用 merge 提交,且同时取 subject 与 body)、-e|--exclude(按 pathspec 排除文件/目录)。脚本还读取 changelog.opts、changelog.format、changelog.mergeformat 三个 git 配置来自定义日志选项与输出格式,其中默认提交格式为 * %s、默认合并格式为 * %s%n%w(64,4,4)%b(见 bin/git-changelog)。该命令的标签范围与 prune 逻辑有测试覆盖,见 git-changelog.bats。

流程控制与恢复类命令

git abort

中止当前的 revert、rebase、merge 或 cherry-pick,无需从历史中翻找具体命令:

$ git abort

git continue

继续当前被中断的 revert、rebase、merge 或 cherry-pick,同样无需记忆具体命令:

$ git continue

两者均有测试覆盖:见 git-abort.bats 与 git-continue.bats。

别名与其余实用命令

git alias

定义、搜索和展示别名。定义新别名:

$ git alias last "cat-file commit HEAD"

用单个参数做正则搜索:

$ git alias ^la
last = cat-file commit HEAD

无参数展示全部别名:

$ git alias
s = status
amend = commit --amend
rank = shortlog -sn --no-merges
whatis = show -s --pretty='tformat:%h (%s, %ad)' --date=short
whois = !sh -c 'git log -i -1 --pretty="format:%an <%ae>

git cp

复制文件并保留历史、支持合并冲突处理(见前文"提交历史与重写类命令"):

$ git cp README.md README.rst

git rename-file

重命名文件或目录并确保 Git 识别该变更,不受文件系统大小写敏感度影响。它组合了 mv 与 git mv 的功能,尤其适合在大小写不敏感文件系统上仅改变文件/目录大小写的重命名(Git 可能检测不到):

# Rename a file
git rename-file old_filename new_filename

# Rename a directory
git rename-file old_directory new_directory

git delete-submodule

删除子模块 name:

$ git delete-submodule lib/foo

结语与进一步阅读

git-extras 的 80+ 条命令覆盖了从日常提交、分支整理,到仓库统计、历史重写、多仓批量运维的完整链路。每个命令的实现都是可读的 Bash 脚本,位于 bin/ 目录;对应的完整 man 手册位于 man/ 目录(如 git-archive-file.md、git-changelog.md);etc/ 目录还提供 bash/zsh/fish 的补全脚本(bash_completion.sh、git-extras-completion.zsh、git-extras.fish),可配合日常使用。若想贡献新命令,可参考 CONTRIBUTING.md 并对照 tests/ 下的 bats 测试样例编写用例。

登录后查看全文
git-extras