Git 操作备忘录

git merge feature-a feature-b

git cat-file -p HEAD

# 用途：取消指定路径的暂存状态
# 结果：将暂存区中的对应内容恢复为 HEAD 的版本，工作目录文件保持不变
git restore --staged <pathspec>...
# 示例 1：取消暂存 README.md，但保留文件修改
git restore --staged README.md

# 用途：将当前分支独有的提交重新应用到新的基线
# 条件：当前分支是需要改写的分支；暂存区和已跟踪文件没有未提交修改；相关提交尚未共享或已协调改写
# 结果：在 <upstream> 之后重建当前分支的提交，并让当前分支指向新的提交序列；<upstream> 不变
git rebase <upstream>
# 示例 1：当前分支为 feature/example，将其独有提交重新应用到 main 之后
git rebase main

# 用途：分别指定新基线、提交选择边界和待改写分支
# 条件：暂存区和已跟踪文件没有未提交修改；<branch> 未被其他 worktree 使用；相关提交尚未共享或已协调改写
# 结果：选择 <branch> 相对于 <upstream> 独有的提交，将其重新应用到 <new-base>，再让 <branch> 指向新序列
git rebase --onto <new-base> <upstream> <branch>
# 示例 1：将 topic/example 相对于 integration 独有的提交重新应用到 main
git rebase --onto main integration topic/example

# 用途：调整提交顺序、修改提交信息、合并或删除提交
# 条件：暂存区和已跟踪文件没有未提交修改；待处理提交尚未共享或已协调改写
# 结果：打开按提交历史从旧到新排列的待办列表，并按照保存后的内容重新创建 <upstream> 之后的提交
git rebase -i <upstream>
# 示例 1：交互式整理当前分支最近五个提交
git rebase -i HEAD~5

# 用途：在存在本地修改时执行变基
# 条件：不存在尚未解决的合并冲突；普通未跟踪文件不得阻碍 Git 写入；相关提交尚未共享或已协调改写
# 结果：变基前创建临时 stash，变基结束后重新应用；重新应用时仍可能产生冲突
git rebase --autostash <upstream>
# 示例 1：临时保存本地修改，将当前分支变基到 main，再重新应用这些修改
git rebase --autostash main

# 用途：变基时重新创建原有合并结构
# 条件：暂存区和已跟踪文件没有未提交修改；相关提交尚未共享或已协调改写
# 结果：在新基线上重新应用普通提交并尝试重新创建合并提交；原有人工冲突解决可能需要再次处理
git rebase --rebase-merges <upstream>
# 示例 1：将当前分支变基到 main，并重新创建其合并结构
git rebase --rebase-merges main

# 用途：解决冲突或完成交互式编辑后继续变基
# 条件：rebase 已暂停；冲突已经解决并用 git add 写入暂存区，或当前编辑已经完成
# 结果：完成当前提交的重建并继续处理剩余提交
git rebase --continue

# 用途：跳过当前无法应用的提交并继续变基
# 条件：rebase 已暂停，并已确认新历史不需要当前提交的修改
# 结果：当前提交不会进入重建后的历史，rebase 继续处理后续提交
git rebase --skip

# 用途：取消处于暂停状态的 rebase
# 条件：rebase 已开始但尚未完成
# 结果：放弃尚未完成的变基，并恢复到变基开始前的状态
git rebase --abort

# 用途：查看当前仓库中的 stash 列表
git stash list

# 用途：临时保存已跟踪文件的修改
# 条件：暂存区中不能存在尚未解决的合并冲突
# 结果：创建 stash，保存已暂存和未暂存修改，并使相应文件恢复到 HEAD 的状态
git stash push -m <message>
# 示例 1：保存当前已跟踪文件的修改，并将该记录标记为 wip: example
git stash push -m "wip: example"

# 用途：同时保存已跟踪文件的修改和未跟踪文件
# 条件：暂存区中不能存在尚未解决的合并冲突
# 结果：创建 stash，保存已暂存修改、未暂存修改和未跟踪文件；随后使相应已跟踪文件恢复到 HEAD，并从工作目录移除已保存的未跟踪文件；被忽略文件保持不变
git stash push -u -m <message>
# 示例 1：保存当前修改和未跟踪文件，但不保存被忽略文件
git stash push -u -m "wip: example"

# 用途：只保存指定路径中的修改
# 条件：暂存区中不能存在尚未解决的合并冲突
# 结果：只将匹配路径的修改写入 stash 并撤回，其他路径保持不变
git stash push -m <message> -- <pathspec>...
# 示例 1：只保存 docs/ 和 README.md 中的修改
git stash push -m "wip: docs" -- docs/ README.md

