工业通信与网络研究课题组 — Gitee 组织使用教程

本文档面向课题组成员，介绍 Gitee 组织的使用方法、Git 基本操作以及仓库管理流程。

目录

1. 组织概览
2. 加入组织
3. Git 基本使用
4. 仓库创建与管理
5. 协作开发流程
6. 常见问题

1. 组织概览

课题组在 Gitee 上创建了一个组织（Organization），用于集中管理所有科研代码、实验脚本、文档及项目资源。

组织内的角色

2. 加入组织

2.1 注册 Gitee 账号

1. 访问 https://gitee.com，点击右上角 注册。
2. 使用学校邮箱或常用邮箱完成注册。
3. 建议将 Gitee 用户名 设为 姓名-拼音 或 学号 等易识别的格式，方便管理员审核。

2.2 申请加入组织

有两种方式：

方式一：通过邀请链接

管理员通过组织后台生成邀请链接，发送给成员。成员点击链接后确认加入即可。

方式二：主动申请加入

1. 登录 Gitee，在顶部搜索栏中搜索组织的名称。
2. 进入组织主页，点击右上角 加入组织 按钮。
3. 填写申请备注（建议注明：姓名、年级、研究方向），等待管理员审批。

2.3 管理员审批

管理员收到申请后：

1. 进入组织主页 → 管理 → 成员管理。
2. 找到待审批成员，点击 通过 并分配适当角色。

3. Git 基本使用

3.1 安装 Git

• Windows：下载 Git for Windows，安装后在开始菜单找到 Git Bash。
• Linux：sudo apt install git（Ubuntu/Debian）或 sudo yum install git（CentOS）。
• macOS：brew install git 或通过 Xcode Command Line Tools 安装。

安装完成后设置用户信息：

git config --global user.name "你的姓名"
git config --global user.email "你的邮箱@example.com"

3.2 SSH 密钥配置（推荐）

使用 SSH 方式可以避免每次操作都输入密码。

# 生成 SSH 密钥
ssh-keygen -t ed25519 -C "你的邮箱@example.com"

# 查看公钥内容
cat ~/.ssh/id_ed25519.pub

将输出的公钥内容复制到 Gitee：

Gitee 右上角头像 → 设置 → SSH 公钥 → 添加公钥

验证是否配置成功：

ssh -T git@gitee.com

若返回 Hi xxx! You've successfully authenticated... 即表示配置成功。

3.3 常用 Git 命令

克隆仓库

# HTTPS 方式
git clone https://gitee.com/组织名/仓库名.git

# SSH 方式（推荐）
git clone git@gitee.com:组织名/仓库名.git

日常工作流

# 查看当前状态
git status

# 拉取远程最新代码（每次开始工作前执行）
git pull

# 添加文件到暂存区
git add 文件名          # 添加单个文件
git add .              # 添加所有修改

# 提交到本地仓库
git commit -m "提交说明"

# 推送到远程仓库
git push

分支操作

# 查看所有分支
git branch -a

# 创建并切换到新分支
git checkout -b 新分支名

# 切换回主分支
git checkout master

# 合并分支
git merge 要合并的分支名

# 删除本地分支
git branch -d 分支名

查看历史与差异

# 查看提交历史
git log --oneline

# 查看文件修改内容
git diff

# 查看某个文件的修改历史
git log -p 文件名

撤销操作

# 撤销工作区的修改（未 add）
git checkout -- 文件名

# 撤销暂存区（已 add，未 commit）
git reset HEAD 文件名

# 撤销上一次提交（已 commit，未 push）
git reset --soft HEAD~1

3.4 Git 仓库中各类文件用途

3.5 .gitignore 常用模板

以下是一个通用的 .gitignore 模板：

# 编译产物
*.o
*.exe
*.dll
*.so
*.out
build/
dist/

# Python
__pycache__/
*.py[cod]
*.egg-info/
.venv/
env/

# IDE / 编辑器
.idea/
.vscode/
*.swp
*.swo

# 系统文件
.DS_Store
Thumbs.db

# 数据文件（根据需要调整）
*.csv
*.xlsx
*.dat
*.pcap

# 密钥与敏感信息
.env
*.pem
*.key

注意：实验数据、密钥文件、大型二进制文件等不应提交到 Git 仓库。大型文件可使用 Gitee 的 Release 附件 或 Git LFS 管理。

4. 仓库创建与管理

4.1 创建仓库

1. 进入组织主页，点击 + 新建仓库。
2. 填写仓库信息：

