Gitee代码托管平台使用指南与Git工作流实践

1. 为什么选择Gitee作为代码托管平台

在国内开发环境中，Gitee（码云）已经成为许多开发者的首选代码托管平台。与GitHub相比，Gitee最大的优势在于访问速度和稳定性。我亲身体验过在GitHub上克隆一个几百MB的仓库需要半小时以上，而在Gitee上通常只需要几十秒。这对于日常开发中的频繁提交和拉取操作来说，体验提升非常明显。

Gitee提供了完整的Git仓库管理功能，包括代码托管、Issue跟踪、Pull Request等。它还支持免费的私有仓库（GitHub的私有仓库需要付费），这对于个人开发者和小团队特别友好。另外，Gitee还提供了Pages服务、CI/CD集成等扩展功能，基本能满足大多数开发项目的需求。

提示：如果你是企业用户，Gitee还提供了企业版，支持更严格的权限管理和团队协作功能。

2. 创建Gitee仓库的详细步骤

2.1 注册和登录Gitee账号

首先，你需要有一个Gitee账号。访问Gitee官网（gitee.com），点击右上角的"注册"按钮。注册过程很简单，只需要提供邮箱和设置密码即可。注册完成后，记得验证邮箱，这样可以使用全部功能。

登录后，你会看到个人主页。这里会显示你的仓库、动态等信息。建议在"账号设置"中完善个人信息，特别是设置SSH公钥，这会让后续的代码推送更方便安全。

2.2 创建新仓库

在Gitee上创建新仓库非常简单：

1. 点击页面右上角的"+"按钮，选择"新建仓库"
2. 填写仓库基本信息：
   • 仓库名称：建议使用英文，避免特殊字符
   • 仓库介绍：简要说明这个仓库的用途
   • 公开/私有：选择仓库的可见性
   • 初始化仓库：可以选择添加README文件、.gitignore和开源许可证
3. 点击"创建"按钮完成仓库创建

我通常会勾选"初始化README"选项，这样仓库会有一个基础的结构。.gitignore文件可以根据项目类型选择，比如Java项目就选择Java模板，这会自动忽略掉一些不必要的文件（如.class文件）。

2.3 仓库设置调整

创建完成后，你可能需要调整一些仓库设置：

1. 进入仓库，点击"管理"选项卡
2. 在"基本设置"中，可以修改仓库名称、描述等信息
3. 在"协作成员"中，可以添加其他开发者共同维护这个仓库
4. 在"WebHooks"中，可以设置一些自动化触发操作

注意：仓库名称一旦确定，后续修改会影响仓库URL，可能导致已有的引用链接失效，所以命名时要考虑清楚。

3. 本地项目准备与Git配置

3.1 安装和配置Git

在推送项目前，你需要在本地安装Git。不同操作系统的安装方法：

• Windows：下载Git for Windows安装包
• macOS：使用Homebrew（brew install git）或直接下载安装包
• Linux：使用系统包管理器（如apt-get install git）

安装完成后，需要进行一些基本配置：

git config --global user.name "你的名字" git config --global user.email "你的邮箱" git config --global core.editor "vim" # 设置你喜欢的编辑器

这些信息会记录在你的提交记录中，建议使用与Gitee账号相同的邮箱。

3.2 初始化本地仓库

如果你已经有一个项目目录，可以这样初始化Git仓库：

cd /path/to/your/project git init

这会创建一个.git目录，用来存储Git的版本控制信息。

对于新项目，我通常会先创建项目目录结构，比如：

project/ ├── src/ ├── docs/ ├── tests/ └── README.md

然后再初始化Git仓库。这样的结构清晰，便于后续维护。

3.3 添加.gitignore文件

.gitignore文件非常重要，它告诉Git哪些文件不需要纳入版本控制。比如：

# 编译生成文件 *.class *.exe *.dll # 日志文件 *.log # IDE相关文件 .idea/ .vscode/ # 系统文件 .DS_Store Thumbs.db

根据你的项目类型，可以从网上找到合适的.gitignore模板，或者使用Gitee创建仓库时提供的模板。

4. 将本地项目推送到Gitee仓库

4.1 关联远程仓库

在本地仓库中添加Gitee远程仓库地址：

git remote add origin https://gitee.com/你的用户名/仓库名.git

或者使用SSH方式（推荐）：

git remote add origin git@gitee.com:你的用户名/仓库名.git

SSH方式需要先在Gitee账号设置中添加你的SSH公钥，但之后操作就不需要每次都输入密码了。

4.2 首次推送代码

标准的首次推送流程：

git add . # 添加所有文件到暂存区 git commit -m "初始提交" # 提交到本地仓库 git push -u origin master # 推送到远程仓库

-u参数设置上游分支，这样以后可以直接使用git push而不用指定远程分支。

4.3 处理推送冲突

如果远程仓库已经有内容（比如你初始化时创建了README文件），直接推送可能会失败。这时需要先拉取远程更改：

