1. 从本地到云端：为什么我们需要一个代码仓库？

如果你刚开始接触编程，或者在一个小团队里单打独斗，可能会觉得代码仓库是个“可有可无”的东西。代码不就在自己电脑上吗？改完直接运行，一切正常，为什么还要费劲上传到一个叫Gitee的网站上？我刚开始写代码的时候也是这么想的，直到有一次，我的硬盘突然罢工，过去三个月写的项目代码，连同那些灵光一现的注释和没来得及提交的调试版本，瞬间化为乌有。那种感觉，就像建筑师看着自己刚画好的蓝图被一把火烧了，而且还没留底稿。

这就是代码仓库最基础、也最重要的价值：备份与版本管理。Gitee，你可以把它理解为一个专为代码设计的、永不丢失的“云端硬盘”。但它的功能远不止备份。想象一下，你和同事要共同修改一份合同。如果你们各自在本地电脑上修改，然后通过微信传来传去，很快就会出现“合同_v1_final_真的最终版_张三改.docx”这种混乱的局面。代码仓库，特别是像Gitee这样基于Git的仓库，就是为了解决这种协作混乱而生的。它能清晰地记录下“谁、在什么时候、修改了哪一行代码、为什么修改”，并且允许你们在各自的分支上并行工作，最后再优雅地合并到一起。

对于个人开发者，Gitee是一个绝佳的作品集和知识管理工具。你写的每一个工具脚本、每一个学习项目，都可以有条不紊地放在上面。哪天你需要回顾某个功能的实现，或者向潜在雇主展示你的代码能力，一个整洁的Gitee主页比任何简历描述都更有说服力。而且，通过Gitee Pages功能，你甚至可以直接将仓库里的网页代码部署成一个静态网站，用于展示个人博客或项目文档，这比租用服务器要简单和便宜得多。

所以，无论你是想保护自己的劳动成果，还是准备开启团队协作，亦或是打造个人技术品牌，学会使用Gitee上传和管理代码，都是现代开发者的一项必备技能。这不仅仅是点几下按钮，而是建立起一套安全、高效、可追溯的代码工作流。

2. 上传第一步：在Gitee安家落户与本地初始化

在把代码推送到云端之前，我们需要在两端做好准备：一是在Gitee上创建一个空的“房子”（远程仓库），二是在本地电脑上准备好要搬家的“行李”（本地Git仓库），并告诉它们彼此的地址。

2.1 在Gitee创建你的第一个仓库

登录Gitee后，点击页面右上角的 “+” 号，选择 “新建仓库”。这个步骤虽然简单，但有几个关键选项决定了仓库的初始状态，值得仔细斟酌：

1. 仓库名称：尽量用英文，使用短横线-连接单词，例如my-first-project。这符合通用惯例，也便于在命令行中操作。

2. 路径：通常会自动填充为与仓库名一致，可以保持不变。

3. 介绍：用一两句话说明这个仓库是做什么的。一个好的介绍能让访客（包括未来的你）快速了解项目价值。

4. 开源许可证：项目的“法律说明书”

   这是新手最容易忽略，但也极其重要的一环。Gitee提供了多种开源许可证模板。简单来说：

   • MIT许可证：最宽松的一种。只要使用者在你代码的副本中包含原许可证和版权声明，他们可以拿你的代码做任何事，包括用于闭源商业项目。适合希望代码被广泛使用的库或工具。
   • GPL系列（如GPL-3.0）：具有“传染性”。任何使用了你代码的项目，如果分发其二进制文件，也必须开源其全部源代码。适合坚持开源精神的完整项目。
   • Apache-2.0：类似MIT，但额外提供了明确的专利授权，对贡献者和使用者都提供了更好的法律保护，大型项目常用。对于个人学习项目或希望快速传播的小工具，选择 MIT 许可证是一个简单又安全的选择。如果你暂时不确定，也可以先选择“不设置许可证”，但这意味着你保留所有权利，他人无法在法律框架下使用你的代码。

