初始化一个 Git 仓库再把自己的项目完整地保存进去——这套操作我前前后后做过的次数早就数不清了带过的新人也不少。说实话很多人卡住的不是git init这一条命令而是后面跟着的一连串连锁问题Git 装好了不知道全局身份怎么配、第一次提交把node_modules和target目录一股脑推上去、想上传到 Gitee 却报 SSH 认证失败、分支乱了不知道怎么合并。这篇文章就把“初始化 Git 仓库并保存项目”这条完整链路拆开讲透从环境安装、全局配置、git init 的三种形态到第一次提交、关联远程仓库最后是高频故障的排查实录。无论你是刚摸 Git 的新手还是用了挺久但一直没系统梳理过的开发者应该都能从里面拿到一些可以直接照做的内容。1. 初始化前的准备环境安装与全局身份配置动手git init之前有两件事必须先做对否则后面全是坑。第一是 Git 本体装好且能正常使用第二是全局身份配好。这两件事看起来基础实际出问题的人最多。1.1 Git 安装三个平台的差异与验证Windows 上我推荐直接装 Git for Windows下载安装包一路 Next 就行。需要注意安装向导里的 PATH 环境变量选项建议选“Git from the command line and also from 3rd-party software”这样不仅 Git Bash 能用CMD 和 PowerShell 里也能直接敲git命令。装完打开 Git Bash输入git --version能看到版本号说明环境没问题。macOS 系统自带的 Git 版本往往偏旧某些老版本对 SSH 密钥格式、分支行为的支持有差异保险起见用 Homebrew 装一份新的brew install gitLinux 上 Debian/Ubuntu 系用sudo apt install gitCentOS/RHEL 系用sudo yum install git。装完之后统一验证一下版本。我在实际工作中见过不少同事在 Windows 上坚持用 CMD 操作 Git结果遇到中文乱码、路径转义、shell 脚本没法跑的问题。Git Bash 本质上是一个模拟 Linux 环境的终端很多 Git 相关的命令和脚本都是按 bash 的习惯写的用它能省掉大量莫名其妙的麻烦。这是我要强调的第一个实操点Windows 环境下尽量使用 Git Bash 而不是 CMD。1.2 全局身份配置为什么必须最先做安装完 Git第一件事就是设置身份git config --global user.name 你的名字 git config --global user.email 你的邮箱这两条配置会写进用户目录下的.gitconfig文件之后的每一次提交都会记录这个身份信息。有人会问我就一个人开发不配行不行不行。Git 提交记录里的 author 字段是空的远程仓库平台无法识别提交人后续想要追溯问题、关联账号都会很麻烦。更现实的是Gitee、GitHub 这类平台都要求提交邮箱必须和账号邮箱匹配否则提交虽然能推上去但不会显示你的头像也不会计入贡献记录。Git 的配置有三个层级system是机器级global是当前用户级local是当前仓库级。优先级从高到低是 local global system。用git config --list可以查看当前所有生效的配置。我在公司里会让新人统一用 local 层级配公司邮箱global 留个人邮箱避免提交身份混用。个人项目里直接用 global 就足够了不用过度设计。1.3 SSH 密钥生成与认证一次搞定要把项目保存到远程仓库主流方式有两种HTTPS 和 SSH。HTTPS 每次推送都要输账号密码虽然可以配置凭据缓存但团队协作或者频繁推送时体验很差。SSH 配置一次之后长期免密是更推荐的方式。生成密钥的命令ssh-keygen -t ed25519 -C 你的邮箱一路回车会生成一对密钥私钥~/.ssh/id_ed25519公钥~/.ssh/id_ed25519.pub。选 ed25519 而不是传统 rsa 的原因很简单它的密钥更短、生成更快、安全性在当前标准下已经被广泛接受rsa 4096 虽然也能用但属于“能用但没必要”的旧方案只有在需要兼容老服务器时才改用-t rsa -b 4096。然后把公钥内容复制到 Gitee 或 GitHub 的设置页面里的 SSH Keys 区域。验证是否配置成功ssh -T gitgitee.com # 返回欢迎信息即为成功 ssh -T gitgithub.com我第一次配 SSH 时踩过坑在 Windows 下直接打开 CMD 执行ssh-keygen生成的密钥路径和我预期的不一致折腾半天才发现是 CMD 的当前用户目录和 Git Bash 的 HOME 概念不一样。所以生成密钥这步我建议在 Git Bash 里做路径最省心。还有一个高频场景是同一台机器上有多套账号比如公司 Gitee 和个人 GitHub 都要用。只有一个默认私钥会导致认证串号解决办法是在~/.ssh/config里按 host 指定不同的私钥文件。这一步的具体写法我在后面的排查章节会详细说。2. git init 的完整拆解三种形态怎么选git init是在当前目录创建一个全新的 Git 仓库。这句话说起来简单但它背后其实有好几种形态选错了后面会很难受。2.1 标准仓库日常开发的不二选择在项目根目录执行git init操作成功后目录下会多出一个.git文件夹里面包含 config、HEAD、objects、refs 等文件。这一步的本质是Git 开始对这个目录下的文件进行版本追踪但此刻还没有任何提交。你可以把这个过程类比成给一块新的移动硬盘做格式化——目录还是那个目录但底层的管理机制已经完全变了。标准仓库带有一个工作区你可以正常编辑文件、增删内容Git 会在后台记录这些变化。日常开发几乎都用这种形态不需要想太多。但我要多提醒一句git init之前先确认目录里没有乱七八糟的临时文件。因为初始化之后这些文件都会被 Git 纳入追踪范围除非你写了.gitignore。我见过有人直接在下载目录里执行 init结果把一堆压缩包、安装程序全推到了仓库里。正确做法是在一个干净的、专门的项目目录里执行。我的习惯是每个项目一个独立文件夹文件夹名字就是项目名路径清晰后续 clone、push 都不容易出错。2.2 裸仓库服务端专用形态git init --bare创建的是裸仓库。它没有工作区里面只有 Git 的内部数据文件相当于一个只存储版本历史、不参与实际开发的仓库。裸仓库最常见的用途有两个一是作为团队共享的中央仓库大家统一往这个仓库推送代码二是作为自建的备份仓库。我帮朋友搭过小团队的内网 Git 服务用的就是裸仓库配合一个简单的服务端目录。流程大概是在服务器上执行git init --bare project.git本地git clone这个地址之后正常 push。在没有外部代码托管平台的环境里这是最轻量的团队协作方案也适合放在 NAS 上做自己的代码备份。2.3 初始分支名main 还是 master老版本 Git 初始化后默认分支叫 master近些年社区和主流托管平台统一改用 main。如果你用的是新版 Gitgit init的默认分支取决于你的配置可能是 master 也可能是 main。想要明确指定git init -b main为什么在意这件事因为 Gitee、GitHub 新建仓库时默认分支通常叫 main本地如果初始化出来是 master推送时要先把本地分支改名或者用git push -u origin master:main这种麻烦的映射方式。与其事后折腾不如初始化时直接-b main。如果你是老仓库已经是 master 分支改名也很简单git branch -m main顺便看一眼初始化后的目录结构.git/HEAD文件里写着当前分支指向的引用.git/config里是仓库级配置.git/objects是对象存储。这些东西知道一下就行不用背但理解它们能帮你排查“这个仓库怎么怪怪的”这类问题。比如有次我遇到仓库明明存在但 Git 不认一看就是.git目录被人手动改坏了。3. 第一次提交从工作区到版本库初始化完成只是万里长征第一步“保存项目”真正的核心是提交commit。一套完整的提交流程是工作区修改 → 暂存区 → 版本库。3.1 三个区域的关系与正确操作顺序我用一个快递发货的类比来解释工作区是你的货仓里面堆着所有货物项目文件。暂存区是打包台你把要发的货挑出来放在这里git add。版本库是快递公司的仓储系统货物一旦入库就有据可查、可以回溯git commit。git add . # 把当前目录所有变动放入暂存区 git status # 查看工作区和暂存区状态 git commit -m feat: 初始化项目结构git add .是新手最常用的命令但我不建议无脑使用。正确习惯是git add指定文件或目录比如git add src/ pom.xml这样提交粒度更清晰。等你对项目结构足够熟悉了再考虑用git add .的便捷性。我经常跟新人强调提交之前一定先跑一遍git status看清楚暂存区里到底放了什么。这个习惯能避免很多尴尬现场——比如不小心把包含密码的配置文件提交了。3.2 提交信息怎么写得让人看得懂git commit -m后面的信息不是随便敲的。好的提交信息是项目的历史说明书三个月后你回来看提交记录要能一眼看出这次改动做了什么。我推荐 Conventional Commits 的简化版就是给提交信息加一个语义化前缀前缀适用场景示例feat:新增功能feat: 增加用户注册接口fix:修复缺陷fix: 修复登录超时问题docs:文档调整docs: 更新部署说明refactor:重构代码refactor: 抽取公共工具类chore:杂项维护chore: 升级依赖版本比如feat: 新增用户登录接口就比update有信息量得多。还有一点提交要尽量原子化一次提交只做一个逻辑上的变更。不要一个提交里既改 bug 又加功能还重构代码那样出了问题没法单独回滚团队 review 也难受。这是我在代码评审里最常提的一条。3.3 .gitignore哪些文件不该进仓库保存项目之前必须想清楚哪些文件不该被保存。以 Java 项目为例target/目录是编译产物本地随时可以重新生成没必要进仓库IDE 的.idea/目录保存的是个人配置进了仓库反而会污染别人的开发环境。Node 项目要忽略node_modules/Python 项目要忽略__pycache__/和虚拟环境目录。在项目根目录创建一个.gitignore文件写规则target/ .idea/ *.iml node_modules/ __pycache__/ *.log .env这里有一个非常经典的坑如果某个文件已经被提交到仓库之后你再往.gitignore里加规则是不生效的。因为 Git 已经在追踪这个文件了ignore 只对未被追踪的文件起作用。处理办法是用git rm --cached把文件从版本库里移除但保留本地文件git rm -r --cached target/ git commit -m chore: 移除误提交的编译产物这个操作我每次接手别人的项目几乎都会做一遍太常见了。很多开源项目的提交记录里都能看到这一类 chore 提交本质上都是在为当初的误提交善后。4. 保存到远程仓库Gitee 实战与分支合并本地提交只能算“保存了一半”。真正意义上的“保存项目”一定要有远程仓库做备份这样换电脑、组员协作都不是问题。国内场景我最常用 GiteeGitHub 作为备选方案也顺手提一下。4.1 创建远程仓库的几个细节在 Gitee 上新建仓库时几个选项值得注意。仓库名和路径建议和项目名保持一致方便记忆。私有还是公开按需求选初学者建议先选私有推代码时心理负担小改公开随时可以。初始化仓库那一栏一般有三个可勾选项README、.gitignore、开源许可。我的建议是全部不要勾选。为什么如果远程仓库初始化时生成了 README 或 .gitignore而本地仓库已经有了提交两边历史没有共同祖先推送时 Git 会判定为冲突报 non-fast-forward 错误。虽然可以用--allow-unrelated-histories强制合并但纯粹是给自己添麻烦。最省心的方式是远程仓库保持完全空白创建好之后直接本地 push远程会自动接收本地历史。4.2 关联远程地址并完成首次推送git remote add origin gitgitee.com:用户名/仓库名.git git branch -M main # 确认本地分支名为 main git push -u origin main这里origin是远程仓库的别名理论上可以随便叫但业界默认叫 origin别特立独行。-u参数会把本地分支和远程分支的追踪关系记录下来之后直接git push就可以不用每次带参数。推送成功之后远程仓库页面就能看到你的代码这时候才算真正完成了“保存项目”。之后每次修改的固定节奏是git add→git commit→git push。这是单人开发的基本节奏。如果是已经存在的远程仓库比如团队项目就不需要 remote add 了直接 clonegit clone gitgitee.com:用户名/仓库名.gitclone 下来之后仓库的 remote 配置是自动带上的直接开始干活即可。注意 clone 出来的默认分支就是远程的 HEAD 分支通常是 main。4.3 分支合并从保存到团队协作“保存项目”如果只是一个人在 main 分支上推来推去Git 的价值只发挥了一半。分支的本质是并行空间你在 feature 分支上改代码不影响主干改完再合并回去。git checkout -b feature/login # 创建并切换到新分支 # ... 开发、提交 ... git checkout main # 切回主分支 git merge feature/login # 合并功能分支合并时最头疼的是冲突。冲突的本质是两个分支在同一个文件的同一个位置做了不同修改Git 不知道听谁的。解决办法是打开冲突文件Git 会在冲突区域打上标记 HEAD 主分支上的内容 功能分支上的内容 feature/login把不需要的部分删掉保留正确内容然后git addgit commit完成合并。我在团队里强调过很多次合并之前先git pull同步远程最新的代码能显著减少冲突。别攒了一周的代码闷头一推十有八九要处理一堆冲突。5. 常见问题与排查技巧实录这一章是我认为整篇文章最值得收藏的部分。以下问题都是我在实际工作和带新人时反复遇到的每个都给出排查思路和解决步骤。5.1 SSH 认证失败Permission denied (publickey)这是新手遇到最多的问题报错长这样gitgitee.com: Permission denied (publickey).排查步骤按顺序来确认本地有密钥文件ls ~/.ssh/看有没有id_ed25519和id_ed25519.pub。确认公钥已添加到平台登录 Gitee进入设置 → SSH 公钥粘贴.pub文件内容。确认 ssh-agent 正在运行且加载了私钥eval $(ssh-agent -s) ssh-add ~/.ssh/id_ed25519测试认证ssh -T gitgitee.com。有一次我帮同事排查折腾半天发现是电脑上有两个密钥文件Git 默认用了旧的那个 id_rsa而平台里贴的是新生成的 ed25519 公钥。多账号、多密钥场景下直接在~/.ssh/config里指定最稳妥Host gitee.com HostName gitee.com User git IdentityFile ~/.ssh/id_ed25519_gitee还可以在里面继续加 GitHub 的配置段落指定另一把私钥互不干扰。这个文件配置好之后ssh -T测试会自动选对应密钥基本不会再出现串号问题。5.2 推送被拒绝non-fast-forward报错信息通常包含failed to push some refs和non-fast-forward。意思是远程分支上有本地没有的提交Git 拒绝覆盖别人的历史。处理方式git pull --rebase origin main # 解决可能出现的冲突 git push origin main用--rebase而不是默认的git pullmerge是为了保持提交历史是一条直线而不是出现一堆 merge commit 分叉。我个人的习惯是团队协作时统一用 rebase 拉取只有合并分支时才用 merge历史会清爽很多。当然这属于团队约定没有绝对优劣但一定要达成统一。5.3 提交错了或误删文件reset 与 reflog先说误删文件的情况。还没提交时误删了工作区文件git checkout -- 文件名这个命令会用版本库里的内容恢复工作区文件非常救命。如果是 commit 提交错了想回滚git reset有三种模式模式暂存区工作区适用场景--soft保留保留撤销提交但保留所有改动--mixed默认清空保留撤销提交和暂存工作区不动--hard清空清空彻底回滚到指定提交硬重置有风险我一般会提醒一句执行--hard之前先确认工作区没有未提交的重要修改否则文件直接蒸发。还有一种更安全的方法是git revert HEAD它会生成一个反向提交来抵消错误提交适合已经推送到远程的场合因为不会改写历史。万一 reset 之后发现回滚错了还有最后的救命稻草git reflog。reflog 记录了 HEAD 的所有历史移动包括被撤销的提交。执行git reflog找到目标提交的 hash然后git reset --hard hash就能找回来。我靠这招救回过不小心删掉的分支直到现在还记得当时的心情。5.4 历史里误提交了大文件随着项目发展偶尔会误提交一个巨大的文件比如几百 MB 的视频或安装包导致每次 push 都异常痛苦。彻底清除这种文件需要用git filter-repo它会重写整个提交历史属于高风险操作执行前一定要完整备份仓库目录。如果是单人项目且远程还没有被影响最简单的办法是把大文件从工作区移走提交一次后续推送不再受影响。历史里的大文件虽然还占着仓库体积但至少不会让每天的操作卡死。等哪天真的需要瘦身了再花时间研究 filter-repo。5.5 高频报错速查表最后整理一张速查表遇到问题先对照一下报错信息可能原因快速处理Permission denied (publickey)SSH 公钥未配置或密钥未被加载按 5.1 的顺序排查failed to push some refs远程有本地没有的提交git pull --rebase 后重推fatal: Not a git repository当前目录不在仓库内检查目录是否存在 .gitUpdates were rejected because the remote contains work远程历史与本地分叉同上先 pull 再 pushRPC failed; HTTP 413 curl 22推送内容过大检查是否误提交大文件这张表是我带新人时的入门清单覆盖了最常见的七八成问题。剩下的问题基本都能通过git log、git status、git remote -v三连定位到方向。6. 实操心得把“保存项目”变成习惯最后分享几点我在实际工作中沉淀下来的操作习惯不深奥但都是踩过坑换来的。第一提交频率要高提交粒度要小。宁可一个下午提交十次不要一天结束憋一个大提交。小提交的回滚成本低review 也方便。我给团队定的习惯是完成一个功能点就提交版本可用就打 tag。第二推送之前永远先看git status和git log。status 看的是有什么将变log 看的是将要推什么。这两条命令加起来十秒钟的事能避免把调试代码、临时日志推上远程的尴尬。第三每到一个里程碑比如版本发布、功能完成记得打一个 tag。git tag v1.0.0之后你的项目就有了一个不可变的历史坐标随时可以通过这个 tag 找回当时的完整代码。这个习惯在你需要复盘线上问题时价值极大。第四Git 的底层原理不用精通但 HEAD、分支、远程追踪这几个概念必须想明白。很多人学 Git 只记住命令换个场景就不会了就是因为没搞懂这三个东西的关系。建议你在本地多建几个测试仓库随便瞎玩玩坏了用 reflog 重来比看一百篇教程都管用。我个人从最早敲git init时的懵懂到后来在大项目里面对上百个分支和无数次合并最大的体会是Git 不是一个需要背命令的工具而是一套需要建立心智模型的工作方式。把“初始化仓库并保存项目”这件事从一条命令变成一套流程不管是个人项目还是团队协作代码的安全感和可控性都会明显上一个台阶。