Git 常用命令指南

这是一份面向日常开发的 Git 命令手册，覆盖从仓库创建到问题恢复的完整工作流。示例中的仓库地址、分支名和邮箱均为占位符，执行前请按实际情况替换。

快速索引

任务	推荐命令
查看工作区状态	`git status -sb`
暂存全部改动	`git add -A`
交互式暂存	`git add -p`
提交改动	`git commit -m "type: 描述"`
查看精简历史	`git log --oneline --graph --decorate --all`
创建并切换分支	`git switch -c <branch>`
拉取远端更新	`git pull --ff-only`
首次推送分支	`git push -u origin <branch>`
临时保存现场	`git stash push -u -m "说明"`
撤销公共提交	`git revert <commit>`
查找丢失提交	`git reflog`

初始化与配置

初始化仓库

git init

在当前目录创建 Git 仓库。新项目通常还需要添加 .gitignore，避免提交依赖、构建产物、密钥和编辑器缓存。

克隆仓库

git clone <repository-url>
git clone <repository-url> <directory>

只需要最新历史时，可以使用浅克隆：

git clone --depth 1 <repository-url>

浅克隆限制

浅克隆不包含完整提交历史，不适合依赖历史分析、版本定位或完整发布流程的场景。

查看配置

全局配置当前仓库配置定位配置来源

git config --global --list

全局配置适用于当前用户的所有仓库。

git config --local --list

本地配置来自当前仓库的 .git/config，并覆盖同名全局配置。

git config --show-origin --show-scope --list

输出会同时显示配置作用域和来源文件，适合排查配置覆盖问题。

设置提交身份：

git config --global user.name "Your Name"
git config --global user.email "your-email@example.com"

配置层级

不带 --global 或 --local 的 git config --list 会显示 Git 合并后的有效配置，不只代表当前仓库配置。

SSH 密钥

查看公钥

cat ~/.ssh/id_ed25519.pub

如果文件不存在，先检查 .ssh 目录中是否使用了其他密钥文件名：

ls -la ~/.ssh

不要泄露私钥

id_ed25519.pub 是可以提交给代码托管平台的公钥；不带 .pub 后缀的 id_ed25519 是私钥，禁止分享、上传或提交到仓库。

生成 Ed25519 密钥

ssh-keygen -t ed25519 -C "your-email@example.com"

执行后按提示选择保存位置并设置密码。默认密钥已存在时，不要直接覆盖；应先确认旧密钥是否仍被代码托管平台或服务器使用。

测试 SSH 连接

ssh -T git@<git-host>

将 <git-host> 替换为代码托管平台域名。首次连接时应核对主机指纹，再确认是否信任。

工作区与暂存区

查看状态

git status
git status -sb

-sb 使用精简格式，同时显示当前分支和上游分支关系，适合日常检查。

查看差异

# 工作区与暂存区之间的差异
git diff

# 暂存区与最近一次提交之间的差异
git diff --staged

# 两个提交或分支之间的差异
git diff <ref-a>..<ref-b>

暂存改动

# 暂存指定文件
git add <file>

# 暂存当前目录下的改动
git add .

# 暂存整个仓库中的新增、修改和删除
git add -A

# 按代码片段选择要暂存的内容
git add -p

提交前建议执行 git diff --staged，确认暂存内容与提交目的保持一致。

取消暂存

git restore --staged <file>

该命令只把文件移出暂存区，不会丢弃工作区中的修改。

移动和删除文件

git mv <old-path> <new-path>
git rm <file>

如果只想停止跟踪文件但保留本地文件：

git rm --cached <file>

提交改动

创建提交

git commit -m "feat(module): 增加某项功能"

提交信息格式参见 Git 提交信息规范。

需要填写详细原因时，直接执行 git commit，在编辑器中编写标题、正文和脚注。

修改最近一次提交

# 修改提交内容或提交信息
git commit --amend

# 仅补充暂存内容，保留原提交信息
git commit --amend --no-edit

提交会被重写

--amend 会生成新的提交哈希。已经推送且被他人基于其开发的提交不应随意重写。

历史与检索

查看提交历史

