Gitee代码上传全攻略：命令行与图形化工具详解

1. 为什么我们需要一个清晰的代码仓库上传流程？

在任何一个软件项目的生命周期里，代码管理都是最基础也最核心的一环。无论是个人学习、团队协作，还是开源贡献，我们都需要一个可靠的地方来存放、追踪和分享我们的代码。对于国内开发者而言，Gitee（码云）凭借其稳定的访问速度和符合本地习惯的生态，成为了一个非常主流的选择。但很多朋友，尤其是刚入门的新手，在第一次尝试将本地代码“搬”到Gitee仓库时，往往会感到一丝迷茫：我该用哪种方式？命令行看着有点吓人，图形化工具又怕功能不全。其实，这两种方式各有其适用场景和优势，选择哪一种，完全取决于你的工作习惯和项目需求。

今天，我们就来彻底拆解在Gitee上上传代码的两种核心方式：通过Git命令行和通过Gitee官方客户端或第三方Git图形化工具。我不会只告诉你步骤，更会深入分析每种方式背后的逻辑、适合谁用、以及在实际操作中那些容易踩坑的细节。无论你是喜欢在终端里运指如飞的高手，还是偏爱可视化操作的效率派，这篇文章都能帮你建立起清晰、可靠的上传流程，让你和你的代码仓库相处得更加融洽。

2. 基石准备：在一切开始之前，你必须完成的配置

无论你选择哪种上传方式，有一些前置步骤是共通的、必须完成的。跳过这些步骤，后续的所有操作都会像没有地基的房子一样摇摇欲坠。很多人卡在第一步，就是因为忽略了这些看似简单却至关重要的配置。

2.1 注册Gitee账号与创建仓库

这听起来像是废话，但确实是一切的开端。访问Gitee官网，注册一个账号。之后，点击页面上的“+”号或“新建仓库”按钮。在创建仓库的页面，有几个关键选项需要你理解其含义：

• 仓库名称：尽量使用英文和短横线，例如my-awesome-project。这有利于在命令行中操作，也符合通用规范。
• 路径：通常会自动根据仓库名生成，这是仓库在Gitee服务器上的实际访问路径。
• 仓库介绍：用一两句话说明这个项目是做什么的，方便他人和自己日后快速理解。
• 是否开源：选择“公开”或“私有”。公开仓库任何人都可以查看（但未必能修改），适合开源项目；私有仓库则仅对你和指定的协作者可见，适合公司或私人项目。
• 初始化仓库：这里有一个至关重要的选择。Gitee提供了“使用Readme文件初始化这个仓库”、“设置模板文件”等选项。对于新手，或者你打算上传一个已存在的本地项目，我强烈建议这里全部留空，不要勾选任何初始化选项。原因很简单：如果你勾选了“使用Readme文件初始化”，Gitee会帮你生成一个初始的README.md文件并完成第一次提交。这时，这个远程仓库就不再是一个“空仓库”了。当你尝试将本地仓库的内容推送到这个非空仓库时，可能会遇到版本历史冲突，需要额外的合并操作，这对新手极不友好。我们的目标是建立一个干净的、空的远程仓库，然后让本地内容成为它的初始提交。

创建完成后，你会看到仓库的HTTPS或SSH地址，形如https://gitee.com/your-username/your-repo.git或[e-mail]:your-username/your-repo.git。记下它，稍后会用到。

2.2 本地Git环境的安装与基础配置

Git是一个分布式版本控制系统，我们需要先在本地电脑上安装它。

• Windows用户：前往 Git 官网下载安装程序。安装过程中，关于“选择默认编辑器”，如果你不熟悉Vim，建议选择“Use Visual Studio Code as Git‘s default editor”或“Notepad++”。在“调整PATH环境”步骤，选择“Git from the command line and also from 3rd-party software”，这会将Git添加到系统环境变量，让你能在任何地方使用git命令。
• macOS用户：通常可以通过安装Xcode Command Line Tools（在终端运行xcode-select --install）来获取Git。或者使用Homebrew安装：brew install git。
• Linux用户：使用系统包管理器安装，例如Ubuntu/Debian：sudo apt-get install git。

