Gitee入门

第一章：缘起——为什么是Gitee？

在正式开始介绍之前，我们先简单了解一下为什么推荐Gitee。

1.1 访问速度极快

服务器 位于国内，无论是克隆、推送还是拉取代码，速度都比 GitHub 快数个量级，尤其是在下载大型仓库或依赖时，体验提升巨大。

1.2 全中文环境

界面、文档、帮助中心均为中文，对国内用户非常友好，降低了学习和使用门槛。

1.3 符合本地需求

集成了代码片段、Wiki、Issue、Pull Request（Gitee中称为“Pull Request”或“合并请求”）、Pages（Gitee Pages）等功能，同时支持企业版的私有化部署，更贴合国内企业和团队的工作流程。

1.4 生态整合

与国内的CI/CD（如Jenkins）、项目管理工具 TAPD 等有较好的集成。

对于个人学习者、初创团队以及国内企业项目，Gitee提供了一个非常稳定和高效的协作环境。

---

第二章：万丈高楼平地起——Gitee账号注册与准备

第1步：注册Gitee账号

1. 打开Gitee官网：Gitee
2. 点击页面右上角的 【注册】 按钮。
3. 你可以通过 手机号 或 邮箱 进行注册。按提示填写信息即可。建议使用常用邮箱，方便接收重要通知。
4. 注册完成后，别忘记去邮箱激活账号。激活后，你的Gitee之旅就正式开始了。

第2步：安装Git

Gitee是一个Git服务器，我们要在本地操作，必须安装Git客户端。

Windows用户：

1、访问 Git 官方下载页：https://git-scm.com/download/win

2、下载并运行安装程序。安装过程中，一路 “Next” 即可，但有几个关键点需要注意：

（1）选择组件: 勾选 Git Bash Here 和 Git GUI Here，非常实用。
（2）选择默认编辑器: 强烈推荐选择 Use Visual Studio Code as Git's default editor（如果你安装了VSCode），或者选择你熟悉的编辑器（如Nano、Vim）。
（3）调整Path环境: 选择 Git from the command line and also from 3rd-party software。这将允许你在任何命令行（如CMD、PowerShell）中使用Git。
（4）选择SSH客户端: 使用默认的 OpenSSH。
（5）配置行结束符转换: 选择 Checkout Windows-style, commit Unix-style line endings。这是为了Windows和Unix/Linux系统协作时的兼容性。
（6）终端模拟器: 选择默认的 Use MinTTY。
（7）其他选项默认即可。

macOS用户：

（1）最简单的方法：安装Xcode Command Line Tools。在终端（Terminal）中运行 xcode-select --install。
（2）或者使用Homebrew：brew install git。

Linux用户 (如Ubuntu/Debian)：

在终端中运行：sudo apt-get update && sudo apt-get install git
安装验证：安装完成后，打开你的终端（Windows可用Git Bash或CMD/PowerShell），输入：

git --version

如果正确显示版本号（如 git version 2.37.1.windows.1），说明安装成功。

第3步：全局配置Git用户信息

这是非常重要的一步！你提交的每一次代码都会带有这个身份信息，它用于标识提交者。

在终端中执行以下两条命令，将示例邮箱和用户名替换成你注册Gitee时使用的信息：

git config --global user.name "Your-Gitee-Username"
git config --global user.email "your-email@gitee.com"

（1）——global表示这是全局配置，对你这台电脑上所有的Git仓库生效。如果某个项目想用不同的信息，可以在项目目录下不加 --global 再配置一次；
（2）user.name 建议和Gitee用户名保持一致，避免混淆；
（3）user.email 必须是你在Gitee上注册时使用的邮箱，否则你的提交贡献将无法在Gitee上正确统计。检查配置是否成。

git config --global --list

---

第三章：建立安全通道——配置SSH公钥

为了避免每次推送代码都输入账号密码，我们需要配置SSH密钥，实现免密安全登录。这是最佳实践，务必掌握。

第1步：生成SSH密钥对

1、打开终端（Git Bash）。

2、运行以下命令，将 your-email@example.com 替换为你的Gitee邮箱：

ssh-keygen -t ed25519 -C "your-email@example.com"

如果你的系统不支持 ed25519 算法，可以使用旧的RSA算法：ssh-keygen -t rsa -b 4096 -C "your-email@example.com"。

3、接下来会提示你“Enter file in which to save the key”，直接按回车，使用默认的保存路径（~/.ssh/id_ed25519 或 ~/.ssh/id_rsa）。

4、会提示你输入一个密码（passphrase），可以直接回车留空（方便使用），当然为了安全起见，设置一个密码更好。之后推送时可能需要输入这个密码。

