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或gitgitee.com: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/Debiansudo 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通信地址以gitgitee.com:开头就需要配置SSH密钥。相比于HTTPS每次操作都可能需要输入密码SSH通过密钥对进行认证一次配置长期免密更加安全便捷。生成密钥对在终端运行以下命令将your_emailexample.com替换为你的邮箱。ssh-keygen -t ed25519 -C your_emailexample.com按回车接受默认的密钥保存路径通常是~/.ssh/id_ed25519然后设置一个安全的密码可直接回车留空但不建议生产环境这么做。查看并复制公钥cat ~/.ssh/id_ed25519.pub终端会显示一长串以ssh-ed25519开头的内容完整复制它。在Gitee中添加公钥登录Gitee点击头像 - 设置 - SSH公钥。在“添加公钥”页面将刚才复制的公钥内容粘贴到“公钥”文本框中标题可以自拟如“My Laptop”然后点击“确定”。测试连接在终端运行ssh -T gitgitee.com。如果看到类似 “Hi XXX! You‘ve successfully authenticated...” 的欢迎信息说明配置成功。完成以上所有准备后我们就可以根据不同的偏好选择代码上传的路径了。3. 方式一使用Git命令行——精准掌控的“手动挡”对于开发者而言掌握Git命令行是一项基本功。它就像开车的手动挡虽然初期学习曲线稍陡但能让你对整个过程有最精细的控制理解每一个操作背后的原理并且在任何环境下包括没有图形界面的服务器都能游刃有余。3.1 场景一将全新的本地项目首次推送到Gitee假设你已经在本地电脑上新建了一个项目文件夹my-project里面有一些代码文件现在想把它放到Gitee上成为一个新的仓库。操作流程与原理拆解初始化本地Git仓库 打开终端进入你的项目目录。cd /path/to/your/my-project git init这个git init命令会在当前目录下创建一个隐藏的.git文件夹这是Git用来跟踪管理版本历史的所有元数据所在。此时你的项目目录就变成了一个Git本地仓库。将文件添加到暂存区Staging Areagit add .这里的.代表当前目录下的所有文件除了在.gitignore中声明的。git add命令的本质是将工作目录中文件的当前快照添加到暂存区。暂存区是一个中间区域你可以把它想象成购物车你把想要这次“提交”的修改先放进去可以反复添加或移除直到确认无误。使用git status命令可以随时查看哪些文件已被暂存绿色哪些文件有修改但未暂存红色。实操心得新手常犯的一个错误是直接git add .把所有文件包括编译产物、依赖目录node_modules、IDE配置文件等都加进去。这会导致仓库臃肿且充满垃圾。正确的做法是先创建一个.gitignore文件在里面列出所有需要被Git忽略的文件和目录模式。例如对于一个Node.js项目.gitignore里至少应该有node_modules/和.env。然后再执行git add .。提交更改到本地仓库git commit -m “Initial commit: project setup”git commit命令将暂存区的内容创建一个永久的快照保存到本地仓库的历史记录中。-m后面跟的是提交信息务必认真填写。好的提交信息应该简洁明了地说明这次提交的目的例如“修复了登录接口的空指针异常”比“修改了代码”要有用得多。关联远程仓库 现在需要告诉本地仓库它应该把代码推送到哪里。回到Gitee你创建的空仓库页面复制它的SSH或HTTPS地址。git remote add origin gitgitee.com:your-username/your-repo.gitgit remote add命令添加一个远程仓库的别名。这里我们习惯将主要的远程仓库命名为origin。你可以通过git remote -v命令查看已关联的远程仓库地址。推送本地提交到远程仓库git push -u origin main这是最关键的一步。git push命令将本地仓库的提交记录上传到指定的远程仓库。origin我们刚刚设置的远程仓库别名。main这是你要推送的本地分支名。现在Git默认的主分支名是main早年是master。-u这是--set-upstream的简写。它建立了本地main分支与远程origin/main分支的追踪关系。设置之后下次在这个分支上只需要简单地输入git push或git pullGit就知道应该与哪个远程分支交互。执行后终端会显示推送进度。完成后刷新你的Gitee仓库页面就能看到代码已经安然在列了。3.2 场景二克隆现有仓库与后续更新如果你要参与一个已经存在于Gitee上的项目或者换了一台电脑需要拉取代码流程则从“克隆”开始。克隆远程仓库git clone gitgitee.com:some-username/existing-repo.git这个命令会在当前目录下创建一个以仓库名命名的文件夹existing-repo并将远程仓库的整个历史记录和所有分支下载到本地同时自动设置好远程别名origin。日常开发循环进入克隆下来的项目目录你的日常操作将形成一个固定循环修改代码。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平台功能对中文用户友好。下载与安装从Gitee官网下载对应系统的客户端并安装。登录与克隆打开客户端使用Gitee账号登录。你可以通过“克隆”按钮输入仓库URL将远程仓库克隆到本地。仓库管理界面客户端主界面通常分为几个区域文件变更列表、提交信息输入框、提交历史图谱。进行提交在工作区修改文件后客户端会自动检测到“未暂存的文件”。你可以勾选需要提交的文件相当于git add在下方输入提交信息。点击“提交”按钮这一步相当于git commit但提交只发生在本地。提交后点击“推送”按钮将本地提交推送到Gitee远程仓库。拉取与同步点击“拉取”按钮可以获取远程更新。客户端通常会将git pull拉取并合并的操作封装在一起。优点与Gitee无缝集成方便管理Gitee上的Issue、Pull Request等界面简洁上手极快。不足功能相对基础对于复杂的分支操作、历史重写等支持较弱。4.2 使用Sourcetree第三方强力推荐Sourcetree是Atlassian公司出品的免费Git图形化工具功能非常强大被誉为“Git GUI神器”。安装与初始配置下载安装Sourcetree。首次运行可能会要求你安装附带的Git如果系统没有的话。你需要配置用户信息同命令行配置。克隆仓库点击“克隆”按钮输入源路径Gitee仓库SSH/HTTPS地址和目标路径即可克隆。强大的主界面Sourcetree的界面信息量丰富。左侧边栏显示本地和远程分支列表管理非常方便。中间文件状态区清晰展示工作副本文件的状态未暂存、已暂存、已忽略。提交面板勾选文件、输入信息、进行提交。底部历史图谱这是Sourcetree的精华它以可视化图形的方式展示所有分支和提交的演进历史合并、分叉一目了然对于理解项目历史非常有帮助。进行提交与推送操作流程与Gitee客户端类似但可视化反馈更细致。提交后在顶部工具栏点击“推送”按钮选择要推送的分支即可。高级功能Sourcetree几乎封装了所有常用Git命令。你可以通过右键菜单轻松进行“检出分支”、“合并”、“变基”、“贮藏”等操作。对于解决合并冲突它也提供了直观的对比合并工具。优点功能全面可视化历史图谱无敌适合管理复杂的分支策略既降低了入门门槛又提供了进阶操作的能力。不足界面相对复杂初次使用需要一点时间适应软件体积较大。4.3 图形化工具的核心价值与选择建议图形化工具的核心价值在于降低认知负担和提升操作效率。它将抽象的Git对象提交、分支、标签和关系合并、分叉直观地呈现出来。何时选择图形化工具你是Git新手希望先感受版本控制带来的好处再深入原理。你的日常工作以简单的提交、推送、拉取为主很少涉及复杂历史操作。你需要经常查看清晰的项目历史图谱来理解代码演进。你所在的团队使用固定的分支模型如Git FlowGUI工具通常有预设流程支持。一个重要的建议即使你主要使用GUI工具也强烈建议你同时了解基本的命令行操作。因为在GUI工具出错或遇到无法理解的情况时命令行是最终的问题排查和解决手段。在服务器、CI/CD环境或某些特定脚本中你只能使用命令行。理解命令行有助于你更深刻地理解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无法简单地合并它们。解决方案有两种主流方法强制推送不推荐除非你完全确定使用git push -f origin main。这会用你的本地历史强行覆盖远程历史。如果远程仓库只有你一个人用且初始化提交无意义可以这么做。但在协作项目中这极其危险会覆盖他人的工作。先拉取再合并推荐执行以下命令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的语法错误导致规则不生效。已经提交到仓库的文件即使后来加入.gitignoreGit依然会继续追踪。解决方案与技巧项目伊始就创建在git init之后立即创建.gitignore文件。你不需要从头写很多IDE如VS Code或项目框架如Vue CLI, Create React App在创建项目时会自动生成。你也可以去 GitHub 的 gitignore 模板仓库找到对应语言或工具的模板复制使用。检查规则是否生效使用git status --ignored可以查看被忽略的文件确认你的规则写对了。清除已追踪的忽略文件如果误将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这会导致主分支历史混乱并且在进行代码审查或并行开发多个功能时带来灾难。正确的工作流在开始任何新工作前从稳定的主分支如main创建一个新分支。git checkout -b feature/add-user-login分支名最好能描述工作内容如feature/xxxbugfix/xxxhotfix/xxx。在新分支上进行所有开发、提交。开发完成后在Gitee上发起一个Pull Request合并请求请求将你的分支合并到main分支。经过代码审查或自行检查后在Gitee上完成合并。这种方式留下了清晰的历史记录和协作痕迹。如果你已经在main分支上做了一些提交但还没推送可以通过git branch new-feature创建新分支然后git reset --hard origin/main将main分支重置到与远程一致的状态再将工作切换到new-feature分支继续。6. 进阶场景当简单推送变得复杂掌握了基本操作后你会遇到一些更复杂的场景这些场景在真实的个人或团队开发中几乎无法避免。6.1 处理合并冲突当你和你的同事修改了同一个文件的同一区域并先后推送到远程时后推送的人就会遇到合并冲突。冲突发生时的表现在执行git pull或git merge时Git会提示CONFLICT (content)并在冲突文件中用标记出冲突内容。手动解决冲突的步骤保持冷静冲突是协作开发的正常现象。定位冲突文件git status会明确列出所有处于“未合并”状态的文件。编辑文件打开冲突文件你会看到类似这样的标记 HEAD 这是你本地的修改 这是远程拉取下来的修改 branch-name你需要手动决定保留哪一部分或者进行整合。删除所有的冲突标记将文件修改成你最终想要的样子。标记冲突已解决解决完所有冲突文件后使用git add file将每个解决后的文件添加到暂存区。这告诉Git冲突已经处理完毕。完成合并执行git commit。Git会为你生成一个默认的合并提交信息你也可以修改它。使用工具无论是VS Code、IntelliJ IDEA等现代编辑器还是Sourcetree、Beyond Compare等专业工具都提供了非常直观的图形化冲突解决界面可以并排对比更改通过点击按钮来选择保留哪一边的修改极大提升了效率。6.2 同步Fork的仓库在开源社区我们经常需要“Fork”别人的仓库到自己的账号下然后进行修改最后希望将修改贡献回原仓库。这就涉及如何让自己的Fork仓库与原仓库上游仓库保持同步。操作流程添加上游远程仓库克隆你自己的Fork仓库到本地后需要添加原仓库为另一个远程源通常命名为upstream。git remote add upstream https://gitee.com/original_author/original_repo.git获取上游更新从上游仓库拉取最新的提交和历史。git fetch upstream合并到本地分支切换到你的本地主分支如main并将上游的更新合并进来。git checkout main git merge upstream/main这里可能会产生合并冲突按上述方法解决即可。更新你自己的Fork将合并后的本地主分支推送到你自己的远程Fork仓库origin。git push origin main这样你的Gitee上的Fork仓库就和原仓库同步了。之后你可以在同步后的基础上创建新分支进行开发并通过Gitee的“Pull Request”功能向原仓库提交贡献。6.3 撤销与回退操作人难免会犯错比如提交了错误的文件、写了错误的提交信息。Git提供了多种“后悔药”。撤销工作区的修改文件还未git addgit checkout -- file。这个命令很危险它会用暂存区或仓库中的版本覆盖工作区的修改且无法恢复。慎用撤销暂存区的修改文件已git add但未git commitgit 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在可视化执行这些操作和预览结果方面有着巨大的优势。