安装完成后，打开终端（Windows上是Git Bash或CMD/PowerShell），进行全局身份配置，这是告诉Git你是谁的关键一步：

git config --global user.name "你的Gitee用户名或常用名" git config --global user.email "你的Gitee账号绑定的邮箱"

这个信息会记录在你每一次的提交记录里，非常重要。你可以通过git config --global --list命令来检查配置是否生效。

2.3 SSH公钥的生成与配置（可选但强烈推荐）

如果你打算使用SSH方式与Gitee通信（地址以[e-mail]:开头），就需要配置SSH密钥。相比于HTTPS每次操作都可能需要输入密码，SSH通过密钥对进行认证，一次配置，长期免密，更加安全便捷。

1. 生成密钥对：在终端运行以下命令，将[e-mail]替换为你的邮箱。

   ssh-keygen -t ed25519 -C "[e-mail]"

   按回车接受默认的密钥保存路径（通常是~/.ssh/id_ed25519），然后设置一个安全的密码（可直接回车留空，但不建议生产环境这么做）。

2. 查看并复制公钥：

   cat ~/.ssh/id_ed25519.pub

   终端会显示一长串以ssh-ed25519开头的内容，完整复制它。

3. 在Gitee中添加公钥：登录Gitee，点击头像 -> 设置 -> SSH公钥。在“添加公钥”页面，将刚才复制的公钥内容粘贴到“公钥”文本框中，标题可以自拟（如“My Laptop”），然后点击“确定”。

4. 测试连接：在终端运行ssh -T [e-mail]。如果看到类似 “Hi XXX! You‘ve successfully authenticated...” 的欢迎信息，说明配置成功。

完成以上所有准备后，我们就可以根据不同的偏好，选择代码上传的路径了。

3. 方式一：使用Git命令行——精准掌控的“手动挡”

对于开发者而言，掌握Git命令行是一项基本功。它就像开车的手动挡，虽然初期学习曲线稍陡，但能让你对整个过程有最精细的控制，理解每一个操作背后的原理，并且在任何环境下（包括没有图形界面的服务器）都能游刃有余。

3.1 场景一：将全新的本地项目首次推送到Gitee

假设你已经在本地电脑上新建了一个项目文件夹my-project，里面有一些代码文件，现在想把它放到Gitee上成为一个新的仓库。

操作流程与原理拆解：

1. 初始化本地Git仓库： 打开终端，进入你的项目目录。

   cd /path/to/your/my-project git init

   这个git init命令会在当前目录下创建一个隐藏的.git文件夹，这是Git用来跟踪管理版本历史的所有元数据所在。此时，你的项目目录就变成了一个Git本地仓库。

2. 将文件添加到暂存区（Staging Area）：

   git add .

   这里的.代表当前目录下的所有文件（除了在.gitignore中声明的）。git add命令的本质，是将工作目录中文件的当前快照添加到暂存区。暂存区是一个中间区域，你可以把它想象成购物车，你把想要这次“提交”的修改先放进去，可以反复添加或移除，直到确认无误。使用git status命令可以随时查看哪些文件已被暂存（绿色），哪些文件有修改但未暂存（红色）。

   实操心得：新手常犯的一个错误是直接git add .把所有文件（包括编译产物、依赖目录node_modules、IDE配置文件等）都加进去。这会导致仓库臃肿且充满垃圾。正确的做法是，先创建一个.gitignore文件，在里面列出所有需要被Git忽略的文件和目录模式。例如对于一个Node.js项目，.gitignore里至少应该有node_modules/和.env。然后再执行git add .。

3. 提交更改到本地仓库：

   git commit -m “Initial commit: project setup”

   git commit命令将暂存区的内容创建一个永久的快照，保存到本地仓库的历史记录中。-m后面跟的是提交信息，务必认真填写。好的提交信息应该简洁明了地说明这次提交的目的，例如“修复了登录接口的空指针异常”比“修改了代码”要有用得多。

