Git 使用手册

新项目首次推送

新建本地仓库，完成首次提交，再推送到空远程仓库。

初始化仓库与提交身份

cd project
git init -b main
git config --local user.name "Your Name"
git config --local user.email "you@example.com"

姓名和邮箱会写入提交记录。

检查文件并创建首次提交

先编写 .gitignore，排除构建产物、本地配置和密钥。确认文件范围后再暂存。

git status --short
git add -- .gitignore README.md src/
git diff --cached --stat
git diff --cached
# 按项目要求执行构建、格式检查和测试
git commit -m "Initialize project"

关联空远程并推送

git remote add origin https://example.com/team/project.git
git remote -v
git push -u origin main

远程已有提交时，先克隆，再导入本地文件。

参考：git init

独立功能分支开发

每个任务创建独立分支，完成后通过 PR／MR 合入主线。

获取项目并创建任务分支

# 仅首次获取项目时执行
git clone https://example.com/team/project.git
cd project

切换分支前，用 commit 或 stash 保存未完成的修改。

git status --short --branch
git fetch origin
git switch --no-track -c feature/search origin/main

--no-track 避免将 origin/main 设为任务分支上游；首次推送时再关联对应的远程任务分支。

实现修改并分次提交

git status --short
git diff -- src/search.java
git add -p -- src/search.java
# 新文件可直接 git add，或先 git add -N 再按块暂存
git diff --cached
git diff --cached --check
# 运行与修改相关的测试
git commit -m "Add search validation"

git diff 查看工作区差异，git diff --cached 查看待提交内容。

同步主线并处理冲突

推送前，将本地提交变基到最新主线。

git fetch origin
git rebase origin/main

变基遇到冲突时，编辑冲突文件后继续。要放弃本次变基，执行 abort。

git status
git diff --name-only --diff-filter=U
# 编辑冲突文件；若解决方式为删除，使用 git rm
git add -- <resolved-file>
git rebase --continue
# 放弃本次变基时改用：git rebase --abort

--skip 会跳过整个提交。

推送分支并提交评审

git diff origin/main...HEAD
git log --oneline origin/main..HEAD
git push -u origin feature/search

创建 PR／MR，源分支为 feature/search，目标分支为 main。

评审后的修改继续提交并推送。已共享的分支使用 merge 同步主线，保留提交历史。

# 完成评审修改后
git add -- src/search.java
git diff --cached
# 重新运行测试
git commit -m "Address search review feedback"
git push origin feature/search

合并后更新主线与清理分支

PR／MR 合并后，更新本地主线并删除任务分支。

git switch main
git pull --ff-only origin main
git branch -d feature/search
git fetch --prune origin

-d 拒绝删除时，检查提交是否已合入。squash 合并会产生新提交，原提交可能不在主线历史中。--prune 清理已失效的远程跟踪引用。

参考：git switch

参考：git rebase

多人共用分支协作

多人共用分支时，使用 merge 整合彼此的提交。

检出共同维护的分支

git fetch origin
# 本地尚无该分支时
git switch -c feature/search --track origin/feature/search
# 本地已有该分支时，只执行：git switch feature/search

跟踪关系用于比较本地与远程进度。

提交本地修改并获取远程更新

git status --short
git diff
git add -- src/search.java
git diff --cached
# 运行相关测试
git commit -m "Handle empty search input"
git fetch origin
git log --left-right --oneline HEAD...origin/feature/search

日志中 < 表示本地独有提交，> 表示远程独有提交。双方都有提交时，分支已经分叉。

整合同伴提交并解决冲突

git merge origin/feature/search

有冲突时，编辑文件并保留需要的修改，再完成合并。

git status
# 编辑冲突文件并检查最终行为
git add -- <resolved-file>
git diff --cached
# 运行测试
git merge --continue
# 放弃本次合并时改用：git merge --abort

验证合并结果并推送

git status
git log --oneline --graph -10
# 运行完整的相关测试
git push origin feature/search

推送被 non-fast-forward 拒绝时，重新 fetch、merge，再推送。强推会覆盖同伴的提交。

参考：git merge

参考：git push

开发期间处理紧急修复

先用 stash 保存当前工作，再切换到修复分支。

保存当前任务

git status --short --branch
git stash push -u -m "search before urgent fix"
git stash list
git status --short

-u 会一并保存未跟踪文件，被忽略文件除外。