第2步：将公钥添加到Gitee

1、根据你上一步选择的算法，在终端中用以下命令打印出公钥内容：

（1）如果是 ed25519: cat ~/.ssh/id_ed25519.pub；
（2）如果是 rsa: cat ~/.ssh/id_rsa.pub。

2、终端会显示一长串以 ssh-ed25519 或 ssh-rsa 开头，以你的邮箱结尾的文本。完整地复制它。

3、登录Gitee，点击右上角头像 -> 【设置】。

4、进入左侧菜单的 【SSH公钥】。

5、在“添加公钥”页面：

（1）标题: 给你的公钥起个名字，比如 My Work Laptop。
（2）公钥: 粘贴你刚才复制的完整公钥内容。

6、点击 【确定】，可能需要验证一下密码。

第3步：验证是否配置成功

ssh -T git@gitee.com

第一次连接时，会提示你是否信任主机，输入 yes 回车。 如果配置成功，你会看到一条如下的欢迎信息

Hi USERNAME! You've successfully authenticated, but Gitee.com does not provide shell access.

这表明你的SSH通道已经成功建立！

---

第四章：第一个仓库——代码上传全流程

现在我们开始实战，将本地代码推送到Gitee。

场景A：本地已有项目，想推送到Gitee

第1步：在Gitee上创建远程仓库

1、登录Gitee，点击右上角 + 号，选择 【新建仓库】。

2、填写仓库信息：

（1）仓库名称：必填，如 my-awesome-project。
（2）路径：会自动生成，通常和仓库名一致，这是你仓库的URL的一部分。
（3）介绍：可选，简单描述你的项目。
（4）公开/私有：选择仓库的可见性。私有仓库只有你授权的人才能看到。
（5）初始化仓库：不要勾选 使用Readme文件初始化这个仓库。因为我们本地已有项目，如果勾选，会导致后续推送冲突，需要先拉取合并，对新手不友好。我们从一个空的仓库开始。
（6）选择.gitignore 和 许可证：可以根据你的项目类型选择，也可以后续手动添加。

3、点击 【创建】。

第2步：初始化本地仓库并提交代码

1、打开终端，进入到你的本地项目根目录。

2、执行以下命令，初始化一个本地Git仓：

git init

这会在当前目录创建一个 .git 的隐藏文件夹。

3、将当前目录下的所有文件（除了在 .gitignore 中声明的）添加到暂存区（Stage）：

git add .

git add . 中的 . 代表当前目录。你也可以用 git add filename 添加特定文件。

4、将暂存区的文件提交（Commit） 到本地仓库，并附上提交信息：

git commit -m "first commit: init project"

-m 后面的字符串是本次提交的说明，必须填写，且应清晰有意义。

第3步：关联远程仓库并推送

1、将你在Gitee上创建的空仓库的地址关联到本地仓库。

（1）在Gitee你的空仓库页面，点击 【克隆/下载】 按钮，选择 SSH，复制地址（如 git@gitee.com:your-username/your-repo-name.git）。

2、在终端中，为本地仓库添加一个名为 origin 的远程地址（这是惯例，代表主仓库：

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

使用 git remote -v 可以查看是否添加成功。

3、首次推送，使用 -u 参数将本地的 master 分支（现在主流更推荐 main，但Git默认初始化可能是 master）推送到远程的 origin 仓库，并建立关联：

git push -u origin master
# 或者，如果你的默认分支是 main
# git push -u origin main

-u (或 --set-upstream) 选项会记住这次推送的分支和目标，下次在这个分支只需要输入 git push 即可。

恭喜！ 刷新你的Gitee仓库页面，代码已经全部安静地躺在那里了。

场景B：从Gitee克隆（Clone）已有项目

如果你要参与别人的项目，或者在公司电脑上继续开发家里电脑上传的项目，你需要克隆。

1、在Gitee上找到你要克隆的项目仓库页面。

2、点击 【克隆/下载】，复制SSH地址（如 git@gitee.com:username/repo.git）。

3、在终端中，切换到你想存放项目的目录，运行：

git clone git@gitee.com:username/repo.git

4、Git会自动为你完成以下操作：

（1）在当前目录下创建一个以仓库名命名的文件夹。
（2）初始化本地仓库。
（3）关联远程仓库，默认名称就是 origin。
（4）拉取（Pull）远程 origin 的所有数据（默认分支）。

5、进入项目目录 (cd repo)，你就可以开始开发了。

---

第五章：日拱一卒——日常开发工作流

你不会只提交一次代码。日常开发是不断循环以下步骤：

