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 --versionmacOS 上有 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.autocrlfWindows 和 Linux/macOS 的换行符不一样这个配置用于把回车符自动转换掉避免出现“明明没改文件git diff却显示整段变化”的经典乌龙。Windows 上建议设置为trueMac/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 格式长这样gitgitee.com:用户名/仓库名.git回到本地终端git init git remote add origin gitgitee.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 密钥并配置到 GiteeGitee 支持 HTTPS 和 SSH 两种协议。公开仓库用 HTTPS 拉代码没问题但推送时光输密码就够烦的私有仓库更是每次都要验证。SSH 的好处是配置一次之后就能免密推送。很多新人第一次遇到“SSH 认证失败”就是卡在这里。生成密钥推荐用ed25519比老式的 RSA 更短更安全。如果你的服务器或 Git 版本较旧再退回 RSA 4096ssh-keygen -t ed25519 -C your_emailexample.com # 兼容性方案 ssh-keygen -t rsa -b 4096 -C your_emailexample.com执行后一路回车默认会在~/.ssh目录生成一对密钥id_ed25519是私钥id_ed25519.pub是公钥。私钥绝对不能外传公钥可以随意分享。用cat ~/.ssh/id_ed25519.pub查看并复制公钥内容然后登录 Gitee进入【设置】→【安全设置】→【SSH 公钥】粘贴保存。保存后用下面命令验证ssh -T gitgitee.com看到提示Hi 你的昵称! ...就代表通了。首次连接时终端会问是否信任主机输入yes即可这是正常的安全确认不是报错。注意如果你本机配置了多个 SSH key比如公司 GitLab 和个人 Gitee 混用别把 key 全放在默认位置然后互相覆盖。建议在~/.ssh/config里按域名区分指定各自使用哪个私钥避免“权限被拒”的诡异问题。2.2 关联远程仓库查看、添加、修改地址Gitee 仓库创建好之后本地仓库需要知道“远程是谁”这就是remote管理命令的用处。# 添加远程仓库 git remote add origin gitgitee.com:用户名/仓库名.git # 查看已有远程 git remote -v # 修改远程地址 git remote set-url origin gitgitee.com:用户名/新仓库名.git # 删除远程关联 git remote remove origingit remote -v会显示你要 push 和 fetch 的两个地址平时多看一眼能避免推送到了错误仓库。两种协议的选择我整理成了一张表协议地址示例优点缺点HTTPShttps://gitee.com/用户/仓库.git免配置任何机器都能直接用推送需输用户名密码部分场景还要验证码SSHgitgitee.com:用户/仓库.git配置后免密推送更安全首次配置密钥有门槛如果在公司内网或代理环境HTTPS 遇到证书问题会比 SSH 多这种环境下 SSH 反而更省心。2.3 从 Gitee 拉取项目到本地命令行、IDEA、VS Code 三种姿势拉取项目最基础的方式是git clone一条命令把远程仓库完整复制到本地git clone gitgitee.com:用户名/仓库名.git # 拉取指定分支 git clone -b develop gitgitee.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 与 LFS3.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修 bugdocs改文档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 LFSLarge 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 的最新提交之上历史变成一条直线非常清爽。操作历史形状典型场景merge保留分叉与合并点公共分支整合、保留完整开发脉络rebase线性整洁个人分支整理、推送前同步远端最新代码日常团队协作我习惯这样做个人开发分支上使用 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/stash5.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 mainpull --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~1git 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 开源许可证怎么选别再闭眼选 MITGitee 新建仓库时会让你填“开源许可证”默认可能是不选。一般人直接选 MIT其实不同许可证的约束差异非常大直接决定别人能不能把你的代码用在商业项目里。许可证核心要求适合场景MIT保留版权声明允许商用、闭源、修改通用库、框架、小工具Apache-2.0保留声明明确专利授权允许商用闭源大公司、项目、关注专利风险GPL-3.0衍生作品必须同协议开源希望强制开源生态的软件MPL-2.0修改过的文件需开源其他部分可以闭源混合型代码库选许可证的标准其实很简单你只是想让人随便用选 MIT你希望用的人别把你的代码改成闭源商业版选 GPL你所在公司有法务要求选 Apache-2.0。个人小项目、学习仓库提前选 MIT 最省事。6.3 仓库能不能包含子项目用 Submodule 别用复制粘贴“Gitee 创建的仓库能包含子项目吗”这个问题答案是能但不要把另一个仓库直接复制进去。正确做法是使用 Git Submodule在父仓库里记录一个指向外部仓库提交号的引用。# 添加子模块 git submodule add gitgitee.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 --grepfeat # 最近 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 常见报错与现象速查表把高频问题整理成表遇到直接查报错或现象根因解决思路Permission denied (publickey)本地没有匹配的 SSH 私钥或公钥未上传 Gitee检查~/.ssh重新生成密钥并上传公钥Host key verification failed主机指纹未知或变更基于安全确认后更新known_hosts文件! [rejected] (non-fast-forward)本地不是远程最新git pull --rebase后再 push严禁随意--forceunable to access ... SSL网络代理、证书或访问限制检查网络环境必要时更新 Git 或按环境配置代理中文文件名乱码Windows/Linux 编码与core.quotepath差异配置git config --global core.quotepath falserefusing to merge unrelated histories两个仓库没有共同提交历史确认无误后使用git pull --allow-unrelated-historiesYour branch is behind ...本地落后远程git fetch后合并或git pull这张表是我被问得最多的内容实战汇总。真遇到不确定的报错第一步永远是git status看当前状态第二步看报错全文找关键短语第三步再去搜索引擎效率远高于无头绪乱试。这份速查写到这我自己最有体会的一点是Git 的命令根本背不完但核心骨架无非三区模型、分支模型和远程协作。真正常用的命令也就二三十条剩下的是遇到问题再查。把命令行练熟再回到 IDEA、VS Code 里用可视化界面你会发现自己能看懂每一步在干什么界面上那些按钮也不再是“凭感觉点”。如果你正在带新人建议把这篇文章里列出的常用命令和报错表直接丢给他让他照着过一遍比答疑到口干有效得多。