从待修复版本创建分支

git fetch origin
git switch --no-track -c fix/search-crash <release-tag-or-commit>

从需要修复的版本标签或提交号创建分支。

完成修复并送审

# 修改文件并复现、验证问题
git add -- src/search.java
git diff --cached
git commit -m "Fix search crash"
git push -u origin fix/search-crash

修复完成后提交评审，再按项目流程发布。

将修复带回开发主线

发布分支与开发主线不同时，用 cherry-pick 将修复带回主线。

git fetch origin
git switch --no-track -c fix/search-main origin/main
git cherry-pick <fix-commit>
# 验证主线上的修复行为
git push -u origin fix/search-main

cherry-pick 有冲突时，解决后 git add，再执行 git cherry-pick --continue；放弃时执行 git cherry-pick --abort。

恢复原来的工作

git switch feature/search
git stash list
git stash show -p "stash@{0}"
git stash apply "stash@{0}"
git status

按说明找到对应的 stash 记录。apply 保留记录，加 --index 可恢复暂存状态；遇到冲突先解决。

# 确认恢复完整后，重新核对序号再删除
git stash drop "stash@{0}"

参考：git stash

参考：git cherry-pick

错误修改的撤销与恢复

按修改所处的状态选择撤销方式。

未提交：检查差异后恢复文件

git status --short
git diff -- src/search.java
git diff --cached -- src/search.java

取消暂存，保留工作区修改：

git restore --staged -- src/search.java

丢弃未暂存修改，用暂存区内容覆盖工作区。被覆盖的修改可能无法恢复。

git restore --worktree -- src/search.java

仅本地提交：补充内容或重新拆分

amend 将暂存内容补入最后一次提交，--no-edit 保留提交说明。

git add -- src/search.java
git diff --cached
git commit --amend --no-edit

重新拆分最后一次提交时，reset --mixed 撤销提交和暂存状态，保留文件内容。

git reset --mixed HEAD~1
git status --short
git diff
git add -p
# 检查并提交第一组改动，剩余改动另行暂存、提交
git diff --cached
git commit -m "Extract search validation"

新增文件在 reset 后可能变成未跟踪状态，git add -p 不会直接纳入它们；先 git add -N -- <new-file> 或直接暂存指定文件。

已经共享：创建反向提交并送审

已共享的提交用 revert 撤销。先从主线创建回退分支。

git status --short
# 保存已有修改，确认工作区干净后继续
git fetch origin
git switch --no-track -c revert/search origin/main
git show <bad-commit>
git revert <bad-commit>
# 验证回退后的行为
git push -u origin revert/search

冲突解决后执行 git add 和 git revert --continue；放弃时执行 git revert --abort。回退合并提交时，-m 指定保留哪条父分支，会影响后续合并。

误删分支或误重置：找到提交并建立恢复分支

git reflog --date=iso
git show <lost-commit>
git branch rescue <lost-commit>
git log --oneline rescue -10

找到提交后建立 rescue 分支。reflog 是本地记录，会过期。

参考：git restore

参考：git reset

参考：git revert

参考：git reflog

其他

查询文件历史与变更来源

git log --oneline --graph --decorate -20
git log --oneline -- src/search.java
git log --oneline --grep="search"
git show <commit> -- src/search.java
git blame -L 20,40 -- src/search.java

blame 显示每行最后修改的提交，再用 git show 查看修改内容。

维护忽略规则

.gitignore 中的示例规则：

build/
*.log
config/local.env

# 查看命中的忽略规则
git check-ignore -v -- build/app.log
# 已被跟踪的文件不会因加入 .gitignore 自动退出仓库
git rm --cached -- config/local.env
git add -- .gitignore
git diff --cached

--cached 保留本地文件，从后续版本中移除它。历史提交仍保留原内容，已泄露的密钥需要撤销或轮换。

# 仅预览未跟踪文件清理范围，不执行删除
git clean -nd

标记与推送发布版本

git show <release-commit>
git tag -a v1.0.0 <release-commit> -m "Release 1.0.0"
git show v1.0.0
git push origin refs/tags/v1.0.0

标签标记发布版本。

核对身份与修改远程地址

git config --show-origin --get user.name
git config --show-origin --get user.email
git remote -v
# 仓库迁移后，确认新地址再修改
git remote set-url origin https://example.com/team/new-project.git
git remote -v

参考：gitignore

参考：git tag