git pull origin master

解决可能的合并冲突后，再推送：

git push origin master

我通常会先git pull --rebase，这样提交历史会更整洁。

5. 日常开发中的Git工作流程

5.1 分支管理策略

对于小型项目，可以直接在master分支开发。但对于多人协作或复杂项目，建议使用功能分支工作流：

1. 创建新分支开发功能：

   git checkout -b feature/新功能

2. 开发完成后，提交更改：

   git add . git commit -m "实现新功能"

3. 推送到远程：

   git push origin feature/新功能

4. 在Gitee上创建Pull Request，合并到master分支

这种工作流可以保持master分支的稳定性，同时便于代码审查。

5.2 提交信息规范

好的提交信息能让项目历史更清晰。我遵循这样的格式：

类型(范围): 简要描述 详细说明（可选） 相关Issue（可选）

类型可以是：

• feat：新功能
• fix：bug修复
• docs：文档更新
• style：代码格式调整
• refactor：代码重构
• test：测试相关
• chore：构建过程或辅助工具变动

例如：

feat(用户模块): 添加用户注册功能 - 实现手机号验证注册 - 添加密码强度检查 相关：#123

5.3 使用.gitattributes统一换行符

跨平台开发时，换行符问题可能导致不必要的更改。可以在项目根目录添加.gitattributes文件：

# 设置文本文件使用LF换行符 * text=auto eol=lf # 明确指定某些二进制文件 *.png binary *.jpg binary

这样可以避免Windows和Unix系统之间的换行符问题。

6. 常见问题与解决方案

6.1 推送被拒绝

错误信息：

! [rejected] master -> master (non-fast-forward)

这通常是因为远程仓库有你本地没有的更改。解决方法：

git pull origin master # 解决可能的冲突后 git push origin master

如果确定要覆盖远程更改（谨慎使用）：

git push -f origin master

6.2 每次推送都要输入密码

如果使用HTTPS方式连接，每次推送都需要输入密码。解决方法：

1. 改用SSH方式（推荐）
2. 或者配置Git凭据缓存：

   git config --global credential.helper cache

6.3 大文件推送失败

Gitee对单个文件大小有限制（通常为100MB）。如果遇到大文件问题：

1. 使用git-lfs（大文件存储）：

   git lfs install git lfs track "*.psd" git add .gitattributes git commit -m "添加大文件跟踪"

2. 或者从仓库中删除大文件：

   git filter-branch --tree-filter 'rm -f 大文件' HEAD

6.4 误提交敏感信息

如果不小心提交了密码等敏感信息：

1. 从历史中彻底删除文件：

   git filter-branch --force --index-filter \ "git rm --cached --ignore-unmatch 敏感文件" \ --prune-empty --tag-name-filter cat -- --all

2. 强制推送到远程：

   git push origin --force --all

3. 通知所有协作者重新克隆仓库

7. Gitee的高级功能使用

7.1 Gitee Pages静态网站托管

Gitee提供类似GitHub Pages的服务：

1. 在仓库设置中启用Gitee Pages
2. 选择部署分支（通常是master或gh-pages）
3. 访问提供的xxx.gitee.io地址即可

我常用这个功能托管项目文档或个人博客。对于Vue/React项目，构建后把dist目录内容推送到指定分支即可。

7.2 使用Gitee的CI/CD

Gitee Go是Gitee提供的CI/CD服务：

1. 在项目根目录创建.gitee/.gitee.yml文件
2. 配置构建步骤，例如：

   version: '1.0' steps: - build: actions: - run: mvn clean package name: 构建项目

3. 提交后会自动触发构建

这对于自动化测试和部署非常有用。

7.3 使用Gitee的Webhooks

Webhooks可以在特定事件（如推送）发生时通知外部服务：

1. 在仓库设置中找到Webhooks
2. 添加新的Webhook，填写目标URL
3. 选择触发事件（如Push事件）

我常用这个功能实现自动部署，当代码推送到特定分支时，服务器自动拉取最新代码并重启服务。

8. 团队协作最佳实践

8.1 权限管理

Gitee提供多种权限级别：

• 所有者：拥有全部权限
• 管理员：可以管理仓库设置
• 开发者：可以推送代码
• 报告者：只能创建Issue
• 观察者：只能查看

根据团队成员的角色分配合适的权限，遵循最小权限原则。

8.2 Code Review流程

良好的Code Review能提高代码质量：

1. 开发者创建功能分支并推送代码
2. 创建Pull Request，描述变更内容
3. 其他成员审查代码，提出意见
4. 修改后再次推送，直到审查通过
5. 合并到主分支

我建议设置"必须通过Code Review才能合并"的保护规则。

8.3 Issue和项目管理

Gitee的Issue系统可以用来：

• 记录bug
• 提出新功能建议
• 跟踪任务进度

我通常会给Issue打标签（如bug、enhancement），并使用里程碑来组织版本发布。