4. 关联远程仓库： 现在需要告诉本地仓库，它应该把代码推送到哪里。回到Gitee你创建的空仓库页面，复制它的SSH或HTTPS地址。

   git remote add origin [e-mail]:your-username/your-repo.git

   git remote add命令添加一个远程仓库的别名。这里我们习惯将主要的远程仓库命名为origin。你可以通过git remote -v命令查看已关联的远程仓库地址。

5. 推送本地提交到远程仓库：

   git push -u origin main

   这是最关键的一步。git push命令将本地仓库的提交记录上传到指定的远程仓库。

   • origin：我们刚刚设置的远程仓库别名。
   • main：这是你要推送的本地分支名。现在Git默认的主分支名是main（早年是master）。
   • -u：这是--set-upstream的简写。它建立了本地main分支与远程origin/main分支的追踪关系。设置之后，下次在这个分支上只需要简单地输入git push或git pull，Git就知道应该与哪个远程分支交互。

   执行后，终端会显示推送进度。完成后，刷新你的Gitee仓库页面，就能看到代码已经安然在列了。

3.2 场景二：克隆现有仓库与后续更新

如果你要参与一个已经存在于Gitee上的项目，或者换了一台电脑需要拉取代码，流程则从“克隆”开始。

1. 克隆远程仓库：

   git clone [e-mail]:some-username/existing-repo.git

   这个命令会在当前目录下创建一个以仓库名命名的文件夹（existing-repo），并将远程仓库的整个历史记录和所有分支下载到本地，同时自动设置好远程别名origin。

2. 日常开发循环：进入克隆下来的项目目录，你的日常操作将形成一个固定循环：

   • 修改代码。
   • git add <file>或git add .：将修改添加到暂存区。
   • git commit -m “message”：提交到本地仓库。
   • git push：推送到远程仓库（因为之前克隆时已建立追踪，所以无需再指定参数）。
   • 在推送前，如果担心远程已有他人更新，可以先执行git pull拉取最新更改并合并到本地，解决可能的冲突后再推送。

3.3 命令行方式的优势与核心操作解析

• 优势：

  • 通用性强：在所有操作系统和服务器环境中表现一致。
  • 功能完整：可以执行所有高级Git操作，如交互式变基（rebase -i）、复杂合并、二分查找（bisect）等。
  • 易于自动化：可以写入脚本，实现CI/CD流水线。
  • 加深理解：强迫你理解Git的核心概念（工作区、暂存区、本地仓库、远程仓库）。

• 必须掌握的几个核心命令：

  • git status：查看仓库状态，你的“导航仪”。
  • git log --oneline --graph：以简洁图形化方式查看提交历史。
  • git diff：查看工作区与暂存区的差异；git diff --staged查看暂存区与最新提交的差异。
  • git branch：管理分支。
  • git checkout -b new-feature：创建并切换到一个新分支。

4. 方式二：使用图形化工具——直观高效的“自动挡”

如果你觉得命令行记忆负担重，或者更习惯于可视化操作，那么图形化工具（GUI）是你的绝佳选择。它们将Git命令转化为按钮、菜单和可视化图表，让版本控制变得直观。这里我们主要介绍Gitee官方客户端和一款广受好评的第三方工具——Sourcetree。

4.1 使用Gitee官方客户端

Gitee提供了自己的桌面客户端，它深度集成Gitee平台功能，对中文用户友好。

1. 下载与安装：从Gitee官网下载对应系统的客户端并安装。
2. 登录与克隆：打开客户端，使用Gitee账号登录。你可以通过“克隆”按钮，输入仓库URL，将远程仓库克隆到本地。
3. 仓库管理界面：客户端主界面通常分为几个区域：文件变更列表、提交信息输入框、提交历史图谱。
4. 进行提交：
   • 在工作区修改文件后，客户端会自动检测到“未暂存的文件”。
   • 你可以勾选需要提交的文件（相当于git add），在下方输入提交信息。
   • 点击“提交”按钮，这一步相当于git commit，但提交只发生在本地。
   • 提交后，点击“推送”按钮，将本地提交推送到Gitee远程仓库。
5. 拉取与同步：点击“拉取”按钮可以获取远程更新。客户端通常会将git pull（拉取并合并）的操作封装在一起。