5. 初始化设置：这里我强烈建议保持所有选项为空（不勾选“使用Readme文件初始化”、“设置模板文件”、“设置.gitignore”）。为什么？因为我们要练习从零开始、最标准的手动上传流程。很多上传失败的问题，都源于远程仓库已经存在了初始文件（如README.md），而本地仓库没有，导致版本历史冲突。我们从一张白纸开始，能避开这个坑。

点击“创建”后，一个空的远程仓库就诞生了。页面会跳转到仓库主页，这里最重要的是找到仓库的“地址”。通常有两种：

• HTTPS地址：形如https://gitee.com/your-username/your-repo-name.git。使用方便，但每次推送可能需要输入Gitee账号密码。
• SSH地址：形如git@gitee.com:your-username/your-repo-name.git。需要先配置SSH密钥，但配置好后无需每次输入密码，更安全便捷。对于长期项目，推荐使用SSH方式。

2.2 在本地建立Git基地并关联远程

现在，打开你的命令行工具（Windows的CMD/PowerShell， Mac/Linux的Terminal），进入你的项目文件夹。

第一步：初始化本地Git仓库

cd /path/to/your/project git init

执行git init后，当前目录下会生成一个隐藏的.git文件夹，这就是本地Git仓库的所有管理数据所在。此时，你的项目文件还处于“未跟踪”状态。

第二步：进行第一次本地提交我们需要把当前的项目文件快照保存到本地仓库的历史记录中。

git add .

这个命令将当前目录下所有新增和修改的文件添加到“暂存区”。git add .是一个便捷操作，但有时我们只想添加特定文件，可以用git add filename。如果想确认哪些文件将被添加，可以先运行git status查看状态。

git commit -m "first commit: project initialization"

git commit命令将暂存区的内容创建一个永久的快照，保存到本地仓库。-m后面的字符串是本次提交的说明信息，务必认真填写。好的提交信息像日记，能让你半年后一眼看懂这次改动做了什么。模糊的信息如“update”或“fix bug”毫无价值。

第三步：关联远程仓库并推送现在，告诉本地仓库，它的远程“家”在哪里。将下面命令中的远程地址替换成你刚创建的Gitee仓库的SSH或HTTPS地址。

git remote add origin https://gitee.com/your-username/your-repo-name.git # 或者 # git remote add origin git@gitee.com:your-username/your-repo-name.git

origin是给这个远程仓库起的一个别名，习惯上用于指代主远程仓库。

最后，将本地仓库的“master”或“main”分支推送到远程仓库的“origin”：

git push -u origin master # 如果你的默认分支名是 main，则用： # git push -u origin main

-u参数是--set-upstream的简写，它建立了本地当前分支与远程指定分支的追踪关系。设置好后，下次在这个分支上只需输入git push即可。

注意：如果你在Gitee创建仓库时初始化了README等文件，而本地仓库是空的，直接git push会失败，提示“非快进式更新”。这时你需要先执行git pull origin master --allow-unrelated-histories将远程历史拉取合并到本地，解决冲突后再推送。这就是为什么我建议从空仓库开始。

至此，你的代码已经成功上传至Gitee。刷新仓库页面，就能看到所有文件了。

3. 日常更新：提交更改与解决冲突的标准化流程

项目不是一蹴而就的，我们每天都会修改代码、添加功能、修复Bug。如何将这些持续的更新安全地同步到Gitee仓库？这需要遵循一个清晰的流程，我称之为“本地工作流三部曲”：修改 -> 暂存 -> 提交。而团队协作时，则需额外注意“拉取 -> 解决冲突 -> 推送”。

3.1 单人项目：标准更新操作

假设你独自开发，已经完成了上一章的首次推送。现在你修改了index.html文件，并新增了一个style.css文件。

1. 查看状态：在提交前，养成先看状态的好习惯。

   git status

   命令行会显示哪些文件被修改了（红色），哪些文件是新添加的（红色），以及哪些文件已经暂存（绿色）。

2. 暂存更改：将你想要纳入本次提交的改动添加到暂存区。你可以添加所有改动，也可以选择性添加。

   git add . # 添加所有改动 # 或 git add index.html # 只添加特定文件 git add style.css