# 用途：查看指定 stash 的差异统计
# 结果：显示该 stash 相对于创建时基线的差异统计，不改变任何状态
git stash show --stat <stash>
# 示例 1：查看最新 stash 的差异统计
git stash show --stat stash@{0}

# 用途：查看指定 stash 的完整补丁
# 结果：显示该 stash 相对于创建时基线的完整差异，不改变任何状态
git stash show -p <stash>
# 示例 1：查看最新 stash 的完整补丁
git stash show -p stash@{0}

# 用途：恢复指定 stash，同时保留该记录
# 条件：工作目录必须与暂存区一致
# 结果：将记录的修改应用到当前状态；可能产生冲突，但不会删除 stash
git stash apply <stash>
# 示例 1：恢复最新 stash，同时保留该记录
git stash apply stash@{0}

# 用途：恢复指定 stash，并在成功后删除该记录
# 条件：工作目录必须与暂存区一致
# 结果：将记录的修改应用到当前状态；成功时删除 stash，发生冲突时保留
git stash pop <stash>
# 示例 1：恢复最新 stash，并在成功后删除该记录
git stash pop stash@{0}

# 用途：从创建 stash 时的基线建立分支并恢复修改
# 条件：<new-branch> 尚不存在，当前本地修改不得妨碍切换到 stash 的基线提交
# 结果：创建并切换到新分支，应用 stash；应用成功时删除该 stash 记录
git stash branch <new-branch> <stash>
# 示例 1：建立 recovery/example 分支并恢复最新 stash
git stash branch recovery/example stash@{0}

# 用途：查看仓库关联的所有 worktree
git worktree list

# 用途：从指定起点新建分支，并为该分支创建 worktree
# 条件：执行命令所在的工作区可以是 clean 或 unclean
# 结果：以 <commit-ish> 为起点创建新分支，并在 <path> 中建立该分支的 worktree
git worktree add -b <new-branch> <path> [<commit-ish>]
# 示例 1：以 origin/main 为起点创建 hotfix/example 分支，并在相邻的 project-hotfix/ 目录中建立该分支的 worktree
git worktree add -b hotfix/example ../project-hotfix origin/main
# 示例 2：以当前 HEAD 为起点创建 feature/example 分支，并在相邻的 project-feature/ 目录中建立该分支的 worktree
git worktree add -b feature/example ../project-feature
# 示例 3：以 v1.2.0 为起点创建 hotfix/v1.2.1 分支，并在相邻的 project-hotfix-v1.2.1/ 目录中建立该分支的 worktree
git worktree add -b hotfix/v1.2.1 ../project-hotfix-v1.2.1 v1.2.0

# 用途：为已有的本地分支创建 worktree
# 条件：执行命令所在的工作区可以是 clean 或 unclean；<branch> 未被其他 worktree 使用
# 结果：在 <path> 中建立使用 <branch> 的 worktree；原工作区中的未提交修改和暂存内容不会复制过去
git worktree add <path> <branch>
# 示例 1：在相邻的 project-release/ 目录中建立使用 release/1.x 分支的 worktree
git worktree add ../project-release release/1.x

# 用途：为指定版本创建不绑定分支的临时 worktree，用于检查旧版本、测试或执行 bisect
# 条件：执行命令所在的工作区可以是 clean 或 unclean
# 结果：在 <path> 中建立 worktree，其 HEAD 直接指向指定提交并处于 detached HEAD 状态；原工作区状态不变
git worktree add --detach <path> <commit-ish>
# 示例 1：直接使用缩写提交 ID，在相邻的 project-inspect-commit/ 目录中建立指向提交 9f3a2c1 的临时 worktree
git worktree add --detach ../project-inspect-commit 9f3a2c1
# 示例 2：在相邻的 project-inspect-tag/ 目录中建立指向 v1.2.0 标签所指提交的临时 worktree
git worktree add --detach ../project-inspect-tag v1.2.0

# 用途：删除不再需要的 linked worktree，但保留其分支和提交
# 条件：执行命令所在的工作区可以是 clean 或 unclean；目标必须是 clean、未锁定且不含子模块的 linked worktree
# 结果：删除 <worktree> 工作目录及其管理记录，不删除对应分支和提交
git worktree remove <worktree>
# 示例 1：删除相邻的 project-hotfix/ worktree
git worktree remove ../project-hotfix

# 用途：预览可以清理的失效 worktree 管理记录
# 条件：执行命令所在的工作区可以是 clean 或 unclean；需在该仓库的任一 worktree 中执行
# 结果：列出工作目录已经不存在且符合清理条件的管理记录，不实际删除
git worktree prune --dry-run