3. 点击 创建。

4.2 开源 vs 闭源

开源许可证选择建议

• MIT License — 最宽松，允许任何用途，适合工具类项目。
• Apache 2.0 — 要求保留版权声明和变更说明，适合较大项目。
• GPL 3.0 — 衍生作品必须同样开源，适合希望保持开源生态的项目。
• 不添加 LICENSE — 默认保留所有权利，闭源仓库可不添加。

建议策略

已发表论文配套代码 / 通用工具 → 开源（Public）+ MIT License
未发表研究 / 含敏感数据    → 闭源（Private）

4.3 仓库命名规范

建议统一命名格式：

<研究方向>-<项目名称>

示例：

• icn-industrial-protocol-analysis
• icn-network-simulation
• icn-edge-computing-framework
• icn-opcua-implementation

4.4 仓库权限管理

管理员可以在仓库 管理 → 仓库成员管理 中设置成员权限：

一般建议：

• 课题组负责人 / 项目负责人 → 管理员
• 参与开发的研究生 → 开发者
• 本科生 / 实习生 / 外部协作者 → 报告者（按需提升）

4.5 仓库设置建议

创建仓库后，建议完成以下设置：

1. 设置默认分支：管理 → 基本设置 → 默认分支（建议使用 master 或 main）。
2. 开启/关闭 Wiki：根据需要开启 Wiki 功能用于存放详细文档。
3. 分支保护：对主分支设置保护规则（禁止强制推送、要求 PR 审核等）。
4. Webhook：如需与 CI/CD 或通知系统对接，可配置 Webhook。

5. 协作开发流程

5.1 推荐的分支策略

master（主分支）    —— 稳定版本，只通过合并请求合并
  └── develop（开发分支） —— 日常开发
       └── feature/xxx（功能分支） —— 具体功能开发

5.2 协作流程示例

场景：开发一个新功能

# 1. 拉取最新代码
git checkout develop
git pull

# 2. 创建功能分支
git checkout -b feature/new-protocol-parser

# 3. 编写代码并提交
git add .
git commit -m "feat: add new protocol parser module"

# 4. 推送到远程
git push -u origin feature/new-protocol-parser

然后在 Gitee 上创建 Pull Request（合并请求）：

1. 进入仓库页面 → Pull Requests → + 新建合并请求。
2. 选择源分支 feature/new-protocol-parser → 目标分支 develop。
3. 填写 PR 描述，请求团队成员 Review。
4. 审核通过后合并，删除功能分支。

5.3 Commit 提交规范

建议使用语义化提交信息：

<类型>: <简要描述>

类型：
  feat     新功能
  fix      修复 Bug
  docs     文档修改
  style    代码格式调整（不影响逻辑）
  refactor 重构
  test     测试相关
  chore    构建工具、依赖更新等

示例：

feat: add Modbus TCP protocol parser
fix: fix buffer overflow in packet decoding
docs: update README with installation instructions

5.4 处理代码冲突

当多人修改同一文件时可能出现冲突：

git pull                      # 拉取远程更新，可能提示冲突
# 手动编辑冲突文件，解决 <<<<<<< 和 >>>>>>> 标记
git add 冲突文件
git commit -m "fix: resolve merge conflicts"
git push

6. 常见问题

Q1: push 时提示 rejected？

远程有新的提交，本地落后于远程。先 git pull 拉取更新后再推送。

Q2: 如何撤销已推送到远程的提交？

# 方法一：新增一个反向提交（推荐，安全）
git revert <commit-hash>
git push

# 方法二：回退本地并强制推送（危险，仅在自己的分支上使用）
git reset --hard <commit-hash>
git push -f

Q3: 如何克隆特定分支？

git clone -b 分支名 git@gitee.com:组织名/仓库名.git

Q4: 文件过大无法推送？

Gitee 单文件限制 100MB。解决方案：

• 将大文件加入 .gitignore
• 使用 Git LFS 管理大文件
• 通过 Gitee Release 上传附件

Q5: 误提交了敏感信息怎么办？

1. 立即修改密码/密钥。
2. 使用 git filter-branch 或 BFG Repo-Cleaner 清除历史。
3. 联系 Gitee 支持协助处理。

Q6: 如何迁移 GitHub 仓库到 Gitee？

1. Gitee 右上角 + → 导入已有仓库。
2. 输入 GitHub 仓库 URL，选择目标组织，点击导入。

附录：实用资源

本文档由工业通信与网络研究课题组维护。如有疑问或建议，请联系组织管理员。