Git与Gitee高频命令实战：从SSH配置到分支合并与冲突解决

做开发的兄弟大概都有过这样的体验：Git 装好了，Gitee 仓库建好了，结果日常提交、推送、拉取全靠一顿复制粘贴，一旦遇到“push 被拒绝”“SSH 认证失败”“commit 信息写错了”这类报错，整个人直接懵掉。前段时间带团队做代码托管迁移，一个新人一个下午问了我三遍同样的问题，我才意识到很多人缺的不是工具，而是一份能把“为什么”讲清楚的 Git 与 Gitee 常用命令速查手册。我决定把这几年实测下来最高频、最常用的那一拨命令整理成文，从安装配置、SSH 通联、日常提交，到分支合并、冲突解决、撤销回滚，再到 Gitee Pages、开源许可证、子模块这些容易被忽略的功能，一次说透。这份内容适合刚接触 Git 与 Gitee 的开发者，也适合每天都在跟远程仓库搏斗、想把工作流沉淀下来的测试、运维和带新人的老手。

1. 环境先跑通：安装配置与首个仓库

1.1 三大系统安装 Git：别再下到“假”安装包

网上搜 Git 安装教程，很容易下到捆绑全家桶的第三方站点资源，这种事情我见得太多了。认准 Git 官方仓库或者系统自带的包管理器，装出来的版本干净又可控。

Windows 最简单，去 git-scm.com 下载安装包，一路 Next 就能装完。装完在开始菜单里能找到 Git Bash，这就是 Windows 下最顺手的命令行终端。Linux 直接用包管理器：

# Ubuntu / Debian sudo apt update && sudo apt install git # CentOS / RHEL sudo yum install git # 验证 git --version

macOS 上有 Homebrew 就用brew install git，效率最高。装完第一个命令永远是验证版本，git --version能返回版本号，说明环境没问题。如果提示找不到命令，先检查 PATH 环境变量，Windows 上重点看看是不是装完没有重启终端。

提示：不建议使用 IDE 自带的 Git，版本可能很老。命令行工具和 IDE 的 Git 插件版本可以独立安装，IDE 也能配置成调用系统 Git，这样两边行为一致，排查问题少绕路。

1.2 本地全局配置：提交者的“身份 ID”必须写清楚

Git 装好后的第一件事不是建仓库，而是设置user.name和user.email。这两个配置会写进每一次提交记录里，等于你的签名。不配置或者配置错邮箱，提交记录上就会出现“未知作者”，Gitee 的动态也不会挂到你的账号上。

git config --global user.name "你的昵称" git config --global user.email "你的邮箱" # 建议顺手做的配置 git config --global init.defaultBranch main git config --global core.autocrlf input git config --global color.ui auto # 查看配置 git config --list git config user.name

解释一下core.autocrlf：Windows 和 Linux/macOS 的换行符不一样，这个配置用于把回车符自动转换掉，避免出现“明明没改文件，git diff却显示整段变化”的经典乌龙。Windows 上建议设置为true，Mac/Linux 用input。这里还有个容易被忽略的细节：如果项目里已经混用了换行符，单独改配置并不会自动修历史文件，需要后续的规范化提交来处理。

接着可以配别名，把高频命令缩短：

git config --global alias.st status git config --global alias.ci commit git config --global alias.lg "log --oneline --decorate --graph --all" git config --global alias.last "log -1 HEAD"

配好之后，git lg可以直接看到带分支关系的提交图，比默认的git log直观太多。这条别名我逢人必推。

1.3 在 Gitee 创建仓库并完成本地初始化

到这一步，先去 Gitee.com 注册账号，完成实名认证。注册和实名我在实操里踩过坑：如果跳过手机绑定，后续创建私有仓库、开启 Pages 服务都会被卡住，所以别偷懒。

登录后右上角“新建仓库”，填仓库名，选“私有”或“公开”。新手喜欢一上来就点公开，如果只是个人练习，强烈建议先私有，以后可以再改。仓库描述可以不填，“初始化仓库”可以勾选生成 README 文件，初始分支选不选都行。创建成功后，复制仓库地址，SSH 格式长这样：

git@gitee.com:用户名/仓库名.git

回到本地终端：

git init git remote add origin git@gitee.com:用户名/仓库名.git git branch -M main git add README.md git commit -m "init: 项目初始化" git push -u origin main