# 用途：清理失效的 worktree 管理记录
# 条件：执行命令所在的工作区可以是 clean 或 unclean；需在该仓库的任一 worktree 中执行
# 结果：删除工作目录已经不存在且符合清理条件的管理记录，不删除现存 worktree、分支或提交
git worktree prune

# 用途：修复手动移动主 worktree 或 linked worktree 后失效的关联
# 条件：执行命令所在的工作区和待修复的工作区都可以是 clean 或 unclean；移动 linked worktree 后需提供其新路径
# 结果：重新建立仓库管理目录与相应 worktree 的双向关联，不改变工作目录文件、分支或提交
git worktree repair [<path>...]
# 示例 1：修复已经手动移动到 ../project-hotfix/ 的 linked worktree
git worktree repair ../project-hotfix

# 用途：将一个已有提交引入当前分支
# 条件：当前工作区必须是 clean
# 结果：应用目标提交引入的修改，并在当前分支创建新提交
git cherry-pick <commit-ish>
# 示例 1：将提交 9f3a2c1 引入当前分支
git cherry-pick 9f3a2c1

# 用途：应用已有提交的修改，但不立即创建提交
# 条件：暂存区中不能存在尚未解决的合并冲突；现有本地修改不得被目标修改覆盖
# 结果：将目标修改写入工作目录和暂存区，HEAD 与当前分支保持不变
git cherry-pick --no-commit <commit-ish>
# 示例 1：应用提交 9f3a2c1 的修改，检查或调整后再自行提交
git cherry-pick --no-commit 9f3a2c1

# 用途：撤销普通提交引入的修改
# 条件：当前工作区必须是 clean
# 结果：创建一个抵消目标提交的新提交，原提交和既有历史保持不变
git revert <commit-ish>
# 示例 1：以新提交撤销提交 9f3a2c1
git revert 9f3a2c1

# 用途：撤销合并提交；因其有多个父提交，必须用 -m 指定保留哪条主线
# 条件：当前工作区必须是 clean；目标是合并提交；<parent-number> 对应其一个父提交
# 结果：反向应用合并相对于该父提交的变化；不是撤销该父提交，也不删除原合并提交
git revert -m <parent-number> <merge-commit>
# 示例 1：先核对 parent 顺序，再保留第一父提交所代表的主线并撤销该次合并
git show --no-patch --pretty=raw 6d8f2a1
git revert -m 1 6d8f2a1
# 注意：撤销只反转内容，原合并关系仍存在；再次合并不会自动恢复被撤销的内容

# 用途：移动当前分支，同时保留暂存区和工作目录中的内容
# 条件：暂存区中不能存在尚未解决的合并冲突
# 结果：当前分支或 detached HEAD 移到目标提交；暂存区和工作目录保持不变
git reset --soft <commit-ish>
# 示例 1：撤回当前提交，同时让其中的修改继续保持已暂存状态
git reset --soft HEAD^

# 用途：移动当前分支并取消目标提交之后的暂存状态
# 条件：当前工作区可以是 clean 或 unclean
# 结果：当前分支或 detached HEAD 移到目标提交，暂存区重置为目标内容，工作目录保持不变
git reset --mixed <commit-ish>
# 示例 1：撤回当前提交并取消其修改的暂存状态，但保留文件修改
git reset --mixed HEAD^

# 用途：使当前分支、暂存区和已跟踪文件全部回到指定提交
# 条件：当前工作区可以是 clean 或 unclean
# 结果：当前分支或 detached HEAD 移到目标提交；暂存区和已跟踪文件被目标内容覆盖，阻碍写入的未跟踪路径也可能被删除
git reset --hard <commit-ish>
# 示例 1：将当前分支退回前一个提交，并丢弃暂存区和工作目录中的未提交修改
git reset --hard HEAD^

# 用途：查看 HEAD 或指定引用的更新记录
# 结果：按时间倒序显示 reflog 位置、commit ID 和操作说明，不改变任何引用
git reflog show [-n <count>] [--date=<format>] [<ref>]
# 示例 1：以本地时间显示 HEAD 最近 10 条更新记录
git reflog show -n 10 --date=local HEAD
# 示例 2：显示 main 最近 5 条更新记录
git reflog show -n 5 main

# 用途：列出当前仓库中拥有 reflog 的引用
# 结果：输出引用名称，不改变 reflog 或引用
git reflog list

# 用途：检查指定引用是否拥有 reflog
# 结果：存在时返回退出状态 0，否则返回非零状态；不输出 reflog 内容
git reflog exists <ref>
# 示例 1：检查本地 main 分支是否拥有 reflog
git reflog exists refs/heads/main