优点：与Gitee无缝集成，方便管理Gitee上的Issue、Pull Request等；界面简洁，上手极快。不足：功能相对基础，对于复杂的分支操作、历史重写等支持较弱。

4.2 使用Sourcetree（第三方强力推荐）

Sourcetree是Atlassian公司出品的免费Git图形化工具，功能非常强大，被誉为“Git GUI神器”。

1. 安装与初始配置：下载安装Sourcetree。首次运行可能会要求你安装附带的Git（如果系统没有的话）。你需要配置用户信息（同命令行配置）。
2. 克隆仓库：点击“克隆”按钮，输入源路径（Gitee仓库SSH/HTTPS地址）和目标路径，即可克隆。
3. 强大的主界面：Sourcetree的界面信息量丰富。
   • 左侧边栏：显示本地和远程分支列表，管理非常方便。
   • 中间文件状态区：清晰展示工作副本文件的状态（未暂存、已暂存、已忽略）。
   • 提交面板：勾选文件、输入信息、进行提交。
   • 底部历史图谱：这是Sourcetree的精华！它以可视化图形的方式展示所有分支和提交的演进历史，合并、分叉一目了然，对于理解项目历史非常有帮助。
4. 进行提交与推送：操作流程与Gitee客户端类似，但可视化反馈更细致。提交后，在顶部工具栏点击“推送”按钮，选择要推送的分支即可。
5. 高级功能：Sourcetree几乎封装了所有常用Git命令。你可以通过右键菜单轻松进行“检出分支”、“合并”、“变基”、“贮藏”等操作。对于解决合并冲突，它也提供了直观的对比合并工具。

优点：功能全面，可视化历史图谱无敌，适合管理复杂的分支策略；既降低了入门门槛，又提供了进阶操作的能力。不足：界面相对复杂，初次使用需要一点时间适应；软件体积较大。

4.3 图形化工具的核心价值与选择建议

图形化工具的核心价值在于降低认知负担和提升操作效率。它将抽象的Git对象（提交、分支、标签）和关系（合并、分叉）直观地呈现出来。

• 何时选择图形化工具？

  • 你是Git新手，希望先感受版本控制带来的好处，再深入原理。
  • 你的日常工作以简单的提交、推送、拉取为主，很少涉及复杂历史操作。
  • 你需要经常查看清晰的项目历史图谱来理解代码演进。
  • 你所在的团队使用固定的分支模型（如Git Flow），GUI工具通常有预设流程支持。

• 一个重要的建议：即使你主要使用GUI工具，也强烈建议你同时了解基本的命令行操作。因为：

  1. 在GUI工具出错或遇到无法理解的情况时，命令行是最终的问题排查和解决手段。
  2. 在服务器、CI/CD环境或某些特定脚本中，你只能使用命令行。
  3. 理解命令行有助于你更深刻地理解GUI工具每个按钮背后的实际动作，从而用得更加得心应手。

5. 实战中你必须绕开的那些“坑”

掌握了基本流程，并不意味着就能一帆风顺。在实际操作中，有几个高频出现的“坑点”，需要我们特别注意。

5.1 坑点一：远程仓库非空导致的推送失败

这是新手最常遇到的问题之一。按照本文2.1节的建议，创建远程仓库时不要初始化README等文件，就是为了避免这个坑。但如果已经初始化了，或者你要推送到的仓库本身就有内容，该怎么办？

问题现象：当你执行git push -u origin main时，可能会收到类似这样的错误：

! [rejected] main -> main (non-fast-forward) error: failed to push some refs to ‘gitee.com:...‘ hint: Updates were rejected because the remote contains work that you do not have locally...

原因分析：这是因为远程仓库的main分支已经有一个提交（比如初始化README的提交），而你的本地main分支是基于一个空仓库开始的，这两个分支的历史没有共同的“祖先”，Git无法简单地合并它们。

解决方案：有两种主流方法：