其中git branch -M main很关键，它把默认分支改名为main，和 Gitee 仓库保持一致，避免后面推送时出现“分支名对不上”的困惑。第一次推送后，Git 会把本地main和远程origin/main关联起来，以后直接git push就行，不用再带参数。

顺带提一句.gitignore：建项目时最好先写好忽略规则，把node_modules/、dist/、*.log、.env这类不该进仓库的内容排除掉。但要注意，忽略规则只对尚未被跟踪的文件生效，如果文件已经被git add过，再写进.gitignore是不会自动生效的，需要用git rm --cached停止跟踪。

2. 打通 Gitee 远程：SSH 密钥、关联仓库与代码拉取

2.1 生成 SSH 密钥并配置到 Gitee

Gitee 支持 HTTPS 和 SSH 两种协议。公开仓库用 HTTPS 拉代码没问题，但推送时光输密码就够烦的，私有仓库更是每次都要验证。SSH 的好处是配置一次，之后就能免密推送。很多新人第一次遇到“SSH 认证失败”就是卡在这里。

生成密钥推荐用ed25519，比老式的 RSA 更短更安全。如果你的服务器或 Git 版本较旧，再退回 RSA 4096：

ssh-keygen -t ed25519 -C "your_email@example.com" # 兼容性方案 ssh-keygen -t rsa -b 4096 -C "your_email@example.com"

执行后一路回车，默认会在~/.ssh目录生成一对密钥：id_ed25519是私钥，id_ed25519.pub是公钥。私钥绝对不能外传，公钥可以随意分享。

用cat ~/.ssh/id_ed25519.pub查看并复制公钥内容，然后登录 Gitee，进入【设置】→【安全设置】→【SSH 公钥】，粘贴保存。保存后用下面命令验证：

ssh -T git@gitee.com

看到提示Hi 你的昵称! ...就代表通了。首次连接时终端会问是否信任主机，输入yes即可，这是正常的安全确认，不是报错。

注意：如果你本机配置了多个 SSH key（比如公司 GitLab 和个人 Gitee 混用），别把 key 全放在默认位置然后互相覆盖。建议在~/.ssh/config里按域名区分，指定各自使用哪个私钥，避免“权限被拒”的诡异问题。

2.2 关联远程仓库：查看、添加、修改地址

Gitee 仓库创建好之后，本地仓库需要知道“远程是谁”，这就是remote管理命令的用处。

# 添加远程仓库 git remote add origin git@gitee.com:用户名/仓库名.git # 查看已有远程 git remote -v # 修改远程地址 git remote set-url origin git@gitee.com:用户名/新仓库名.git # 删除远程关联 git remote remove origin

git remote -v会显示你要 push 和 fetch 的两个地址，平时多看一眼，能避免推送到了错误仓库。两种协议的选择我整理成了一张表：

如果在公司内网或代理环境，HTTPS 遇到证书问题会比 SSH 多，这种环境下 SSH 反而更省心。

2.3 从 Gitee 拉取项目到本地：命令行、IDEA、VS Code 三种姿势

拉取项目最基础的方式是git clone，一条命令把远程仓库完整复制到本地：

git clone git@gitee.com:用户名/仓库名.git # 拉取指定分支 git clone -b develop git@gitee.com:用户名/仓库名.git

克隆完成后，本地会自动生成一个main分支，并根据远程分支建立跟踪关系。直接在 IDE 里操作也没问题，IDEA 的做法是File → New → Project from Version Control，把仓库地址贴进去，选择目录，等待依赖索引完成就行。VS Code 则用命令面板输入Git: Clone，或者直接在终端里git clone后用code 目录名打开。

拉下来的项目有个特点：默认在远程跟踪分支上，你在这个基础上新建一个本地分支再开发，是最稳妥的做法。

git checkout -b feature/login

只要你的开发任务不是直接在主干上改，养成“新功能开新分支”的习惯，后面合并、回滚都会从容很多。

3. 日常提交闭环：三区模型、add/commit/push、amend 与 LFS

3.1 必须搞懂的三区模型：工作区、暂存区、版本库

很多人用 Git 只记得“改代码、提交、推送”，出问题就卡壳，根子是对三区模型没概念。Git 把文件状态分成三块：工作区是你打开编辑器看到的文件；暂存区是git add之后存放“准备提交”的区域；版本库是git commit后生成提交历史的地方。

