版本控制与协作 / 知识点
Git 命令速查手册
手册条目
git commit -m "<提交说明>"将暂存区中的修改保存为新的本地提交。
提交暂存内容
使用 git commit 将暂存区当前保存的修改生成一个新的本地提交。它只提交已经通过 git add 暂存的内容,不会自动包含工作区中的未暂存修改。
基本语法
常用写法是 git commit -m "<提交说明>"。执行前先检查暂存区,避免漏提交文件或混入无关修改。
git status --short
git diff --cached --stat
git commit -m "fix: handle empty username"
git log -1 --oneline预期输出如下,分支名、提交 ID 和文件统计会随仓库实际情况变化。
M src/user.js
src/user.js | 3 ++-
1 file changed, 2 insertions(+), 1 deletion(-)
[<BRANCH> <ID>] fix: handle empty username
1 file changed, 2 insertions(+), 1 deletion(-)
<ID> fix: handle empty usernameM src/user.js 中的 M 位于第一列,表示该文件的修改已经暂存。最后一行说明当前分支最新提交已更新为 <ID>。
常用参数
-m "说明":直接在命令行填写提交说明,适合单行信息。--dry-run:预览哪些内容会被提交,不创建提交。--amend:用当前暂存内容替换最近一次提交,并生成新的提交 ID。-v:打开编辑器编写说明时,同时显示待提交差异,便于复核。
高频用法
提交前使用 git diff --cached 查看完整差异;只看文件和行数统计时使用 git diff --cached --stat。提交完成后,可用 git show --stat --oneline -1 检查最新提交包含的文件。
需要分批提交时,先用 git add <PATH> 精确暂存本次相关文件,再执行 git commit。不要为了省事把所有修改一次性加入暂存区。
风险与边界
git commit 只创建本地提交,不会自动上传远程仓库;需要共享时还要执行 git push。
当暂存区为空时,命令会提示 nothing to commit,不会创建空提交。若确实需要空提交,应明确使用 --allow-empty,不要把它用于普通业务修改。
对已经推送并被他人使用的提交执行 --amend 会改变提交 ID,后续通常需要强制推送,并可能导致他人的分支出现冲突。安全做法是创建一个新的修正提交;只有确认提交尚未共享时才修改历史。
排障清单
- 出现
Author identity unknown:配置 Git 的user.name和user.email后重试。 - 提交内容少了文件:用
git status --short检查该文件是否仍显示为第二列修改或??。 - 提交混入无关内容:尚未推送时可撤销最近提交并重新暂存;已经推送时优先用新的反向提交修正。
- 提交被钩子拒绝:阅读钩子输出并修复检查失败项,不要默认使用
--no-verify绕过质量检查。
速查:先看 git diff --cached,确认无误后再执行 git commit -m "说明"。
git commit -am "<提交说明>"跳过手动暂存步骤并提交已跟踪文件的修改。
快速提交已跟踪文件
使用 git commit -am 自动暂存并提交所有已跟踪文件的修改和删除,适合改动范围明确的小型修复。它不会提交新建但尚未跟踪的文件。
基本语法
命令格式为 git commit -am "<提交说明>",其中 -a 负责暂存已跟踪文件的变化,-m 负责提供提交说明。
下面假设 README.md 已经被 Git 跟踪,而 debug.log 是新建文件。
echo "release note" >> README.md
echo "temporary data" > debug.log
git status --short
git commit -am "docs: update README"
git status --short预期输出如下,提交 ID、分支名和行数可能不同。
M README.md
?? debug.log
[<BRANCH> <ID>] docs: update README
1 file changed, 1 insertion(+)
?? debug.log提交前的 M README.md 表示已跟踪文件存在未暂存修改;?? debug.log 表示新文件尚未跟踪。提交后只剩 debug.log,说明 -a 没有把新文件加入提交。
适用场景
适合只修改了几个已跟踪文件,并且希望把这些修改全部放进同一个提交的情况,例如修正文档、调整已有配置或修复单一缺陷。
不适合需要选择部分文件、部分代码块或需要同时提交新文件的情况。此时应显式执行 git add <PATH>,复核暂存区后再提交。
参数边界
-a 会处理仓库中已跟踪文件的修改和删除,但不会包含:
- 状态为
??的未跟踪文件。 - 被
.gitignore忽略且从未跟踪的文件。 - 子模块工作目录内部尚未提交的具体文件内容。
- 只希望留到下一次提交的其他已跟踪文件修改。
风险与安全替代
当工作区同时存在多个任务的修改时,git commit -am 会把所有已跟踪文件的变化一起暂存,可能把调试代码、临时配置或无关删除带入提交。
安全替代方案是先运行 git diff 查看全部未暂存修改,再使用 git add <PATH> 精确选择文件。需要按代码块选择时使用 git add -p,确认后执行普通的 git commit -m "说明"。
不要使用 git commit -am 代替提交前检查。即使命令执行成功,也应通过 git show --stat --oneline -1 验证最新提交涉及的文件范围。
排障清单
- 新文件没有进入提交:先用
git add <PATH>将其纳入跟踪,再提交。 - 意外提交了其他已跟踪文件:未推送时重做最近提交;已推送时优先创建修正提交。
- 文件修改仍留在工作区:检查它是否位于子模块、是否为未跟踪文件,或是否在提交过程中再次被程序修改。
- 输出
nothing to commit:确认文件确实发生变化,并检查当前目录是否属于预期仓库和分支。
速查:git commit -am 只适合“一次提交所有已跟踪文件变化”,涉及新文件或选择性提交时改用 git add 加 git commit。
git commit --amend --no-edit
git commit --amend -m "<新的提交说明>"补充最近一次提交的内容或修改其提交说明。
修改最近提交
用于把漏掉的文件补进最近一次提交,或改写该提交的说明。核心命令是 git commit --amend;它会生成一个新的提交对象,因此提交哈希通常会变化。
命令定位
只处理当前分支的 HEAD 提交。工作区修改必须先暂存,未执行 git add 的内容不会被补入提交;如果只改说明,则无需改动文件。
高频用法
补交遗漏文件并保留原说明
git add src/app.conf
git commit --amend --no-edit预期输出
[main <ID>] fix: adjust payment timeout
Date: <TIME>
2 files changed, 5 insertions(+), 1 deletion(-)<ID>、<TIME> 和文件统计会随仓库变化。--no-edit 保留原提交说明,但新暂存的 src/app.conf 会进入最近提交。
只修改提交说明
git commit --amend -m "fix: correct payment timeout"预期输出
[main <ID>] fix: correct payment timeout
Date: <TIME>
1 file changed, 2 insertions(+)命令会保留原提交中的文件快照,只替换说明。执行前先确认暂存区为空,否则暂存内容也会一并写入。
常用参数
--no-edit:沿用原提交说明,适合补文件。-m "<MESSAGE>":直接指定新说明,不打开编辑器。--reset-author:把作者重置为当前 Git 身份,并刷新作者时间;仅在确实需要变更作者时使用。--no-verify:跳过提交钩子,可能绕过格式、测试或安全检查,生产仓库不建议使用。
验证结果
git show --stat --oneline HEAD预期输出
<ID> fix: correct payment timeout
src/app.conf | 4 +++-
1 file changed, 3 insertions(+), 1 deletion(-)第一行确认最新说明和新哈希,后续统计确认目标文件已经进入提交。需要核对具体差异时改用 git show HEAD。
风险与边界
--amend 会改写历史。若旧提交已经推送,其他人可能已基于旧哈希开发;此时强制推送可能覆盖远端新增提交。共享分支优先追加一个修正提交,个人分支确需改写时先执行 git fetch,再使用 git push --force-with-lease,不要使用无保护的 --force。
该命令只能直接修改最近一次提交。要修改更早的提交需使用交互式变基,并承担重写后续提交哈希的风险。
排障清单
- 漏掉的文件仍未进入提交:运行
git status --short,确认目标文件已暂存。 - 暂存了多余文件:先用
git restore --staged <PATH>撤出,再重新执行 amend。 - 推送被拒绝:说明远端已有旧提交或新增提交;先拉取远端状态,确认无他人变更后再决定追加提交或使用
--force-with-lease。 - 提交说明编辑器无法退出:改用
-m "<MESSAGE>"或--no-edit,避免依赖交互式编辑器。
echo '<忽略规则>' >> .gitignore
git check-ignore -v <路径>
git rm -r --cached -- <路径>通过忽略规则排除不应纳入版本控制的文件。
忽略指定文件
用于让 Git 不再提示本地配置、日志、构建产物等不应提交的文件。仓库共享规则写入 .gitignore;已经被 Git 追踪的文件不会因为新增规则而自动停止追踪。
基本语法
.gitignore 每行一条规则,路径分隔符统一写 /。规则按目录层级生效,后出现的匹配规则可以覆盖前面的规则。
.env
logs/
*.log
/dist/
logs/*
!logs/keep.log.env 忽略任意层级同名文件,logs/ 忽略目录,*.log 忽略扩展名,/dist/ 只匹配仓库根目录。最后两行先忽略 logs 内所有内容,再保留 keep.log。
高频用法
添加共享忽略规则
printf '%s\n' '.env' 'logs/' '*.log' '/dist/' >> .gitignore
git add .gitignore
git commit -m "chore: update gitignore"预期输出
[main <ID>] chore: update gitignore
1 file changed, 4 insertions(+)git add 通常没有输出。提交后规则会随仓库同步;追加前先检查 .gitignore,避免重复或过宽规则。
停止追踪已提交文件
git rm --cached .env
git commit -m "chore: stop tracking local env"预期输出
rm '.env'
[main <ID>] chore: stop tracking local env
1 file changed, 1 deletion(-)
delete mode 100644 .env--cached 只从 Git 索引移除文件,本地工作区文件仍保留。目录需要使用 git rm -r --cached <PATH>,并先确认忽略规则已经正确覆盖该目录。
规则速查
| 规则 | 含义 |
|---|---|
file.txt |
忽略任意层级的同名文件 |
/file.txt |
只忽略仓库根目录下的文件 |
build/ |
忽略任意层级的 build 目录 |
*.tmp |
忽略所有 .tmp 文件 |
temp?.log |
? 匹配单个字符 |
!keep.log |
取消前面规则对该文件的忽略 |
取消忽略目录内文件时,父目录不能被整体排除。应使用 logs/* 后再写 !logs/keep.log,而不是先写 logs/。
验证与排障
git check-ignore -v .env logs/app.log预期输出
.gitignore:1:.env .env
.gitignore:2:logs/ logs/app.log输出依次显示规则文件、行号、命中规则和目标路径。没有输出表示路径未被忽略;此时检查规则位置、拼写和更靠后的覆盖规则。
还可运行 git status --ignored --short 查看被忽略项。输出中的 !! 表示文件已被忽略,不会进入普通未跟踪文件列表。
风险与边界
.gitignore 不是安全措施。若密钥或密码已经提交,新增忽略规则只能阻止后续误提交,历史版本仍包含敏感内容;应立即轮换凭据,并按仓库管理要求清理历史。
过宽规则如 *、config/ 可能隐藏源码或必要配置。安全做法是限定目录或扩展名,并在提交前用 git check-ignore -v <PATH> 验证具体命中来源。
个人编辑器缓存等不应写入共享规则时,可使用 .git/info/exclude;跨仓库的个人规则可配置全局 excludes 文件。两者不会随仓库提交,适合仅本机生效的忽略项。
兼容性
.gitignore 在 Windows、macOS 和 Linux 中都使用 /。子目录中的 .gitignore 只影响该目录及其后代;全局忽略规则优先级较低,仓库内规则或命令行排除规则可能覆盖它。
git rm --cached -- <路径>
git rm -r --cached -- <目录>从版本控制中移除文件但保留本地副本。
停止跟踪文件
使用 git rm --cached 将文件从 Git 索引中移除,同时保留工作区里的本地副本。常用于停止提交环境配置、构建产物或本地密钥文件。
基本语法
处理单个文件使用 git rm --cached -- <path>;处理目录时增加 -r。其中 -- 表示后续内容均为路径,避免以短横线开头的文件名被解析成参数。
常用参数:
-r:递归处理目录。-f:文件在索引或工作区中有特殊变更时强制移除,使用前必须检查差异。--ignore-unmatch:路径不存在或未被跟踪时仍返回成功,适合自动化脚本。
高频用法
假设 config/local.env 已被 Git 跟踪,以下命令将它加入忽略规则、停止跟踪并验证暂存区中的删除记录:
printf '\nconfig/local.env\n' >> .gitignore
git rm --cached -- config/local.env
git add .gitignore
git diff --cached --name-only --diff-filter=D -- config/local.env预期输出:
rm 'config/local.env'
config/local.env第一行表示文件已从索引移除;第二行表示暂存区包含该文件的删除记录。本地文件仍然存在,可用 test -f config/local.env && echo exists 检查。
停止跟踪整个目录时使用 git rm -r --cached -- build/。修改 .gitignore 后需要让所有已跟踪文件重新匹配忽略规则时,可使用 git rm -r --cached -- . 再执行 git add .,但提交前必须完整检查暂存区。
风险与边界
不要遗漏 --cached。执行 git rm <path> 会同时删除索引记录和本地文件;安全做法是先运行 git status --short,确认路径后再执行带 --cached 的命令。
停止跟踪不会清除历史提交中的内容。若文件曾包含密码、令牌或私钥,应立即轮换凭据,并按团队流程使用历史重写工具清理仓库历史。
git rm --cached 只会生成暂存变更,其他成员要在提交并推送后才能收到删除记录。提交前使用 git diff --cached --stat 和 git diff --cached --name-status 核对范围。
排障清单
出现 pathspec did not match any files 时,先用 git ls-files -- <path> 检查文件是否已被跟踪,并核对路径大小写和当前目录。
文件随后又被加入暂存区,通常是 .gitignore 规则缺失、位置错误或被 ! 否定规则重新包含。可用 git check-ignore -v -- <path> 查看命中的具体规则。
误操作后尚未提交,可执行 git restore --staged -- <path> 恢复索引状态;如果同时误删了本地文件,再执行 git restore --worktree -- <path>。
兼容性
命令适用于常见 Git 版本。Windows、macOS 和 Linux 中建议统一使用正斜杠路径,并对包含空格或通配符的路径加引号,例如 git rm --cached -- "config/local file.env"。
git mv [-n] -- <源路径> <目标路径>在保留版本变更记录的同时移动或重命名文件。
移动或重命名文件
使用 git mv 在工作区移动或重命名已跟踪文件,并立即把旧路径删除和新路径新增记录加入暂存区,避免遗漏其中一侧的变更。
基本语法
重命名文件使用 git mv -- <source> <destination>;将多个文件移入目录时,目标目录必须已经存在。Git 保存的是文件快照,提交记录中的“重命名”通常由内容相似度检测得出,并不是独立的永久元数据。
常用参数:
-n:只显示准备执行的操作,不实际移动,适合批量操作前预检。-v:显示已执行的移动过程。-f:目标已存在时强制处理,可能覆盖目标文件,应谨慎使用。-k:批量移动时跳过发生错误的文件,继续处理其他路径。
高频用法
重命名单个已跟踪文件:
git mv -- docs/old-name.md docs/new-name.md
git status --short -- docs/old-name.md docs/new-name.md预期输出:
R docs/old-name.md -> docs/new-name.mdgit mv 成功时通常没有输出;状态行开头的 R 表示暂存区已识别为重命名。相似度较低时也可能显示为一条删除记录和一条新增记录,但提交后的文件内容仍然正确。
在大小写不敏感的文件系统上,仅修改文件名大小写时使用临时名称中转:
git mv -- README.md README.tmp
git mv -- README.tmp Readme.md
git status --short -- README.md Readme.md预期输出:
R README.md -> Readme.md移动到其他目录前先创建目标目录,例如先执行 mkdir -p docs/archive,再执行 git mv -- guide.md docs/archive/guide.md。批量移动前可运行 git mv -n -- src/*.txt archive/ 查看计划操作。
风险与边界
使用 -f 且目标路径已存在时,可能覆盖目标文件并造成未提交内容丢失。安全替代方案是先执行 test -e <destination> 或使用不带 -f 的默认命令,让 Git 在冲突时停止。
git mv 不能把文件直接移出当前工作树或移动到另一个仓库。跨仓库迁移应先复制文件,再分别在源仓库和目标仓库检查、暂存和提交。
移动文件后继续大量改写内容,会降低 Git 的重命名相似度,历史视图可能显示为删除加新增。需要保留清晰审查记录时,先单独提交纯移动操作,再提交内容修改。
排障清单
出现 bad source 或 not under version control 时,使用 git status --short 和 git ls-files -- <source> 检查源文件是否存在且已被跟踪。未跟踪文件应先使用普通 mv 移动,再执行 git add -- <destination>。
出现 destination exists 时不要直接增加 -f。先比较源文件和目标文件,确认目标是否可以删除或改用新的目标名称。
使用系统的 mv 命令移动文件后,可以执行 git add -A -- <old-path> <new-path> 同时暂存删除和新增;只执行 git add <new-path> 可能遗漏旧路径的删除记录。
查看重命名后的单文件历史可使用 git log --follow -- <new-path>。该选项依赖重命名检测,对目录整体移动和同时发生的大规模改写不一定能完整追踪。
兼容性
Windows 和默认配置的 macOS 文件系统通常不区分文件名大小写,因此大小写重命名建议始终采用临时名称两步操作。路径包含空格、方括号或通配符时应加引号,并保留 --,例如 git mv -- "old name.md" "new name.md"。
git branch
git branch --show-current列出本地分支并标识当前所在分支。
查看本地分支
在仓库中确认已有本地分支以及当前所在分支时使用 git branch。该命令只读取引用,不会切换、创建或删除分支。
基本用法
git branch预期输出
develop
* main
release/1.4* 标识当前分支;没有星号的行是其他本地分支。分支默认按名称排序,实际名称会随仓库不同。
常用参数
--list:显式进入列出模式,适合按名称筛选。-v:同时显示各分支最新提交的短哈希和标题。--sort=-committerdate:按最近提交时间倒序显示。--no-color:关闭颜色,便于日志保存或脚本解析。
风险与边界
git branch 不显示仅存在于远程的分支,也不会自动刷新远程信息。仓库处于 detached HEAD 时,输出可能没有 * 分支名;此时用 git status 确认是否直接检出了某个提交。脚本中不要依赖终端颜色,优先使用 --no-color。
排障清单
- 没有任何输出:仓库可能还没有首次提交,完成一次提交后再查看。
- 提示
not a git repository:当前目录不在 Git 仓库内,进入项目目录或检查.git是否存在。 - 找不到预期分支:它可能仅存在于远程,改用
git branch -a查看。
速查:看到 * main 即表示当前工作区位于 main 分支。
git branch -a同时列出本地分支和远程跟踪分支。
查看全部分支
需要同时核对本地分支和远程跟踪分支时使用 git branch -a。该命令读取本地保存的引用,不会实时连接远程仓库。
基本用法
git branch -a预期输出
* main
release/1.4
remotes/origin/HEAD -> origin/main
remotes/origin/develop
remotes/origin/main无 remotes/ 前缀的是本地分支;remotes/<远程名>/ 开头的是远程跟踪分支。remotes/origin/HEAD -> origin/main 表示远程默认分支指向 main,它不是普通工作分支。
常用参数
-a、--all:同时列出本地分支和远程跟踪分支。-r、--remotes:只列出远程跟踪分支。-v:附带显示最新提交的短哈希和标题。--sort=-committerdate:按最近提交时间倒序排列。
风险与边界
列表中的远程跟踪分支可能已经过期,因为 git branch -a 不会主动抓取远程状态。需要最新结果时先执行远程抓取;使用 --prune 会删除本地已失效的远程跟踪引用,但不会删除远程服务器上的真实分支。生产仓库中先确认远程地址和权限,避免把网络或认证失败误判为分支不存在。
排障清单
- 只看到本地分支:仓库可能尚未配置远程,使用
git remote -v检查。 - 看不到新建的远程分支:先抓取远程更新,再重新执行
git branch -a。 - 仍看到已删除的远程分支:抓取时启用
--prune清理失效跟踪引用。 - 出现多个
remotes/<名称>/:仓库配置了多个远程,应根据远程名前缀判断来源。
速查:本地分支看无前缀行,远程分支看 remotes/<远程名>/ 行。
git branch <NEW_BRANCH> [<START_POINT>]
git switch -c <NEW_BRANCH> [<START_POINT>]基于当前或指定版本创建一个本地分支。
创建新分支
用于基于当前提交或指定版本创建本地分支。git branch 只新增分支引用,不切换工作区;需要创建后立即进入新分支时使用 git switch -c。
基本语法
git branch <NEW_BRANCH> [<START_POINT>]
git switch -c <NEW_BRANCH> [<START_POINT>]预期结果
git branch: <NO_OUTPUT>
git switch -c: Switched to a new branch '<NEW_BRANCH>'省略 <START_POINT> 时以当前 HEAD 为起点;可指定提交哈希、标签、本地分支或远程跟踪分支。成功执行 git branch 通常没有输出。
高频用法
从当前版本创建分支并确认结果:
git branch feature/login
git branch --list feature/login
git branch --show-current预期输出
feature/login
<CURRENT_BRANCH>列表前没有 *,表示 feature/login 已创建但尚未切换;<CURRENT_BRANCH> 是执行前所在分支,实际名称可能不同。
从指定提交创建修复分支:
start_point=HEAD
git branch hotfix/payment "$start_point"
git rev-parse --verify --short hotfix/payment预期输出
<ID>示例以当前 HEAD 为指定起点;可把 start_point 改成有效提交哈希、标签或分支名。<ID> 是新分支指向的短提交哈希。
基于远程分支创建本地跟踪分支:
git fetch origin
git branch --track feature/payment origin/feature/payment预期输出
branch 'feature/payment' set up to track 'origin/feature/payment'.该命令仍不会切换分支。需要立即进入时可改用 git switch --track -c feature/payment origin/feature/payment。
常用参数
-a:列出本地和远程跟踪分支,只用于查看。--track:为新分支设置上游分支,后续可直接执行git pull、git push。--no-track:明确不建立上游关系。-f:强制移动已存在分支的指针,不是普通创建操作。
风险与边界
当同名分支已存在时,普通创建会失败,不会覆盖原分支。不要为绕过报错直接使用 git branch -f:它会移动现有分支指针,可能让尚未合并的提交失去分支引用。安全做法是先用 git log --oneline <BRANCH> 确认历史,再改用新名称或显式备份原分支。
创建分支不会保存、清理或复制未提交修改;工作区仍保持原样。分支名称只记录提交位置,不包含独立文件副本。
排障清单
- 出现
fatal: a branch named ... already exists:运行git branch --list <BRANCH>确认同名分支,选择切换、重命名或换新名称。 - 出现
not a valid object name:起点不存在或尚未拉取;先执行git fetch --all --prune,再检查提交、标签或远程分支名。 - 远程分支找不到:使用
git branch -r查看实际名称,并确认远程仓库不是其他别名。
兼容性
Git 2.23 及以上推荐用 git switch -c 创建并切换;旧版本可使用 git checkout -b <NEW_BRANCH> [<START_POINT>]。
git switch <BRANCH>
git switch -
git checkout <BRANCH>将工作区切换到另一个已有分支。
切换分支
用于把 HEAD、索引和工作区切换到已有本地分支。优先使用职责更明确的 git switch;旧版 Git 可使用 git checkout。
基本语法
git switch <BRANCH>
git switch -
git checkout <BRANCH>预期结果
Switched to branch '<BRANCH>'git switch - 返回上一次所在分支,适合在两个分支之间快速往返。切换成功后,工作区文件会更新为目标分支对应版本。
高频用法
先确认工作区状态,再切换到已有分支:
git status --short
git switch develop
git branch --show-current预期输出
<NO_OUTPUT>
Switched to branch 'develop'
develop<NO_OUTPUT> 表示工作区干净;若第一条命令显示文件状态,先判断这些修改能否安全带到目标分支。
切回上一个分支:
git switch -
git branch --show-current预期输出
Switched to branch '<PREVIOUS_BRANCH>'
<PREVIOUS_BRANCH><PREVIOUS_BRANCH> 取决于切换历史,实际名称可能不同。
需要暂存当前修改后再切换时:
git stash push -u -m 'before switching branch'
git switch develop预期输出
Saved working directory and index state On <CURRENT_BRANCH>: before switching branch
Switched to branch 'develop'-u 会同时暂存未跟踪文件。返回原分支后使用 git stash pop 恢复,恢复前先确认当前工作区干净。
常用参数
-:切换到上一个分支。--detach <COMMIT>:临时查看某个提交,不进入任何分支。--track -c <LOCAL> <REMOTE>:从远程跟踪分支创建本地分支并切换。--discard-changes或-f:丢弃阻碍切换的已跟踪文件修改,风险较高。
风险与边界
未提交修改与目标分支不冲突时,Git 可能允许切换,并让修改继续留在工作区;这不代表修改已经归属于目标分支。提交前应再次执行 git status,避免把改动提交到错误分支。
当切换会覆盖本地修改时,Git 会拒绝执行。不要直接加 -f 或 --discard-changes:触发后可能永久丢失已跟踪文件的未提交修改。安全替代方案是先提交临时提交,或使用 git stash push -u 保存现场。
git switch --detach <COMMIT> 会进入 detached HEAD。此时新提交不属于任何分支;如需保留,应及时执行 git switch -c <NEW_BRANCH> 建立分支引用。
排障清单
- 出现
invalid reference或pathspec ... did not match:本地分支不存在;用git branch --list和git branch -r核对名称。 - 提示本地修改会被覆盖:提交、暂存或手工回退相关文件后再切换,不要盲目强制。
- 提示分支已在其他工作树检出:运行
git worktree list查找<PATH>,到对应工作树切换分支,或先移除不再使用的工作树。 - 远程同名分支无法自动识别:显式执行
git switch --track -c <LOCAL> origin/<REMOTE>,避免多远程仓库下的歧义。
兼容性
git switch 从 Git 2.23 开始提供;更旧版本使用 git checkout <BRANCH>,但不要把切换分支与恢复文件的 checkout 用法混在同一次操作中。
git switch -c <新分支名> [<起点>]创建新的本地分支并立即切换过去。
创建并切换分支
用于从当前提交或指定起点创建本地分支,并立即把工作区切换到新分支。优先使用 git switch -c;旧版 Git 可改用 git checkout -b。
基本语法
语法格式:
git switch -c <新分支名> [<起点>]省略 <起点> 时,新分支从当前 HEAD 创建;起点可以是分支名、标签或提交哈希。
高频用法
从当前提交创建并切换到功能分支:
git switch -c feature/login预期输出:
Switched to a new branch 'feature/login'确认当前分支:
git branch --show-current预期输出:
feature/login从远程主分支创建本地修复分支,并明确设置上游:
git fetch origin
git switch --track -c hotfix/payment origin/main预期输出:
Switched to a new branch 'hotfix/payment'
branch 'hotfix/payment' set up to track 'origin/main'.后续在该分支可直接执行 git pull;首次推送时仍应确认远程目标分支名称。
常用参数
-c:仅在目标分支不存在时创建;已存在会报错,适合日常使用。-C:强制创建或重置同名分支到指定起点后切换,可能移动已有分支指针。--track:从远程分支创建时设置上游,后续可直接执行git pull和git push。--no-track:明确不建立上游关系。
风险与边界
执行 git switch -C <分支> <起点> 且分支已存在时,Git 会把该分支强制移动到新起点;未被其他分支或标签引用的提交可能变得难以发现。安全替代方案是先运行 git branch --list <分支>,确认不存在后使用 -c。
工作区存在与目标分支冲突的未提交修改时,切换会被拒绝,避免覆盖文件。先提交修改,或使用 git stash push -u -m "before branch switch" 临时保存;不要用强制切换绕过检查。
排障清单
出现 fatal: a branch named '<NAME>' already exists 时,说明本地已有同名分支,可直接执行 git switch <NAME>,或改用新的分支名。
出现 invalid reference 时,先用 git branch -a 检查起点是否存在;远程分支刚创建时先执行 git fetch origin 更新引用。
兼容性
git switch 从 Git 2.23 起提供。较旧版本使用:
git checkout -b feature/login预期输出:
Switched to a new branch 'feature/login'速查:新分支不存在时用 git switch -c;已存在时只用 git switch <分支名>。
git branch -m <新分支名>修改本地分支名称并保持提交历史不变。
重命名分支
用于修改本地分支名称,提交记录、文件内容和提交哈希均保持不变。重命名只改变分支引用名称,不会自动修改远程分支。
基本语法
重命名当前分支:
git branch -m <新分支名>重命名其他本地分支:
git branch -m <旧分支名> <新分支名>-m 在目标名称已存在时会拒绝操作;-M 会强制覆盖同名目标分支,日常操作优先使用 -m。
高频用法
把当前分支从 feature/login 改为 feature/auth:
git branch -m feature/auth
git branch --show-current预期输出:
feature/authgit branch -m 成功时通常不输出内容,因此通过 git branch --show-current 验证新名称。
重命名当前未检出的其他分支:
git branch -m bugfix/pay hotfix/pay
git branch --list hotfix/pay预期输出类似:
hotfix/pay前导空格表示该分支存在但不是当前分支;当前分支会显示 *。
同步远程分支
本地重命名后,先推送新名称并设置上游,再删除远程旧名称:
git push -u origin feature/auth
git push origin --delete feature/login预期关键输出类似:
To <REMOTE_URL>
* [new branch] feature/auth -> feature/auth
branch 'feature/auth' set up to track 'origin/feature/auth'.
To <REMOTE_URL>
- [deleted] feature/login<REMOTE_URL> 会显示实际仓库地址。删除旧远程分支前,应确认没有未合并提交,并通知仍在使用旧名称的协作者。
风险与边界
执行 git branch -M <新名称> 且目标分支已存在时,会用当前分支覆盖目标分支引用,目标原先指向的提交可能失去直接引用。安全替代方案是先执行 git branch --list <新名称>;若有输出,先比较 git log --oneline --decorate --graph --all,不要直接强制覆盖。
本地重命名不会更新 GitHub、GitLab 等平台中的默认分支、保护规则、CI 配置或部署脚本。若旧名称被这些系统引用,需要在平台设置和仓库配置中同步修改。
排障清单
出现 fatal: a branch named '<NAME>' already exists 时,说明新名称已被占用。选择其他名称,或先确认该分支可删除后执行 git branch -d <NAME>;未合并分支不要使用 -D 强制删除。
推送后仍跟踪旧远程分支时,重新设置上游:
git branch --unset-upstream
git branch --set-upstream-to=origin/feature/auth预期输出:
branch 'feature/auth' set up to track 'origin/feature/auth'.速查:只改本地名称用 git branch -m;远程也要改名时,执行“推送新分支、设置上游、确认后删除旧分支”。
git branch -d <BRANCH>
git branch -D <BRANCH>删除已合并或不再需要的本地分支。
删除本地分支
用于清理已经合并、废弃或误建的本地分支。优先使用安全删除 -d;只有确认分支中的提交不再需要时,才使用强制删除 -D。
基本语法
git branch -d <BRANCH>
git branch -D <BRANCH>-d 会检查分支是否已合并,未合并时拒绝删除;-D 等价于 --delete --force,会跳过合并检查。
安全删除已合并分支
先切换到需要保留的分支,再查看已合并分支并删除目标分支:
git switch main
git branch --merged
git branch -d feature/login预期输出:
Switched to branch 'main'
feature/login
* main
Deleted branch feature/login (was <COMMIT>).* 表示当前分支。<COMMIT> 是被删除分支最后指向的提交短哈希,实际值会不同。删除分支只移除引用;只要提交仍被其他分支或标签引用,提交内容不会消失。
强制删除未合并分支
当安全删除提示分支未合并时,先确认独有提交:
git log --oneline main..feature/login预期输出:
<COMMIT> 调整登录超时
<COMMIT> 增加登录审计日志输出非空表示这些提交只在 feature/login 可见。确认不要这些提交后再执行:
git branch -D feature/login预期输出:
Deleted branch feature/login (was <COMMIT>).风险与边界
触发条件:对未合并分支执行 -D。可能后果:分支引用立即删除,独有提交之后可能被 Git 垃圾回收。安全替代方案是先创建备份分支:
git branch backup/feature-login feature/login
git branch -D feature/login预期结果:
Deleted branch feature/login (was <COMMIT>).创建备份分支通常没有输出,可用 git branch --list 'backup/*' 验证。不能删除当前检出的分支;该分支若被其他 worktree 检出,也会删除失败。删除本地分支不会删除远程分支,远程删除需另用 git push <REMOTE> --delete <BRANCH>。
排障清单
- 提示
Cannot delete branch ... checked out:先切换分支;若仍失败,运行git worktree list查找其他工作树。 - 提示
not fully merged:先用git log <BASE>..<BRANCH>核对独有提交,不要直接把-d改成-D。 - 删除后发现误操作:立即运行
git reflog找到原提交,再执行git branch <BRANCH> <COMMIT>恢复。
git remote
git remote -v
git remote show <REMOTE>查看远程仓库名称、地址及详细配置。
查看远程仓库
用于确认当前仓库配置了哪些远程名称、拉取与推送地址,以及远程分支的跟踪状态。排查“拉错仓库、推送地址不同、默认分支异常”时先执行这些命令。
基本语法
git remote
git remote -v
git remote show <REMOTE>git remote 只列远程名称;-v 同时显示 fetch 和 push 地址;git remote show 会查询远程并汇总默认分支、跟踪分支和推送关系。
查看名称与地址
git remote -v预期输出:
origin https://github.com/example/project.git (fetch)
origin git@github.com:example/project.git (push)第一列是远程别名,通常为 origin;第二列是地址;末列说明该地址用于拉取还是推送。fetch 与 push 地址可以不同,不能只检查其中一行。
只读取某个远程的有效地址时使用:
git remote get-url origin
git remote get-url --push origin预期输出:
https://github.com/example/project.git
git@github.com:example/project.git查看详细配置
git remote show origin预期输出:
* remote origin
Fetch URL: https://github.com/example/project.git
Push URL: git@github.com:example/project.git
HEAD branch: main
Remote branches:
main trackedHEAD branch 是远程默认分支;tracked 表示本地已建立远程跟踪信息。该命令通常需要访问远程,输出内容会随权限、网络和分支状态变化。
网络不可用时,可直接读取本地配置:
git config --get-regexp '^remote\.origin\.'预期输出:
remote.origin.url https://github.com/example/project.git
remote.origin.fetch +refs/heads/*:refs/remotes/origin/*
remote.origin.pushurl git@github.com:example/project.git没有单独配置 pushurl 时,推送默认复用 url,因此输出可能只有 url 和 fetch。
风险与边界
查看命令不会修改仓库,但终端输出可能包含带用户名、访问令牌或内部域名的 URL。触发条件是远程地址内嵌凭据;可能后果是日志、截图或工单泄露凭据。安全替代方案是只分享脱敏后的主机和仓库路径,并把凭据放入系统凭据管理器或 SSH 配置。
git remote -v 展示的是配置地址,不证明网络可达或具备权限。需要验证读取权限时可执行:
git ls-remote --heads origin预期输出:
<COMMIT> refs/heads/main若出现认证失败、DNS 错误或连接超时,应分别检查凭据、域名解析和代理设置。
排障清单
- 没有任何输出:当前仓库未配置远程,使用
git remote add <REMOTE> <URL>添加。 origin不存在:运行git remote确认实际名称,不要默认所有仓库都叫origin。- 拉取正常但推送失败:重点比较 fetch URL 与 push URL,并检查 SSH 密钥或 HTTPS 凭据。
- 远程分支列表过期:先运行
git fetch --prune <REMOTE>,再查看git remote show <REMOTE>。
git remote add <远程名> <仓库地址>为本地仓库关联新的远程仓库地址。
添加远程仓库
用于把当前本地 Git 仓库关联到新的远程地址。命令只修改本地 .git/config,不会自动上传代码;添加后应核对拉取与推送地址。
基本语法
git remote add <远程名> <仓库地址>远程名通常使用 origin;Fork 项目连接原始仓库时常用 upstream。仓库地址可以是 HTTPS 或 SSH。
高频用法
添加默认远程并检查配置:
git remote add origin https://github.com/example/demo.git
git remote -v预期输出
origin https://github.com/example/demo.git (fetch)
origin https://github.com/example/demo.git (push)fetch 是拉取地址,push 是推送地址;默认情况下二者相同。
为 Fork 仓库添加上游源:
git remote add upstream https://github.com/example/upstream.git
git remote get-url upstream预期输出
https://github.com/example/upstream.git后续执行 git fetch upstream 可获取上游分支,但不会自动合并到当前分支。
常用参数
-f:添加后立即执行一次 fetch;远程仓库较大或网络受限时应谨慎使用。-t <分支>:只跟踪指定分支,可重复指定。-m <分支>:把远程默认分支指向指定名称,例如main。
风险与边界
远程名已存在时会报 remote ... already exists,原配置不会被覆盖。先运行 git remote -v;确需更新地址时使用 git remote set-url,不要先删除再盲目重建。
命令不会验证仓库是否存在、账号是否有权限,也不会确认 URL 是否指向正确项目。不要把访问令牌直接写进 HTTPS URL,否则可能以明文保存在 .git/config。正式推送前应再次核对 git remote get-url origin,必要时使用 git push --dry-run 验证目标与权限。
排障清单
出现 fatal: not a git repository 时,先进入正确仓库目录,或确认是否需要执行 git init。出现名称冲突时,可用 git remote rename <旧名> <新名> 保留原配置;确认无用后再执行 git remote remove <远程名>。
速查:先查 git remote -v,再执行 git remote add,最后用 git remote get-url 核对。
git remote set-url <远程名> <新地址>更新已有远程仓库使用的访问地址。
修改远程地址
用于处理仓库迁移、域名变更,或在 HTTPS 与 SSH 之间切换。修改只作用于当前本地仓库,不会迁移远程分支、标签或权限。
基本语法
git remote set-url <远程名> <新地址>该命令修改远程的 url。未单独配置 pushurl 时,拉取和推送都会使用新地址;已有独立推送地址时,需用 --push 单独修改。
高频用法
替换 origin 的默认地址并验证:
git remote set-url origin https://github.com/example/new-demo.git
git remote -v预期输出
origin https://github.com/example/new-demo.git (fetch)
origin https://github.com/example/new-demo.git (push)从 HTTPS 切换为 SSH:
git remote set-url origin git@github.com:example/new-demo.git
git remote get-url origin预期输出
git@github.com:example/new-demo.git仅设置独立推送地址:
git remote set-url --push origin git@github.com:example/new-demo.git
git remote -v预期输出
origin https://github.com/example/new-demo.git (fetch)
origin git@github.com:example/new-demo.git (push)常用参数
--push:只修改推送地址,不影响拉取地址。--add:追加地址而不是替换,常用于多个推送目标。--delete <正则>:删除匹配的附加地址;正则过宽可能删除非目标配置,操作前先查看全部地址。
风险与边界
地址写错会导致后续 fetch、pull 或 push 失败;若误指向另一个有写权限的仓库,还可能把提交推到错误项目。修改后执行 git remote get-url --all origin,正式推送前使用 git push --dry-run 验证目标与权限。
set-url 不会改变当前分支的上游绑定。仓库迁移后若默认分支名称也变化,应继续检查 git branch -vv 和远程默认分支。不要把访问令牌嵌入 URL,避免凭据以明文写入本地配置。
排障清单
出现 No such remote 时,先执行 git remote 查实际名称;远程不存在则使用 git remote add。SSH 返回 Permission denied (publickey) 时检查密钥和账号权限;HTTPS 返回 401 或 403 时检查令牌、凭据缓存和仓库授权。
速查:修改前后都执行 git remote -v,分别确认 fetch 与 push 指向预期地址。
git fetch [<remote>] [<refspec>]下载远程分支、标签和引用信息但不合并代码。
获取远程更新:git fetch
git fetch 用于把远程仓库的新提交、分支、标签和引用下载到本地,并更新 origin/main 这类远程跟踪分支;它不会自动合并到当前分支,适合在合并、变基或排查远程差异前先同步信息。
命令定位
工作区有未提交修改时也可以执行 fetch,因为它通常不改动工作区和暂存区。执行后,本地分支仍停留在原提交,需要再用 git merge、git rebase 或 git pull 决定如何整合远程更新。
先确认当前远程仓库名称和地址:
git remote -v预期输出:
origin <REMOTE_URL> (fetch)
origin <REMOTE_URL> (push)origin 是常见默认名称;实际名称可能是 upstream 或其他自定义值。
基本语法
git fetch [<remote>] [<refspec>]常用参数:
--all:依次获取所有已配置的远程仓库。--prune:同步时删除远程已不存在的远程跟踪引用。--tags:显式获取远程全部标签。--dry-run:展示计划更新的引用,不实际写入。--verbose:显示更详细的引用更新信息。
高频用法
获取默认远程 origin 的更新:
git fetch origin预期输出:
From <REMOTE_URL>
* [new branch] feature/pay -> origin/feature/pay
<OLD_COMMIT>..<NEW_COMMIT> main -> origin/main
* [new tag] v1.4.0 -> v1.4.0读取方法:[new branch] 表示发现新远程分支;<OLD_COMMIT>..<NEW_COMMIT> 表示远程跟踪分支已从旧提交推进到新提交;[new tag] 表示下载了新标签。仓库没有变化时可能不输出任何内容。
一次更新所有远程并清理失效引用:
git fetch --all --prune预期输出:
Fetching origin
From <REMOTE_URL>
- [deleted] (none) -> origin/feature/old
<OLD_COMMIT>..<NEW_COMMIT> main -> origin/main只获取远程某个分支:
git fetch origin main预期输出:
From <REMOTE_URL>
* branch main -> FETCH_HEAD此命令会把结果记录到 FETCH_HEAD,但是否同时更新 origin/main 取决于引用配置和 Git 版本;自动化脚本不要假设它一定更新远程跟踪分支。它不会切换到 main。
验证远程更新
比较当前分支与远程主分支的提交差异:
git log --oneline --left-right HEAD...origin/main预期输出:
> <COMMIT_A> fix: handle timeout
> <COMMIT_B> feat: add retry policy
< <COMMIT_C> chore: local adjustment以 > 开头的是仅存在于 origin/main 的提交;以 < 开头的是仅存在于当前 HEAD 的提交。若没有输出,表示两端没有独有提交。
风险与排障
git fetch 本身通常安全,但 --prune 会删除本地的远程跟踪引用。触发条件是远程分支已被删除;后果是 origin/<branch> 不再存在,但同名本地分支和其提交不会被删除。首次清理可先执行 git fetch --prune --dry-run origin 查看计划变更。
出现 Could not resolve host 时先检查 DNS 和代理;出现 Permission denied (publickey) 时检查 SSH 密钥、远程地址和账号权限;出现 couldn't find remote ref 时确认分支名大小写和远程是否仍存在。可用以下命令查看远程实际分支:
git ls-remote --heads origin预期输出:
<COMMIT_ID> refs/heads/main
<COMMIT_ID> refs/heads/feature/pay速查:只下载更新用 git fetch origin;同步全部远程并清理失效引用用 git fetch --all --prune。
git fetch --prune [<远程名>]
git remote prune [--dry-run] <远程名>移除本地保存但远程已不存在的分支引用。
清理失效远程分支引用
远程分支被删除后,本地仍可能保留 origin/feature-old 这类远程跟踪引用。使用 git fetch --prune 或 git remote prune 可以移除这些失效引用,避免分支列表、补全结果和脚本继续使用不存在的远程分支。
前置检查
先查看本地记录的远程分支:
git branch -r预期输出:
origin/HEAD -> origin/main
origin/feature-old
origin/main再查询远程服务器当前真实存在的分支:
git ls-remote --heads origin预期输出:
<COMMIT_ID> refs/heads/main若 git branch -r 中存在 origin/feature-old,但远程查询结果没有 refs/heads/feature-old,该引用可以清理。
推荐做法
先预演将被删除的引用:
git remote prune --dry-run origin预期输出:
Pruning origin
URL: <REMOTE_URL>
* [would prune] origin/feature-old确认无误后执行实际清理:
git remote prune origin预期输出:
Pruning origin
URL: <REMOTE_URL>
* [pruned] origin/feature-old[pruned] 表示仅删除本地保存的远程跟踪引用,不会向远程服务器发送删除分支请求。
高频用法
获取远程更新时顺便清理:
git fetch --prune origin预期输出:
From <REMOTE_URL>
- [deleted] (none) -> origin/feature-old对所有远程执行同步和清理:
git fetch --all --prune预期输出:
Fetching origin
From <REMOTE_URL>
- [deleted] (none) -> origin/feature-old
Fetching upstream让当前仓库以后每次获取都自动清理:
git config fetch.prune true
git config --get fetch.prune预期输出:
true需要对所有仓库生效时改用 git config --global fetch.prune true。团队共享环境中建议先使用仓库级配置,避免改变其他项目的行为。
清理后的验证
再次列出远程分支:
git branch -r预期输出:
origin/HEAD -> origin/main
origin/main若同名本地分支仍存在,这是正常现象。可用以下命令分别查看本地分支和跟踪关系:
git branch -vv预期输出:
* main <COMMIT_ID> [origin/main] fix: update config
feature-old <COMMIT_ID> [origin/feature-old: gone] feat: old work[origin/feature-old: gone] 表示本地分支还在,但其上游远程分支已不存在。确认本地提交不再需要后,才考虑执行 git branch -d feature-old;未合并分支不要直接用 -D。
风险与排障
清理命令只删除远程跟踪引用,触发条件是远程端已不存在对应引用;可能后果是依赖 origin/<branch> 的脚本、IDE 配置或比较命令失败。安全替代方案是先用 --dry-run 预演,并在清理前记录重要提交:
git branch --no-track backup/feature-old origin/feature-old预期结果:
命令成功时通常无输出;可用 git branch --list backup/feature-old 验证。该备份命令只适用于失效引用尚未被清理且提交仍可访问的情况。若清理后需要找回提交,可尝试 git reflog --all;但回收记录可能过期,不能替代提前创建本地分支或标签。
速查:日常同步用 git fetch --prune origin;只清理引用用 git remote prune origin;首次操作先加 --dry-run。
git pull [远程仓库] [远程分支]获取远程分支更新并合并到当前分支。
拉取并合并代码
用于把远程分支的新提交获取到本地,并合并进当前分支。默认适合共享分支或允许产生合并提交的协作流程。
基本语法
git pull [远程仓库] [远程分支]git pull 等价于先执行 git fetch,再对取得的远程跟踪分支执行合并。省略参数时,Git 使用当前分支配置的上游分支。
高频用法
拉取当前分支对应的上游分支:
git status --short
git pull预期输出:
Updating a1b2c3d..d4e5f6a
Fast-forward
src/app.js | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)Fast-forward 表示当前分支没有额外本地提交,分支指针直接前移;文件统计表示本次更新涉及的路径和增删行数。实际提交号、文件名和行数会不同。
明确从 origin/main 拉取并合并到当前分支:
git pull origin main预期输出:
From <REMOTE_URL>
* branch main -> FETCH_HEAD
Already up to date.Already up to date. 表示远程 main 没有当前分支尚未包含的提交;<REMOTE_URL> 会显示实际远程地址。
只允许快进,避免自动创建合并提交:
git pull --ff-only本地与远程已经分叉时,预期输出:
fatal: Not possible to fast-forward, aborting.该输出表示命令已经停止,没有创建合并提交。应先查看双方提交,再决定执行普通合并或变基。
常用参数
--ff-only:只能快进,无法快进就停止,适合要求线性历史且禁止隐式合并的仓库。--no-ff:即使可以快进也创建合并提交,只在团队明确要求保留分支合并节点时使用。--no-commit:完成非快进合并但暂不创建提交,便于提交前检查结果;快进合并不受此参数控制。--no-rebase:明确使用合并策略,可覆盖本地pull.rebase=true配置。
风险与边界
工作区存在未提交修改且与远程更新冲突时,拉取会失败,或进入难以直接合并的状态。安全做法是先执行 git status,提交当前修改,或用 git stash push -u 临时保存后再拉取。
本地与远程都存在新提交时,普通 git pull 可能创建合并提交,使历史出现分叉节点。若仓库要求线性历史,优先使用 git pull --ff-only 检测分叉,再按团队规则选择合并或变基。
不要在未确认当前分支和上游分支时直接执行无参数 git pull。错误的上游配置会把非预期分支合入当前分支;先用 git branch -vv 核对跟踪关系。
排障清单
遇到 There is no tracking information for the current branch,先设置上游:
git branch --set-upstream-to=origin/main
git pull预期输出:
branch '<CURRENT_BRANCH>' set up to track 'origin/main'.
Already up to date.<CURRENT_BRANCH> 为实际当前分支名。
遇到合并冲突时,先查看冲突文件:
git status --short预期输出:
UU src/app.jsUU 表示双方都修改了该文件。解决冲突后执行 git add src/app.js 和 git commit;若决定放弃本次合并,执行 git merge --abort。
git pull --rebase [远程仓库] [远程分支]获取远程更新后将本地提交变基到最新版本。
拉取并变基代码
用于先获取远程更新,再把当前分支尚未推送的本地提交依次重放到远程最新提交之后。适合要求线性提交历史的个人功能分支。
基本语法
git pull --rebase [远程仓库] [远程分支]该命令先执行获取,再以远程分支为新基线重放本地提交。被重放的提交会生成新的提交 ID。
高频用法
对当前分支配置的上游执行变基拉取:
git status --short
git pull --rebase预期输出:
Successfully rebased and updated refs/heads/<CURRENT_BRANCH>.<CURRENT_BRANCH> 为实际分支名。该输出表示远程更新已取得,本地提交也已成功重放;没有本地提交需要重放时,也可能显示 Already up to date.。
明确基于 origin/main 更新当前分支:
git pull --rebase origin main预期输出:
From <REMOTE_URL>
* branch main -> FETCH_HEAD
Successfully rebased and updated refs/heads/<CURRENT_BRANCH>.实际远程地址、分支名和提交数量会不同。
工作区有未提交修改时,可以启用自动暂存:
git pull --rebase --autostash存在已跟踪文件修改时,预期输出包含:
Created autostash: <COMMIT_ID>
Successfully rebased and updated refs/heads/<CURRENT_BRANCH>.
Applied autostash.<COMMIT_ID> 为临时自动暂存提交 ID。工作区干净时不会出现创建和恢复自动暂存的提示。
常用参数
--rebase:使用变基代替合并,不生成普通合并提交。--rebase=merges:重放提交时尽量保留本地合并结构,适合确实需要保留合并节点的分支。--autostash:变基前临时保存已跟踪文件的未提交修改,完成后自动恢复。--no-autostash:明确关闭配置中启用的自动暂存,要求工作区先保持干净。
冲突处理
变基过程中出现冲突时,Git 会暂停在当前提交。先查看冲突文件:
git status --short预期输出:
UU src/app.js编辑并解决冲突后继续:
git add src/app.js
git rebase --continue全部提交重放完成后的预期输出:
Successfully rebased and updated refs/heads/<CURRENT_BRANCH>.若当前本地提交已经不再需要,可执行 git rebase --skip 跳过;若想完全恢复到变基前状态,执行 git rebase --abort。
风险与边界
变基会改写本地提交 ID。对已经推送且被他人基于其开发的共享提交执行变基,可能导致其他成员重复提交、冲突或错误覆盖。安全替代方案是在共享分支使用普通合并;只对尚未共享的本地提交执行变基。
变基完成后若远程仍保留旧提交历史,普通推送可能被拒绝。确需更新自己独占的远程分支时使用 git push --force-with-lease,不要使用 --force;前者会在远程分支已被他人更新时拒绝覆盖。
--autostash 只临时处理工作区修改,不保证恢复时无冲突,也不会自动保存未跟踪文件。重要修改应先正常提交,或手动执行 git stash push -u 并确认暂存记录存在。
排障清单
遇到 cannot pull with rebase: You have unstaged changes,先检查并保存修改:
git status --short
git stash push -u -m "before pull rebase"
git pull --rebase
git stash pop无冲突时,预期输出包含:
Saved working directory and index state On <CURRENT_BRANCH>: before pull rebase
Successfully rebased and updated refs/heads/<CURRENT_BRANCH>.
Dropped refs/stash@{0} (<COMMIT_ID>)若 git stash pop 发生冲突,暂存记录通常不会被删除,应先用 git stash list 确认,再手动解决。