git log
git log --oneline --graph --decorate --all
git log --author="<author>" --since="2026-01-01"
git log -- <path>

查看提交详情

git show <commit>
git show <commit>:<path>

第二条命令用于查看某个提交中文件当时的内容。

搜索历史

# 按提交信息搜索
git log --grep="<keyword>"

# 查找某段文本数量发生变化的提交
git log -S "<text>" --oneline

# 在已跟踪文件中搜索文本
git grep "<pattern>"

定位代码来源

git blame <file>
git blame -L <start>,<end> <file>

git blame 用于定位每一行最后由哪个提交修改，应结合 git show 理解变更背景，而不是用于追责。

分支管理

查看分支

git branch
git branch -a
git branch -vv
git branch --show-current

-a 同时显示本地和远端跟踪分支，-vv 额外显示上游关系和同步状态。

创建和切换分支

# 创建并切换到新分支
git switch -c feature/login

# 切换到已有分支
git switch main

需要兼容旧版 Git 时，可以使用：

git checkout -b feature/login
git checkout main

重命名分支

# 重命名当前分支
git branch -m <new-name>

# 重命名指定分支
git branch -m <old-name> <new-name>

删除分支

# 只删除已经合并的本地分支
git branch -d <branch>

# 删除远端分支
git push origin --delete <branch>

只有在确认未合并提交不再需要时，才使用强制删除：

git branch -D <branch>

强制删除风险

-D 会忽略分支是否合并。执行前先用 git log <branch> 和 git branch --merged 检查提交是否已经保留在其他分支。

远端仓库与同步

管理远端地址

git remote -v
git remote add origin <repository-url>
git remote set-url origin <repository-url>
git remote remove <remote>

获取远端更新

git fetch origin
git fetch --all --prune

fetch 只更新远端跟踪分支，不会修改当前工作分支。--prune 会清理远端已删除分支对应的本地跟踪引用。

拉取并整合更新

仅允许快进使用 Rebase

git pull --ff-only

如果本地和远端已经分叉，命令会停止，避免自动生成意外的合并提交。

git pull --rebase

将本地提交重新应用到远端最新提交之后，使历史保持线性。

推送分支

# 首次推送并设置上游分支
git push -u origin <branch>

# 后续推送
git push

重写个人分支历史后，如果确实需要强制更新远端，应使用：

git push --force-with-lease

避免直接使用 --force

--force-with-lease 会在远端分支出现未知更新时拒绝覆盖，比 --force 更安全。共享分支仍不应重写历史。

合并、Rebase 与 Cherry-pick

合并分支

git switch main
git merge <branch>

只允许快进合并：

git merge --ff-only <branch>

取消尚未完成的合并：

git merge --abort

处理冲突

执行 git status 查看冲突文件。
编辑冲突文件并删除冲突标记。
运行测试或构建，确认结果正确。
使用 git add <file> 标记冲突已解决。
根据当前操作执行 git commit、git merge --continue 或 git rebase --continue。

Rebase

# 将当前分支提交重新应用到目标分支之后
git rebase <base-branch>

# 交互式整理最近 3 个提交
git rebase -i HEAD~3

冲突处理命令：

git rebase --continue
git rebase --skip
git rebase --abort

不要重写共享历史

Rebase 会改变提交哈希。仅整理尚未共享的个人分支提交，避免对公共分支执行 Rebase。

应用指定提交

git cherry-pick <commit>
git cherry-pick --abort

适合把一个或少量独立提交应用到当前分支。大量连续提交通常应优先考虑合并或 Rebase。

暂存工作现场

# 保存已跟踪文件的改动
git stash push -m "工作说明"

# 同时保存未跟踪文件
git stash push -u -m "工作说明"

# 查看暂存列表
git stash list

# 查看某条暂存的详细差异
git stash show -p stash@{0}

# 应用并保留暂存记录
git stash apply stash@{0}

# 应用成功后删除暂存记录
git stash pop

# 删除指定暂存记录
git stash drop stash@{0}

stash 适合临时切换任务，不应替代有意义的提交。执行 pop 后如发生冲突，暂存记录通常会保留，解决冲突后再手动清理。

标签与版本

# 查看标签
git tag --list