用点外卖类比就很好懂：菜买回来放在厨房是工作区，切好洗好装盘是git add，下锅炒熟是git commit，骑手送出门是git push。少任何一个环节，菜都不会到顾客手里。

理解了这个模型，很多怪现象就有答案了：git diff默认只显示工作区和暂存区的差异，git diff --staged才显示暂存区和版本库的差异；git commit -a能跳过暂存直接提交“已跟踪文件”的修改，但新文件依然不会进去；git reset的三种hard/soft/mixed也是围绕这三区设计的。

3.2 add、commit、push 的实际用法与提交信息规范

# 添加文件到暂存区 git add src/App.js git add . # 当前目录全部修改 git add -A # 包括删除在内的全部修改 # 提交 git commit -m "feat: 新增登录页面" # 推送 git push origin main

第一次推送某个新分支时，用git push -u origin main，-u会建立本地分支和远程分支的跟踪关系，之后直接git push就可以了。如果忘了-u，虽然也能推上去，但后面每次都要写完整参数，不推荐。

提交信息我强烈建议按conventional commits风格写：feat表示新功能，fix修 bug，docs改文档，refactor重构，test补测试，chore杂务。比如：

feat: 新增登录页 fix: 修复登录后跳转失效 docs: 补充部署说明

这样git log --oneline扫一眼，整个开发节奏清清楚楚。将来做版本发布、代码审查，能省下大量沟通成本。

3.3 改提交信息或补提交：commit --amend 的正确姿势

提交完才发现写错了信息，或者忘了把某个文件加进去，这是高频场景。git commit --amend可以修改最近一次提交：

# 修改提交信息 git commit --amend -m "fix: 正确的提交信息" # 只补增文件，不改信息 git add 漏掉的文件 git commit --amend --no-edit

--amend的本质是“用新提交替换旧提交”，所以它只适合还没推送的提交。如果已经git push了，强行amend会改写历史，导致本地和远端分叉，队友拉代码时就是一堆冲突。遇到已经推送且想改信息的情况，正确做法是git revert生成一个反向提交，把改动用“新提交”的形式撤销掉，而不是篡改历史。

3.4 仓库里塞不进大文件：Git LFS 与 Gitee 容量限制

日常办公里，PSD、安装包、视频素材经常几个 GB，这类文件直接提交进 Git，会让仓库体积爆炸，克隆慢到怀疑人生。Gitee 对单仓库容量、单个文件大小都有明确限制，超出后会被拒绝推送。解决方案是 Git LFS（Large File Storage）。

# 安装 LFS（只需一次） git lfs install # 指定哪些扩展名交给 LFS 管理 git lfs track "*.zip" "*.psd" "*.exe" # LFS 会生成 .gitattributes，提交它 git add .gitattributes git commit -m "chore: 使用 LFS 管理大文件"

git lfs track之后，再git add那些扩展名的文件，Git 并不会把大文件本体塞进仓库，而是存一个指针，真正的文件交给 LFS 服务器管理。其他人git clone时会通过指针自动下载实际文件。

需要提醒的是：如果项目早期已经有大文件进去了，后期再补 LFS 是救不了历史的，得借助git filter-branch或git lfs migrate这类重写历史的操作，成本很高。所以新建仓库时就要定好规矩，把.gitattributes第一时间提交。

4. 分支操作：创建切换、合并 rebase、解决冲突

4.1 分支的本质与高频命令

分支相当于在同一个仓库里开多个互不干扰的工作副本。最常见的用法是main保持稳定，开发都在feature分支推进，大家互不踩脚。

# 查看分支 git branch git branch -a # 创建分支 git branch feature/login # 创建并切换 git checkout -b feature/login # 新版本更推荐的写法 git switch -c feature/login # 切换已有分支 git switch main # 删除本地分支 git branch -d feature/login # 删除远程分支 git push origin --delete feature/login

我现在更推荐用git switch和git restore，语义比checkout的重载清晰：switch专门负责切分支，restore专门负责还原文件，不会混。

4.2 merge 与 rebase：什么时候用哪个

合并分支时，merge和rebase是两种不同哲学。

