Git 新手入门：从第一次提交到分支协作的避坑指南

几乎每个开发者的第一课都是 Git：它不难学，但有不少“看起来没问题、做完就后悔”的坑。本文按一条安全的学习顺序，带你从第一次提交一路走到分支协作，把最常见的坑一次性讲清楚。

一、先配好身份：git config

Git 的每一次提交都会记录作者信息，所以第一件事是告诉 Git 你是谁：

git config --global user.name "你的名字"
git config --global user.email "你的邮箱"

--global 表示全局生效，配置保存在你用户目录下的 .gitconfig 文件里。想确认配置是否生效：

git config --list

新手坑：不配邮箱直接提交，后来发现提交记录里作者是乱码，还得用改写历史的方式修复，得不偿失。先配置，再动手。

二、第一次 init 与 commit

找个练习目录，依次执行：

mkdir git-practice && cd git-practice
git init
echo "hello git" > README.md
git status
git add README.md
git commit -m "初始化项目，添加 README"

git init 会在当前目录生成一个 .git 隐藏目录——这就是仓库的大脑，所有版本信息都存在里面。记住一条铁律：永远不要手动改 .git 里的东西，也不要把它删了（删了就等于丢掉了全部历史）。

git status 是你最好的朋友。任何时候不确定仓库处于什么状态，先敲一遍 git status，它会告诉你哪些文件被修改、哪些已暂存。

三、理解暂存区，写好提交信息

Git 里文件有三种状态：工作区（你正在改的文件）→ 暂存区（git add 之后）→ 仓库（git commit 之后）。暂存区存在的意义是让你可以精细地组织一次提交包含哪些改动，而不是把所有修改一股脑塞进去。

提交信息值得认真对待。一条好的提交信息：动词开头、一句话说清“做了什么”、50 字以内。

反面例子：git commit -m "改了一下" —— 三个月后你自己都看不懂改了什么。
正面例子：git commit -m "修复登录页密码错误提示不显示的问题"

团队协作时，清晰的提交信息就是给队友的说明书。

四、分支与切换：并行开发的利器

分支的本质是一个指向某次提交的“可移动指针”。创建一个功能分支并切换过去：

git branch feature-login        # 创建分支
git checkout -b feature-login   # 创建并切换（一步到位）
# 新版 Git 更推荐语义清晰的写法：
git switch -c feature-login

当前所在的分支由 HEAD 指针指示。切换分支前，先确认工作区是干净的（git status 无未提交改动），否则改动会被带到另一个分支，容易把自己绕晕。

五、merge 与 rebase：两种“合代码”姿势

把分支合回主分支有两种方式：

merge（合并）：保留完整的分叉历史，多产生一次“合并提交”，历史图能看出分支从哪分叉、在哪汇合。

git switch main
git merge feature-login

rebase（变基）：把你的提交“搬”到目标分支最新提交之后，历史变成一条直线，更干净。

git switch feature-login
git rebase main

新手最大的坑在这里：永远不要对已经推送到公共分支的提交做 rebase。rebase 会改写提交的哈希，相当于“篡改历史”，队友基于旧历史的工作会全部错乱。记住口诀：rebase 只用在自己的本地分支上，公共历史只用 merge。

六、远程仓库：push 与 pull

把本地仓库和远程仓库关联起来：

git remote add origin <远程仓库地址>
git push -u origin main        # 第一次推送，-u 建立上下游关联
git push                       # 之后直接 push 即可

从远程拉取更新：

git pull                       # 等价于 git fetch + git merge

git pull 出冲突不要慌，下一节专门讲。养成习惯：每天开工先 git pull 同步最新代码，能避免一大半冲突。

七、五个最常见的坑

坑 1：合并冲突
两个人改了同一文件的同一行，Git 不知道听谁的，就会在文件里留下冲突标记：

<<<<<<< HEAD
你的改动
=======
队友的改动
>>>>>>> feature-login

处理方法：打开文件，人工决定保留哪部分（或融合两者），删掉标记行，然后 git add 再 git commit 完成合并。冲突本身不可怕，可怕的是不看内容就一把梭。

坑 2：detached HEAD（游离 HEAD）
如果你 git checkout 了一个提交哈希而不是分支名，HEAD 就“游离”了——此时提交的代码不属于任何分支，一切换分支就找不回来。正确做法：想基于某个旧提交开展工作，先 git switch -c 新分支名 <提交哈希> 建个分支接住它。

坑 3：force push 的危险
git push --force 会用本地历史强行覆盖远程历史，队友还没拉取的提交会被直接抹掉。万不得已要用强制推送时，请用 git push --force-with-lease：它会在远程有你没见过的新提交时拒绝执行，多一层保险。

坑 4：忘记写 .gitignore
把 node_modules/、编译产物、.env 密钥文件提交进仓库，是新人最高频的翻车现场。项目一开始就建好 .gitignore：

node_modules/
dist/
.env
*.log

如果已经误提交：git rm --cached <文件> 把它从版本控制中移除（保留本地文件），再补上 .gitignore。

坑 5：提交大文件
几百 MB 的安装包、数据集一旦提交，仓库体积就永久膨胀，git clone 会慢到怀疑人生。大文件请用 Git LFS 管理，或者干脆不要进仓库，走对象存储或网盘分享链接。

八、安全学习顺序与协作流程

给新手的安全学习路线：

1. git config 配身份 → 2. init / add / commit 本地三板斧 → 3. 分支的创建与切换 → 4. merge 合并（先别碰 rebase）→ 5. 远程仓库的 push / pull → 6. 熟练后再学 rebase 和冲突处理。

等你加入真实项目，标准协作流程一般是这样：

1. main（或 master）分支受保护，不直接提交；
2. 从最新 main 切出 feature/xxx 功能分支开发；
3. 开发完先同步主分支最新代码、解决冲突；
4. 推送到远程并发起合并请求（Pull Request）；
5. 队友 Code Review 通过后合入 main，删除功能分支。

按这套流程走，你的代码永远有迹可循、有 review 兜底，这才是分支协作真正的价值。

Git 的命令不多，难的是理解它背后的模型：工作区、暂存区、仓库三态，分支是指针，提交是快照。把这几个概念吃透，再回头看上面的命令，会发现每一步都顺理成章。从今天起，用上面的安全顺序练上几遍，下次合代码时，你就是那个不慌的人。