3. 提交到本地历史：为本次改动创建一个快照。

   git commit -m "feat: add homepage structure and basic styles"

   我使用了“feat:”前缀，这是一种约定俗成的提交信息规范（如Conventional Commits），有助于生成清晰的更新日志。其他常见前缀有fix:（修复Bug）、docs:（文档更新）、style:（代码格式调整）等。

4. 推送到远程仓库：将本地提交同步到Gitee。

   git push

   因为首次推送时用了-u建立了关联，这里直接git push即可。

3.2 团队协作：拉取、冲突与合并

在多人协作中，你的同事可能在你上次拉取代码后，也向同一个分支（如master）推送了他们的提交。如果你直接修改然后git push，很可能会被拒绝，因为你的本地历史已经“落后”于远程历史。

1. 开始工作前，先拉取最新代码：

   git pull origin master

   这个命令相当于git fetch（获取远程最新数据） +git merge（将远程数据合并到本地当前分支）。这是保持本地代码与团队同步的基础操作。

2. 遭遇冲突：冷静分析与解决如果你和同事修改了同一文件的同一区域，Git无法自动决定保留谁的修改，就会产生“冲突”。执行git pull后，你会看到类似这样的提示：

   Auto-merging index.html CONFLICT (content): Merge conflict in index.html Automatic merge failed; fix conflicts and then commit the result.

   此时，用编辑器打开index.html，你会看到Git标记出的冲突区块：

   <<<<<<< HEAD <h1>这是我本地修改的标题</h1> ======= <h1>这是同事远程修改的标题</h1> >>>>>>> commit-id-from-remote

   • <<<<<<< HEAD到=======之间是你的本地修改。
   • =======到>>>>>>>之间是远程拉取下来的修改。你的任务就是手动编辑这个文件，决定最终保留的内容，并删除所有这些标记行。例如，你可能决定采用同事的标题，但保留你的样式，那么就把文件改成你想要的样子。

3. 解决冲突后，完成合并提交： 解决完所有冲突文件后，你需要告诉Git冲突已经解决。

   git add index.html # 将解决完冲突的文件重新暂存 git commit -m "merge: resolve conflict in index.html"

   Git会自动为你生成一个合并提交的信息，你也可以修改它。

4. 推送合并后的结果：

   git push

   现在，你的本地修改和同事的修改已经完美融合，并推送到了远程仓库。

实操心得：为了避免频繁解决令人头疼的冲突，一个黄金法则是：在开始一天的工作或开始一个新功能前，先git pull更新本地代码。此外，对于复杂功能，尽量使用“分支”进行开发，完成后通过“Pull Request”合并到主分支，这能极大地隔离不同开发者的工作，减少主分支的冲突概率。我们会在下一章详细讨论分支策略。

4. 进阶管理：分支策略、忽略文件与图形化工具

掌握了基本的推送和拉取，你已经能应对大部分个人项目了。但要更高效、更专业地管理项目，尤其是参与团队协作，还需要掌握几个关键的高级概念和工具。

4.1 使用分支：让开发并行不悖

分支是Git的“杀手级”功能。它允许你从主线（如master）上创建一个完全独立的副本，在这个副本上任意实验、开发新功能或修复Bug，而不会影响主线代码的稳定性。完成后，再将其合并回去。

• 查看所有分支：git branch（当前分支前会标有*号）
• 创建新分支：git branch feature-login（创建一个名为feature-login的分支）
• 切换到新分支：git checkout feature-login或使用更现代的git switch feature-login
• 创建并切换分支（快捷方式）：git checkout -b feature-login

一个实用的工作流示例：

1. 你接到一个开发登录页面的任务。首先，确保你在主分支并拉取最新代码。

   git checkout master git pull origin master

2. 基于最新的master创建一个功能分支。

   git checkout -b feature-user-login

3. 在这个分支上安心开发，进行多次git add和git commit。
4. 开发完成，准备合并。首先，切换回master并再次拉取最新代码（防止在此期间有别人更新）。

   git checkout master git pull origin master

5. 将功能分支合并到master。

   git merge feature-user-login

6. 解决可能出现的合并冲突（如果有的话）。
7. 将合并后的master推送到远程。

   git push origin master