git merge feature/login会把 feature 分支的最新提交合并进当前分支，生成一个合并提交，完整保留两条分支的发展历史。用--no-ff强制生成合并提交，防止快速前进时丢失分支形状。

git rebase main则是把当前分支的提交“重放”到 main 的最新提交之上，历史变成一条直线，非常清爽。

日常团队协作我习惯这样做：个人开发分支上使用 rebase 保持和main同步，做到干净线性；合回公共main分支时用 merge，让发布节点清晰可见。有一点要切记：已经推送到公共分支的提交，不要再用 rebase 改写，否则其他成员会经历一串莫名其妙的冲突。

4.3 解决冲突实操

只要多人改同一区域代码，冲突迟早会来。发生时 Git 会在文件中插入冲突标记：

<<<<<<< HEAD 当前分支的代码 ======= 另一分支的代码 >>>>>>> feature/login

处理方式不复杂：打开文件，把<<<<<<<、=======、>>>>>>>这些标记行删掉，留下最终要保留的代码，然后：

git add 冲突文件 git commit -m "merge: 解决登录页样式冲突"

如果在rebase过程中冲突，解决并git add后不是直接 commit，而是执行git rebase --continue。要是觉得自己越改越乱，运行git rebase --abort可以完全退回 rebase 之前的状态。这是我踩过不少坑后的体会：冲突解决就像拼拼图，先看清两边意图，别盲目删代码；涉及需求分歧的时候，先找人确认再动手。

5. 同步与撤销：fetch/pull、push 被拒绝、reset/revert/stash

5.1 fetch 与 pull：别再把两个概念混在一起

很多新人以为git pull等于“从远程更新”，其实它的实质是fetch加上merge两步。git fetch origin只是把远程的新提交下载到本地引用，不会动工作区，看完确认没问题再合并，安全感强得多。

# 只下载远程更新 git fetch origin # 查看远程分支 git log origin/main --oneline # 确认无误后再合并 git merge origin/main # 一步到位的等价物 git pull origin main

为了让历史保持干净，我推荐直接养成git pull --rebase origin main的习惯，它等价于“先把本地提交暂存，拉取远程新提交，再把本地提交逐个重放上去”。这样不会生成多余的“merge remote-tracking branch”提交。

5.2 push 被拒绝：非快进冲突的解决思路

开头提到的那个新人提问，报错长这样：

! [rejected] main -> main (non-fast-forward)

原因很简单：远端有本地没有的新提交，本地不是基于最新代码做的修改。解决步骤也是固定的：

git pull --rebase origin main git push origin main

pull --rebase会把本地新提交暂存，拉取远端更新，再把本地提交重放到最新位置，最后 push 就能成功。

如果不是rebase手法而是本地已经有大量提交，也可以merge后再 push，历史里会多一个合并提交，但不会丢内容。真正要小心的是git push --force：它会直接覆盖远端历史。我见过有人用它覆盖了队友提交的情况，场面非常难看。真要强制推送，务必用git push --force-with-lease，如果远端出现了未知新提交，它会拒绝执行，避免误伤。

5.3 撤销操作：reset、revert、stash 三兄弟

撤销是 Git 里最混乱的考点，先把三兄弟分清。

git reset是针对“还没推送”的场景：

# 丢弃最近一次提交及所有改动 git reset --hard HEAD~1 # 撤销提交但保留改动在暂存区 git reset --soft HEAD~1 # 撤销提交，改动回到工作区（默认模式） git reset --mixed HEAD~1

git revert是针对“已经推送”的场景，它会生成一个反向提交，把之前的改动撤销，但不动历史。团队协作要撤销某个已推送的提交，用它，而不是 reset。

git stash是用来“临时保存脏工作区”的：

git stash git stash pop git stash list git stash drop stash@{0}

比如当前功能改到一半，临时要去修一个线上 bug，直接切分支会报错说不允许带未提交改动。这时候git stash把半成品收起来，切分支修 bug，回来再git stash pop恢复现场，非常好用。如果连自己误删的分支也想救回来，终极武器是git reflog，它能列出所有历史操作对应的提交号，找到后git branch 分支名 提交号就能恢复。

6. Gitee 进阶：Pages、开源许可证、子模块

6.1 Gitee Pages：用仓库托管静态站点