1. 强制推送（不推荐，除非你完全确定）：使用git push -f origin main。这会用你的本地历史强行覆盖远程历史。如果远程仓库只有你一个人用，且初始化提交无意义，可以这么做。但在协作项目中，这极其危险，会覆盖他人的工作。
2. 先拉取再合并（推荐）：执行以下命令：

   git pull origin main --allow-unrelated-histories

   --allow-unrelated-histories选项允许Git合并两个没有共同祖先的历史。这通常会产生一个合并提交。Git可能会自动合并，也可能会提示冲突（比如你们都有一个同名文件README.md）。如果有冲突，需要手动解决冲突文件，然后执行git add .和git commit来完成合并。最后再执行git push origin main。

最佳实践：对于全新的本地项目，始终坚持从空的远程仓库开始。

5.2 坑点二：忽略文件.gitignore配置不当

.gitignore文件配置错误，会导致大量无关文件（如系统文件、IDE配置、编译输出、依赖包）被提交到仓库，使仓库体积暴涨，克隆速度变慢，且容易泄露敏感信息。

常见问题：

• 忘记添加.gitignore文件。
• .gitignore的语法错误，导致规则不生效。
• 已经提交到仓库的文件，即使后来加入.gitignore，Git依然会继续追踪。

解决方案与技巧：

1. 项目伊始就创建：在git init之后，立即创建.gitignore文件。你不需要从头写，很多IDE（如VS Code）或项目框架（如Vue CLI, Create React App）在创建项目时会自动生成。你也可以去 GitHub 的 gitignore 模板仓库，找到对应语言或工具的模板复制使用。
2. 检查规则是否生效：使用git status --ignored可以查看被忽略的文件，确认你的规则写对了。
3. 清除已追踪的忽略文件：如果误将node_modules这样的目录提交了，仅仅在.gitignore中添加规则是不够的，因为Git已经在追踪它了。你需要将其从Git索引中移除（但保留在本地磁盘）：

   git rm -r --cached node_modules git commit -m “Stop tracking node_modules directory”

   然后再进行推送。这样，远程仓库将不再包含这个目录，但本地文件依然存在。

5.3 坑点三：提交信息（Commit Message）过于随意

糟糕的提交信息就像没有标签的罐头，时间一长，你完全不知道里面是什么，更别说回溯历史、定位问题了。

反面教材：“update”，“fix bug”，“修改”。

优秀提交信息的要素：

• 格式：通常第一行是简短摘要（不超过50字符），空一行后是详细描述。
• 摘要：使用祈使句，说明这次提交的目的，而非做了什么。例如：“修复用户头像上传时尺寸校验失效的问题” 比 “修改了upload.js的校验逻辑” 要好。
• 详情：解释为什么要这么修改，以及相关的上下文。如果解决了某个Issue，可以附上Issue编号（如Fix #123）。

工具辅助：可以使用类似commitizen这样的工具来规范提交信息格式，强制自己养成好习惯。

5.4 坑点四：在错误的分支上进行开发

这是一个经典的流程错误。很多人习惯直接在main分支上开发新功能或修复bug，这会导致主分支历史混乱，并且在进行代码审查或并行开发多个功能时带来灾难。

正确的工作流：

1. 在开始任何新工作前，从稳定的主分支（如main）创建一个新分支。

   git checkout -b feature/add-user-login

   分支名最好能描述工作内容，如feature/xxx，bugfix/xxx，hotfix/xxx。
2. 在新分支上进行所有开发、提交。
3. 开发完成后，在Gitee上发起一个Pull Request（合并请求），请求将你的分支合并到main分支。
4. 经过代码审查（或自行检查）后，在Gitee上完成合并。这种方式留下了清晰的历史记录和协作痕迹。

如果你已经在main分支上做了一些提交，但还没推送，可以通过git branch new-feature创建新分支，然后git reset --hard origin/main将main分支重置到与远程一致的状态，再将工作切换到new-feature分支继续。

6. 进阶场景：当简单推送变得复杂

掌握了基本操作后，你会遇到一些更复杂的场景，这些场景在真实的个人或团队开发中几乎无法避免。

6.1 处理合并冲突

当你和你的同事修改了同一个文件的同一区域，并先后推送到远程时，后推送的人就会遇到合并冲突。