8. （可选）删除已经合并的本地功能分支：git branch -d feature-user-login。

在Gitee上，更团队化的做法是将功能分支推送到远程（git push -u origin feature-user-login），然后在Gitee仓库页面发起一个Pull Request（PR）或合并请求（MR）。这样其他成员可以在网页上审查你的代码变更，讨论通过后再由负责人合并到主分支。这是一种非常高效的代码审查和协作机制。

4.2.gitignore文件：别把“垃圾”上传到仓库

你的项目目录里可能有很多不需要、也不应该纳入版本控制的文件，比如：

• 操作系统自动生成的文件（.DS_Store(Mac),Thumbs.db(Windows)）。
• 运行时文件（如node_modules/,__pycache__/,.class文件）。
• 编辑器配置文件（如.vscode/,.idea/，除非团队统一）。
• 包含敏感信息的文件（如配置文件中的密码、API密钥）。
• 构建产物（如dist/,build/）。

将这些文件上传到仓库会污染提交历史、浪费空间，并可能泄露机密。.gitignore文件就是用来指定哪些文件或目录应该被Git忽略。

如何创建和使用：

1. 在项目根目录创建一个名为.gitignore的文本文件。
2. 在文件中按行写入需要忽略的规则。支持通配符，例如：

   # 忽略所有 .log 文件 *.log # 忽略 node_modules 整个目录 node_modules/ # 忽略所有名为 .env 的文件（常用于存储环境变量） .env # 忽略 build 目录，但不要忽略 build/docs 目录 build/* !build/docs/

3. 将这个.gitignore文件本身添加到Git并提交。

   git add .gitignore git commit -m "chore: add .gitignore file" git push

Gitee在创建仓库时提供的模板功能，其实就是帮你生成一个针对特定语言（如Java、Python、Node.js）的通用.gitignore文件，非常方便。你也可以在 gitignore.io 这类网站生成。

4.3 图形化工具：给命令行加个“方向盘”

虽然命令行是掌握Git的根本，但图形化界面工具（GUI）能直观地展示分支结构、变更历史，简化部分操作，对新手尤其友好。

• VS Code 内置Git工具：如果你使用VS Code，它自带了强大的Git图形界面。左侧活动栏的源代码管理图标（或按 Ctrl+Shift+G）可以可视化地暂存文件、查看差异、提交和推送。安装Gitee插件后，还能直接在VS Code内克隆Gitee仓库、创建PR等。
• Sourcetree：一款免费且功能强大的Git GUI客户端，支持Windows和Mac。它能以非常直观的图谱展示分支和提交历史，进行复杂的合并、变基操作比命令行更清晰。
• GitHub Desktop：虽然名字叫GitHub，但它也完美支持Gitee。界面简洁，非常适合刚入门、想避开命令行的用户完成日常提交、拉取、推送操作。

我的建议是：从命令行开始学习基础命令，理解底层逻辑。在日常工作中，可以结合使用GUI工具来提高效率，特别是查看历史、解决冲突和操作分支时。例如，用命令行进行add,commit,pull,push，用Sourcetree来可视化地管理分支和解决复杂的合并冲突。

5. 故障排除：上传与更新中的常见“坑”与填坑指南

即使流程再熟悉，在实际操作中你也难免会遇到一些错误提示。别慌，大部分问题都有固定的解决思路。下面我整理了几个最常见的问题及其解决方法。

5.1 错误：failed to push some refs与non-fast-forward

这是最经典的错误之一，通常发生在你尝试git push时，但远程仓库已经有了你本地没有的新提交。

错误信息示例：

! [rejected] master -> master (non-fast-forward) error: failed to push some refs to 'https://gitee.com/...' hint: Updates were rejected because the tip of your current branch is behind hint: its remote counterpart. Integrate the remote changes (e.g. hint: 'git pull ...') before pushing again.

原因分析：你的同事先于你推送了代码到远程master分支，导致远程分支的提交历史领先于你的本地分支。Git为了防止你覆盖别人的工作，拒绝了这次推送。

解决方案：