# 创建带说明的标签
git tag -a v1.2.0 -m "Release v1.2.0"

# 推送指定标签
git push origin v1.2.0

# 推送所有本地标签
git push origin --tags

# 删除本地和远端标签
git tag -d v1.2.0
git push origin --delete v1.2.0

发布版本建议使用带说明标签，便于保留创建者、时间和发布说明。

撤销与恢复

安全操作速查

目标	命令	是否改写历史
丢弃未暂存的单文件修改	`git restore <file>`	否
取消暂存并保留修改	`git restore --staged <file>`	否
撤销公共提交	`git revert <commit>`	否，会新增提交
撤回最近提交并保留暂存	`git reset --soft HEAD~1`	是
撤回最近提交并保留工作区	`git reset HEAD~1`	是
查找分支移动记录	`git reflog`	否

丢弃未提交修改

git restore <file>

执行前先用 git diff -- <file> 检查将被丢弃的内容。未提交且没有其他备份的修改通常无法通过 Git 恢复。

撤销已发布提交

git revert <commit>

revert 通过新增反向提交撤销变更，不会删除公共历史，是共享分支上的首选方式。

调整尚未共享的本地提交

# 撤回提交，改动保持在暂存区
git reset --soft HEAD~1

# 撤回提交，改动保留在工作区但取消暂存
git reset HEAD~1

恢复丢失提交

git reflog
git switch -c recovery/<name> <commit>

先从 reflog 找到目标提交哈希，再创建恢复分支，避免直接移动现有分支造成二次丢失。

清理未跟踪文件

先预览将被删除的内容：

git clean -nd

确认无误后再执行：

git clean -fd

不可恢复操作

git reset --hard 和 git clean -fd 可能永久丢失未提交内容。执行前必须检查 git status、git diff 和预览结果，并确认没有需要保留的文件。

忽略规则排查

# 判断文件是否被忽略，并显示匹配规则
git check-ignore -v <path>

# 查看已忽略文件
git status --ignored

.gitignore 不会自动停止跟踪已经提交的文件。需要保留本地文件并停止跟踪时使用：

git rm --cached <file>

定位问题提交

使用二分查找定位引入问题的提交：

git bisect start
git bisect bad
git bisect good <known-good-commit>

Git 会逐步切换候选提交。每轮验证后执行 git bisect good 或 git bisect bad，定位完成后退出：

git bisect reset

Worktree

Worktree 可以让同一仓库的多个分支同时存在于不同目录，适合在当前任务未完成时并行处理紧急修复。

# 基于现有分支创建工作树
git worktree add ../project-hotfix hotfix/login

# 创建新分支并添加工作树
git worktree add -b hotfix/login ../project-hotfix main

# 查看工作树
git worktree list

# 移除工作树
git worktree remove ../project-hotfix

# 清理失效记录
git worktree prune

移除前确认目标工作树没有未提交修改。

Submodule

# 添加子模块
git submodule add <repository-url> <path>

# 克隆后初始化全部子模块
git submodule update --init --recursive

# 更新到子模块远端跟踪分支
git submodule update --remote --recursive

# 查看子模块状态
git submodule status --recursive

父仓库只记录子模块的提交指针。更新子模块后，需要在父仓库中提交新的指针；协作方拉取父仓库后也需要同步子模块。

仓库检查与维护

# 检查对象和引用完整性
git fsck

# 优化本地仓库存储
git gc

# 统计对象数量和磁盘占用
git count-objects -vH

Git 通常会自动维护仓库，不需要频繁手动执行 git gc。大型仓库出现明显性能或空间问题时再评估使用。

常用工作流

开始功能开发提交并推送同步主分支安全撤销线上变更

git switch main
git pull --ff-only
git switch -c feature/<name>

git status -sb
git diff
git add -p
git diff --staged
git commit -m "feat(scope): 描述变更"
git push -u origin feature/<name>

git fetch origin
git rebase origin/main
git push --force-with-lease

该流程只适用于个人功能分支。共享分支应按团队约定使用合并或禁止重写历史。

git switch main
git pull --ff-only
git switch -c revert/<name>
git revert <commit>
git push -u origin revert/<name>