# 用途：检查 reflog 中记录的旧位置
# 条件：指定记录尚未过期，且其指向的 Git 对象仍然存在
# 结果：显示该位置对应的提交及其补丁，不移动任何引用
git show <ref>@{<specifier>}
# 示例 1：检查 HEAD 在两次移动之前所指向的提交
git show HEAD@{2}

# 用途：将 reflog 中找到的提交保留为新分支
# 条件：指定记录及其提交仍然存在；<new-branch> 尚不存在
# 结果：创建指向该提交的新分支，不切换分支，也不移动现有引用
git branch <new-branch> <ref>@{<specifier>}
# 示例 1：将 HEAD 在两次移动之前所指向的提交保留为 rescue/example
git branch rescue/example HEAD@{2}

# 用途：创建包含所有引用及其可达对象的自包含 bundle
# 条件：执行命令所在的工作区可以是 clean 或 unclean
# 结果：将当前仓库可由所有引用到达的历史写入 <file>，不包含未提交状态和仓库配置
git bundle create <file> --all
# 示例 1：将当前仓库历史写入 project.bundle
git bundle create project.bundle --all

# 用途：验证 bundle 格式及其前置提交
# 条件：在一个 Git 仓库中执行；验证增量 bundle 时，应在接收方仓库中执行
# 结果：检查文件完整性，并列出当前仓库缺少的前置提交；不导入任何对象
git bundle verify <file>
# 示例 1：验证 project.bundle
git bundle verify project.bundle

# 用途：从自包含 bundle 创建新仓库
# 条件：<file> 必须是没有缺失前置提交的 bundle，<directory> 不能是已有的非空目录
# 结果：在 <directory> 中创建包含 bundle 历史的新仓库
git clone <file> <directory>
# 示例 1：从 project.bundle 创建 project/ 仓库
git clone project.bundle project

# 用途：查看 bundle 提供的引用
# 结果：显示其中可供读取的引用及其 commit ID，不导入任何对象
git ls-remote <file>
# 示例 1：查看 project.bundle 提供的引用
git ls-remote project.bundle

# 用途：从 bundle 获取指定引用
# 条件：在接收方仓库中执行；该仓库必须具备 bundle 要求的前置提交
# 结果：导入所需对象，并按引用规范更新本地引用
git fetch <file> <source-ref>:<destination-ref>
# 示例 1：将 project.bundle 的 main 分支获取为 bundle/main 远程跟踪引用
git fetch project.bundle refs/heads/main:refs/remotes/bundle/main

# 用途：将指定版本导出为源码包
# 条件：执行命令所在的工作区可以是 clean 或 unclean
# 结果：把指定版本中的文件写入 <output>，并为包内路径添加 <prefix>/ 前缀
git archive --format=<format> --prefix=<prefix>/ -o <output> <tree-ish>
# 示例 1：将 v1.2.0 标签导出为 project-1.2.0.tar.gz
git archive --format=tar.gz --prefix=project-1.2.0/ -o project-1.2.0.tar.gz v1.2.0

# 用途：指定 bad 与 good 边界并开始二分
# 条件：两个边界已经过验证；工作区能够安全切换提交
# 结果：记录开始前的 HEAD，并切换到第一个候选提交
git bisect start <bad> <good>
# 示例 1：在当前提交与 v1.0.0 之间开始二分
git bisect start HEAD v1.0.0

# 用途：将当前候选提交标记为正常
# 条件：bisect 正在进行，且当前提交已确认为 good
# 结果：更新 good 边界，并切换到下一个候选提交或报告结果
git bisect good

# 用途：将当前候选提交标记为异常
# 条件：bisect 正在进行，且当前提交已确认为 bad
# 结果：更新 bad 边界，并切换到下一个候选提交或报告结果
git bisect bad

# 用途：跳过当前无法可靠判断的候选提交
# 条件：bisect 正在进行，且当前提交不能归类为 good 或 bad
# 结果：选择其他候选提交；边界附近存在 skip 时可能无法确定唯一结果
git bisect skip

# 用途：结束二分
# 条件：bisect 正在进行
# 结果：清除二分状态，并恢复开始二分前所在的分支或提交位置
git bisect reset

# 用途：用指定命令自动测试候选提交
# 条件：bisect 正在进行；命令能够按约定返回稳定的退出状态
# 结果：反复测试并标记候选提交，直至定位边界或中止二分
git bisect run <command> [<argument>...]
# 示例 1：用仓库外的脚本自动测试候选提交
git bisect start HEAD v1.0.0
git bisect run ../test-regression.sh
git bisect reset