1. 先拉取，再推送：这正是错误提示建议的做法。

   git pull origin master

   这会将远程的更改拉取下来并尝试与你的本地更改合并。
2. 处理可能的合并冲突：如果git pull后自动合并失败（产生冲突），你需要按照第3.2节的方法手动解决冲突，然后git add、git commit完成合并提交。
3. 重新推送：

   git push origin master

   此时，你的本地历史已经包含了远程的最新更改和你自己的更改，推送就会成功。

注意：有时git pull会打开一个编辑器让你填写合并提交的信息，保存并关闭即可。如果你不熟悉vim，可以按i进入编辑模式，写完后按Esc，再输入:wq保存退出。

5.2 错误：support for password authentication was removed

当你使用HTTPS地址推送，并输入密码时，可能会收到此错误。

原因分析：Gitee等平台为了安全，已逐步取消了对账号密码直接认证的支持，推荐使用个人访问令牌（PAT）或SSH密钥。

解决方案（二选一）：

• 方案A：使用个人访问令牌（推荐给HTTPS用户）

  1. 登录Gitee，进入设置 -> 安全设置 -> 私人令牌。
  2. 点击“生成新令牌”，勾选需要的权限（对于推送代码，至少需要projects的写权限）。
  3. 生成后，务必立即复制并保存好令牌，因为它只显示一次。
  4. 下次使用HTTPS推送时，在要求输入密码的地方，直接粘贴这个令牌即可。

• 方案B：改用SSH密钥认证（一劳永逸）

  1. 生成SSH密钥对（如果还没有）：

     ssh-keygen -t ed25519 -C "your_email@example.com"

     一路回车使用默认设置。这会在~/.ssh/目录下生成id_ed25519（私钥，绝不可泄露）和id_ed25519.pub（公钥）。
  2. 将公钥添加到Gitee：复制id_ed25519.pub文件的内容。

     # Mac/Linux cat ~/.ssh/id_ed25519.pub # Windows (PowerShell) type $env:USERPROFILE\.ssh\id_ed25519.pub

     登录Gitee，进入设置 -> SSH公钥，粘贴并添加。
  3. 测试连接：

     ssh -T git@gitee.com

     看到欢迎信息即表示成功。
  4. 修改远程仓库地址为SSH（如果你之前用的是HTTPS）：

     git remote set-url origin git@gitee.com:your-username/your-repo-name.git

     之后再进行git push或git pull就无需输入密码了。

5.3 错误：src refspec master does not match any

这个错误通常发生在第一次推送时。

原因分析：本地仓库没有任何提交（commit），你试图推送一个不存在的分支历史到远程。

解决方案： 确保你已经执行了初始提交。

git add . git commit -m "initial commit"

然后再执行git push -u origin master。

5.4 状态混乱：如何撤销或回退更改？

在提交过程中，难免有手误的时候。Git提供了多种“后悔药”。

• 撤销工作区的修改（未git add）：放弃对某个文件的修改，还原到上次提交的状态。

  git checkout -- filename # 或使用更语义化的命令 git restore filename

• 撤销暂存区的修改（已git add， 未git commit）：将文件从暂存区移回工作区，但保留工作区的修改内容。

  git reset HEAD filename # 或 git restore --staged filename

• 撤销最近一次提交（已git commit， 未git push）：创建一个新的提交来撤销上一次提交的更改，这是一个安全的操作，会保留历史记录。

  git revert HEAD

  执行后会打开编辑器让你确认反转提交的信息，保存退出即可。

• 彻底重置到某个提交（危险！）：git reset命令非常强大，但会改变历史，如果已经推送到了远程，强制推送 (git push -f) 会影响其他协作者，需谨慎使用。

  • git reset --soft HEAD~1：撤销上一次提交，但保留更改在暂存区。
  • git reset --mixed HEAD~1（默认）：撤销上一次提交，且取消暂存，更改保留在工作区。
  • git reset --hard HEAD~1：危险！彻底丢弃上一次提交以及所有工作区的更改，无法恢复。

核心原则：如果更改只存在于你的本地，你可以相对安全地使用reset。如果更改已经push到了共享的远程仓库，为了不破坏团队其他人的历史，请优先使用git revert。