冲突发生时的表现：在执行git pull或git merge时，Git会提示CONFLICT (content)，并在冲突文件中用<<<<<<<，=======，>>>>>>>标记出冲突内容。

手动解决冲突的步骤：

1. 保持冷静：冲突是协作开发的正常现象。
2. 定位冲突文件：git status会明确列出所有处于“未合并”状态的文件。
3. 编辑文件：打开冲突文件，你会看到类似这样的标记：

   <<<<<<< HEAD 这是你本地的修改 ======= 这是远程拉取下来的修改 >>>>>>> branch-name

   你需要手动决定保留哪一部分，或者进行整合。删除所有的冲突标记（<<<<<<<，=======，>>>>>>>），将文件修改成你最终想要的样子。
4. 标记冲突已解决：解决完所有冲突文件后，使用git add <file>将每个解决后的文件添加到暂存区。这告诉Git冲突已经处理完毕。
5. 完成合并：执行git commit。Git会为你生成一个默认的合并提交信息，你也可以修改它。

使用工具：无论是VS Code、IntelliJ IDEA等现代编辑器，还是Sourcetree、Beyond Compare等专业工具，都提供了非常直观的图形化冲突解决界面，可以并排对比更改，通过点击按钮来选择保留哪一边的修改，极大提升了效率。

6.2 同步Fork的仓库

在开源社区，我们经常需要“Fork”别人的仓库到自己的账号下，然后进行修改，最后希望将修改贡献回原仓库。这就涉及如何让自己的Fork仓库与原仓库（上游仓库）保持同步。

操作流程：

1. 添加上游远程仓库：克隆你自己的Fork仓库到本地后，需要添加原仓库为另一个远程源，通常命名为upstream。

   git remote add upstream https://gitee.com/original_author/original_repo.git

2. 获取上游更新：从上游仓库拉取最新的提交和历史。

   git fetch upstream

3. 合并到本地分支：切换到你的本地主分支（如main），并将上游的更新合并进来。

   git checkout main git merge upstream/main

   这里可能会产生合并冲突，按上述方法解决即可。
4. 更新你自己的Fork：将合并后的本地主分支推送到你自己的远程Fork仓库（origin）。

   git push origin main

   这样，你的Gitee上的Fork仓库就和原仓库同步了。之后，你可以在同步后的基础上创建新分支进行开发，并通过Gitee的“Pull Request”功能向原仓库提交贡献。

6.3 撤销与回退操作

人难免会犯错，比如提交了错误的文件、写了错误的提交信息。Git提供了多种“后悔药”。

• 撤销工作区的修改（文件还未git add）：git checkout -- <file>。这个命令很危险，它会用暂存区或仓库中的版本覆盖工作区的修改，且无法恢复。慎用！
• 撤销暂存区的修改（文件已git add，但未git commit）：git reset HEAD <file>。这个命令将文件从暂存区移回工作区，但保留工作区的修改内容。
• 修改最后一次提交：
  • 如果只是提交信息写错了：git commit --amend，会进入编辑器让你修改信息。
  • 如果漏了文件：先git add漏掉的文件，再执行git commit --amend，可以将这次修改合并到上一次提交中，而不会产生新的提交记录。
• 回退到某个历史版本：使用git reset或git revert。
  • git reset --hard <commit_id>：危险！将当前分支的指针直接移动到指定的提交，并丢弃之后的所有提交。这相当于“删除”了历史，如果这些提交已经推送到远程，会给协作者带来巨大麻烦。仅限在本地未推送时使用。
  • git revert <commit_id>：安全！创建一个新的提交，这个新提交的内容是指定提交的“反操作”，从而撤销那次提交的更改。历史记录被完整保留，并且可以安全地推送到远程。这是团队协作中撤销更改的推荐方式。

对于这些进阶操作，尤其是在涉及历史重写的reset操作时，务必先确认操作的影响范围，在不确定的情况下，可以先在一个临时分支上测试。图形化工具（如Sourcetree）在可视化执行这些操作和预览结果方面，有着巨大的优势。