git-extras 命令手册:从仓库统计到多仓批量操作的 80+ 个 Git 增强命令实战指南
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 依次完成:
- 若存在
.git/hooks/pre-release.sh,执行它并传入给定标签及剩余参数 - 以消息
Release <tag>提交变更(如 changelog 等) - 打上给定
<tag>标签 - 推送分支与标签
- 若存在
.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 测试样例编写用例。