Gitee Pages 的作用是把仓库里的静态文件（HTML、CSS、JS）部署成可访问的网站，很适合个人博客、项目文档、开源项目主页。

操作流程是：进入仓库页面 → 选择【服务】→【Gitee Pages】→ 选择要部署的分支和目录 → 点击部署。首次使用需要完成实名认证，部署后访问地址一般是用户名.gitee.io/仓库名。

部署不是自动的，这点很坑：每次推送代码更新后，都要回到 Gitee Pages 页面手动点击“更新”按钮，站点才会重新部署。第一次用的时候，我推了代码左等右等页面都没变，后来才意识到漏了这个手动步骤。如果有自定义域名需求，Gitee 会要求按国内域名管理规范完成备案，具体要求以官方页面和提示为准。

6.2 开源许可证怎么选：别再闭眼选 MIT

Gitee 新建仓库时会让你填“开源许可证”，默认可能是不选。一般人直接选 MIT，其实不同许可证的约束差异非常大，直接决定别人能不能把你的代码用在商业项目里。

选许可证的标准其实很简单：你只是想让人随便用，选 MIT；你希望用的人别把你的代码改成闭源商业版，选 GPL；你所在公司有法务要求，选 Apache-2.0。个人小项目、学习仓库，提前选 MIT 最省事。

6.3 仓库能不能包含子项目：用 Submodule 别用复制粘贴

“Gitee 创建的仓库能包含子项目吗”这个问题，答案是能，但不要把另一个仓库直接复制进去。正确做法是使用 Git Submodule，在父仓库里记录一个指向外部仓库提交号的引用。

# 添加子模块 git submodule add git@gitee.com:用户名/公共库.git libs/public-lib # 初次拉取子模块内容 git submodule update --recursive

团队其他成员克隆主仓库后，需要执行git submodule init和git submodule update才能把子模块实际内容拉出来。子模块的好处是版本锁定，父仓库固定引用子模块的某个具体提交，升级时显式更新，不容易出现“我这边能跑你那边不行”的问题。

缺点也很明显：管理成本偏高，子模块一多，更新和审查流程就很重。小型项目我通常不推荐子模块，更建议把公共代码抽成独立依赖包，用包管理器引入，项目结构会清爽很多。

7. 高频排查速查：日志、差异、忽略规则与常见报错

7.1 看历史与差异的高效姿势

定位问题时别一个个git log翻到眼瞎，常用参数能大幅提高效率：

# 简洁日志 git log --oneline # 图形化分支图 git log --graph --oneline --all # 按作者搜 git log --author="名字" # 按提交信息搜 git log --grep="feat" # 最近 N 条 git log -5 # 查看每次提交的具体改动 git log -p

看差异的四个常用场景：

git diff # 工作区 vs 暂存区 git diff --staged # 暂存区 vs 仓库 git diff HEAD # 工作区+暂存区 vs 仓库 git diff main..feature # 两个分支对比

配合git diff --stat可以只看改动了哪些文件，肉眼扫描效率更高。

7.2 停止跟踪与忽略规则

.gitignore的写法并不复杂，但生效规则常被误解：

node_modules/ dist/ *.log .DS_Store .env

忽略规则只对新加进去的未跟踪文件生效。已经跟踪过的文件，改.gitignore是压不住的，需要先把文件移出跟踪：

git rm --cached .env

这条命令会停止跟踪.env，但本机文件还在，非常适合“配置文件不适合进仓库，但已经提交过”的清理场景。操作完成后记得提交并推送，团队里其他人也要同步执行一次类似处理。

7.3 常见报错与现象速查表

把高频问题整理成表，遇到直接查：

这张表是我被问得最多的内容实战汇总。真遇到不确定的报错，第一步永远是git status看当前状态，第二步看报错全文找关键短语，第三步再去搜索引擎，效率远高于无头绪乱试。

这份速查写到这，我自己最有体会的一点是：Git 的命令根本背不完，但核心骨架无非三区模型、分支模型和远程协作。真正常用的命令也就二三十条，剩下的是遇到问题再查。把命令行练熟，再回到 IDEA、VS Code 里用可视化界面，你会发现自己能看懂每一步在干什么，界面上那些按钮也不再是“凭感觉点”。如果你正在带新人，建议把这篇文章里列出的常用命令和报错表直接丢给他，让他照着过一遍，比答疑到口干有效得多。