5.1 标准流程：add -> commit -> push

1、修改代码：完成一个小功能或修复一个bug。
2、查看状态：使用 git status 查看哪些文件被修改、哪些已暂存。
3、添加到暂存区：git add . 或 git add specific_file.js。
4、提交到本地仓库：git commit -m "feat: add user login function"。提交信息要规范，推荐使用 约定式提交 规范，如 fix:, feat:, docs: 等开头。
5、推送到远程：git push。因为第一次推送时用了 -u，所以这里直接 git push 就行。

5.2 重要概念：拉取更新（Pull）！

在团队协作中，远程仓库可能已经被队友更新了。所以在你的 git push 之前，务必先拉取一下远程的最新更改，并合并到本地，避免冲突。

git pull origin master
# 等同于 git fetch + git merge
# 如果默认分支是main，则替换为main

如果 git pull 后存在冲突，Git会提示你，你需要手动解决冲突文件中的差异（文件中的 <<<<<<<, =======, >>>>>>> 标记），然后再次 add, commit, push。

---

第六章：锦上添花——高级技巧与最佳实践

6.1 .gitignore 文件

这个文件告诉Git哪些文件或目录不需要纳入版本控制。比如IDE配置文件（.idea/, .vscode/）、依赖文件夹（node_modules/）、日志文件、编译产物等。

最佳实践：项目一开始就创建它。你可以在 gitignore.io - Create Useful .gitignore Files For Your Project 生成对应语言或工具的 .gitignore 模板。

6.2 分支（Branch）管理

在主分支（master/main）上直接开发是危险的。应该为每个新功能或bug修复创建一个新分支。

# 创建并切换到新功能分支
git checkout -b feature/awesome-new-feature

# 在新分支上开发、提交...
git add .
git commit -m "feat: implement awesome feature A"

# 开发完成后，切换回主分支
git checkout main

# 确保主分支是最新的
git pull origin main

# 将功能分支合并到主分支
git merge feature/awesome-new-feature

# 删除已合并的本地功能分支
git branch -d feature/awesome-new-feature

# 推送更新后的主分支
git push origin main

6.3 使用Gitee的 Pull Request (PR)

如果你在 Fork 的仓库上开发（参与开源项目），或者公司的代码审查流程要求，你不会直接合并到主分支，而是发起一个 Pull Request（合并请求）。

1、将你的功能分支推送到你的远程仓库：git push origin feature/xxx。
2、在Gitee仓库页面，通常会自动弹出创建PR的提示，或者你手动点击 【Pull Requests】 -> 【新建 Pull Request】。
3、选择你的功能分支作为源分支，目标分支为主分支。
4、填写标题和描述，请求代码审查。
5、审查通过后，由项目管理员合并你的PR。

---

第七章：常见问题与避坑指南（Q&A）

7.1 Q: git push 提示 Permission denied (publickey)？

A：SSH密钥配置失败。请重新检查第三章的所有步骤：密钥是否生成、公钥是否完整复制到Gitee、是否验证成功。

7.2 Q: git push 提示 error: failed to push some refs to...？

A：通常是因为远程仓库有你本地没有的更新（比如你在网页上创建了README文件）。先执行 git pull origin master --rebase，拉取远程更新并变基，解决可能的冲突后，再 git push。

7.3 Q: 提交时写错了提交信息怎么办？

A：如果还没推送到远程，使用 git commit --amend 命令可以修改上一次的提交信息。

7.4 Q: 误把不该提交的文件（如密码配置文件）add 了怎么办？

A：如果还没commit，用 git reset HEAD <file> 将其从暂存区撤出。如果已经commit了，需要使用 git filter-branch 或 BFG Repo-Cleaner 等工具从历史中彻底删除，这操作很危险，建议查专门教程。

---

总结与展望

至此，你已经系统地掌握了Gitee的核心使用流程：

1、环境准备：注册 + 安装Git + 配置用户信息。
2、安全通道：生成并配置SSH密钥，实现免密操作。
3、核心操作：
（1）git init, git add, git commit, git push (本地到远程)；
（2）git clone, git pull (远程到本地)
4、进阶知识：.gitignore、分支、Pull Request。

理论看千遍，不如动手做一遍。现在就找一个你的本地项目，按照指南，完整地走一遍流程吧！

Gitee和Git的功能远不止于此，诸如 标签（Tag）、贮藏（Stash）、重置（Reset）、回退（Revert） 等高级操作，以及基于Git的CI/CD自动化，都是你未来可以探索的方向。掌握了本文的基础，你将有足够的能力去征服它们！