# 用途：输出当前二分过程的操作记录
# 条件：bisect 正在进行
# 结果：输出可供检查、保存或 replay 使用的记录，不改变二分状态
git bisect log
# 示例 1：将记录保存到仓库外的文件
git bisect log > ../bisect.log

# 用途：从已有记录恢复二分进度
# 条件：<log-file> 是 git bisect log 生成的有效记录；工作区能够安全切换提交
# 结果：重放记录中的 start、good、bad 和 skip 操作
git bisect replay <log-file>
# 示例 1：从保存的记录恢复二分进度
git bisect reset
git bisect replay ../bisect.log

# 用途：让当前仓库开始接受定时维护
# 条件：执行命令所在的工作区可以是 clean 或 unclean；操作系统中存在可用调度器
# 结果：登记当前仓库，未配置策略时设为 incremental，关闭普通 Git 命令触发的自动维护，并创建或更新用户级后台调度
git maintenance start [--scheduler=<scheduler>]
# 示例 1：让 Git 根据操作系统自动选择调度器
git maintenance start --scheduler=auto

# 用途：在不改动现有调度器的情况下，将另一个仓库加入维护名单
# 条件：在需要加入的仓库中执行；工作区可以是 clean 或 unclean
# 结果：登记当前仓库并完成与 start 相同的仓库配置，但不创建或启动调度器
git maintenance register
# 示例 1：调度器已经由其他仓库启动，将相邻的 project-b 加入同一维护名单
cd ../project-b
git maintenance register

# 用途：查看已登记的仓库
# 结果：输出当前用户全局配置中的所有 maintenance.repo 值
git config --global --get-all maintenance.repo

# 用途：只停止当前仓库的定时维护
# 条件：当前仓库已经登记；工作区可以是 clean 或 unclean
# 结果：从维护名单中移除当前仓库，其他仓库和调度器保持不变；maintenance.auto=false 仍然保留
git maintenance unregister
# 可选：恢复普通 Git 命令按需触发自动维护的默认行为
git config --unset maintenance.auto

# 用途：暂停所有已登记仓库的定时维护
# 条件：工作区可以是 clean 或 unclean
# 结果：停止并移除共用的用户级调度器，但保留维护名单；以后执行 start 可以继续处理这些仓库
git maintenance stop

# 用途：针对明确问题手动运行指定任务
# 条件：执行命令所在的工作区可以是 clean 或 unclean；每个 <task> 都必须是受支持的任务名称
# 结果：仅按参数出现顺序执行指定任务，不运行其他任务
git maintenance run --task=<task> [--task=<task>...]
# 示例 1：导入大量提交后，立即更新 commit-graph
git maintenance run --task=commit-graph
# 示例 2：仓库积累了大量松散对象和较小 pack 文件，执行增量整理
git maintenance run --task=loose-objects --task=incremental-repack
# 示例 3：需要一次全面整理时单独运行 gc；不要与 loose-objects 放在同一次维护中
git maintenance run --task=gc

# 用途：仅在仓库达到相应维护阈值时运行任务
# 条件：执行命令所在的工作区可以是 clean 或 unclean
# 结果：达到阈值时执行维护，否则不改变仓库数据
git maintenance run --auto

git status --short --branch

git push origin feature/example

git pull

# pull 使用 rebase 时
git rebase --abort

# pull 使用 merge 时
git merge --abort

git fetch origin

# 查看分叉后的完整提交图
git log --graph --oneline --decorate --boundary \
  feature/example...origin/feature/example

# 只查看远端有、本地没有的提交
git log --oneline \
  feature/example..origin/feature/example

# 检查这些远端提交是否存在补丁等价的本地版本
git cherry -v \
  feature/example origin/feature/example

# 用途：以变基后的本地历史替换远端旧历史
# 条件：已经 fetch 并确认远端只有变基前的旧提交；该分支允许改写
# 结果：保护检查通过时，将 origin/feature/example 更新到本地 feature/example
git push \
  --force-with-lease \
  --force-if-includes \
  origin feature/example

git fetch origin
git status --short --branch

# 输出并人工核对远端尖端；本例应当是变基前的旧提交 D
git rev-parse origin/feature/example

# 将上一步输出的完整 commit ID 填入 <expected-remote-tip>
git push \
  --force-with-lease=refs/heads/feature/example:<expected-remote-tip> \
  origin feature/example:feature/example

# 条件：工作区没有会妨碍合并的未提交修改
git merge origin/feature/example
git push origin feature/example

git cherry-pick <remote-new-commit>...

git switch -c feature/example-rebased
git push --set-upstream origin feature/example-rebased