Git 新手到团队协作与 GitHub/GitCode 指南

1. 学习目标

这份指南面向零基础，目标是让你做到：

独立使用 Git 管理本地版本。
在 VS Code 里完成日常提交、拉取、推送、解决冲突。
和团队用 GitHub / GitCode 协作开发。
知道 Git 在不同工作场景里的正确用法。

2. Git、GitHub、GitCode 的关系

Git：本地版本控制工具，装在你电脑上。
GitHub/GitCode：远程托管平台，用于协作、评审、备份。

一句话：
Git 负责"记录历史"，GitHub/GitCode 负责"远程协作"。

3. Git 可以使用在什么地方

代码开发：前端、后端、测试、脚本。
文档协作：产品文档、技术手册、会议记录。
数据与 AI：训练脚本、配置、实验记录。
运维部署：Dockerfile、K8s 配置、自动化脚本。
学习与教学：课程作业、团队实验项目。
设计资源版本管理：配合 Git LFS 管理较大文件。

不建议直接用 Git 管理：

超大视频、模型原始文件（建议对象存储或制品库）。

4. 安装与初始化（一步步）

4.1 安装 Git

下载并安装 Git。
打开终端执行：

bash 复制代码

git --version

看到版本号表示安装成功。

4.2 首次配置身份

bash 复制代码

git config --global user.name "你的名字"
git config --global user.email "你的邮箱"
git config --global init.defaultBranch main
git config --global core.autocrlf true
git config --global core.quotepath false

检查：

bash 复制代码

git config --global --list

5. 核心概念（新手必须懂）

工作区：你正在改的文件。
暂存区：准备提交的改动。
本地仓库：提交历史。
远程仓库：GitHub/GitCode 上的仓库。

标准流程：
改文件 -> add -> commit -> push

6. 基础命令（按操作顺序）

6.1 新建仓库

bash 复制代码

mkdir demo-project
cd demo-project
git init

6.2 添加文件并首次提交

bash 复制代码

echo "# Demo" > README.md
git status
git add README.md
git commit -m "chore: initial commit"

6.3 查看历史与差异

bash 复制代码

git log --oneline --graph --decorate
git diff
git diff --staged

6.4 常见撤销

bash 复制代码

git restore <文件>                  # 撤销工作区修改
git restore --staged <文件>         # 取消暂存
git commit --amend                  # 修改最近一次提交

7. VS Code 中一步步使用 Git

7.1 打开项目并识别 Git

用 VS Code 打开项目目录。
点击左侧 Source Control（源代码管理）。
如果提示"初始化仓库"，点击 Initialize Repository。

7.2 提交代码（GUI）

修改任意文件。
Source Control 中查看改动文件列表。
点击文件右侧 +（Stage Changes）。
在输入框写提交说明，例如：feat: add login form。
点击 Commit。

7.3 推送与拉取（GUI）

点击 ... 菜单。
选择 Push 推送。
选择 Pull 拉取。
也可点击左下角同步按钮 Sync Changes。

7.4 冲突处理（GUI）

Pull 后若出现冲突，打开冲突文件。
选择 Accept Current / Accept Incoming / Accept Both。
保存后重新 Stage。
再次 Commit 并 Push。

8. GitHub 配合使用（完整步骤）

8.1 配置 SSH

bash 复制代码

ssh-keygen -t ed25519 -C "你的邮箱"
cat ~/.ssh/id_ed25519.pub

把输出公钥添加到 GitHub Settings -> SSH and GPG keys。

测试：

bash 复制代码

ssh -T git@github.com

8.2 本地项目推送到 GitHub

bash 复制代码

git init
git add .
git commit -m "chore: initial commit"
git remote add origin git@github.com:用户名/仓库名.git
git branch -M main
git push -u origin main

8.3 团队 PR 流程（GitHub）

从 main 切分支：feature/xxx。
开发并提交。
推送分支：git push -u origin feature/xxx。
在 GitHub 发起 Pull Request。
根据 Review 修改并追加提交。
CI 通过后合并。

9. GitCode 配合使用（完整步骤）

GitCode 操作逻辑和 GitHub 基本一致，主要是平台界面不同。

9.1 配置 SSH

进入 GitCode 个人设置。
打开 SSH Keys 页面。
粘贴本地公钥并保存。
用平台文档中的 SSH 域名测试连通。

9.2 本地项目推送到 GitCode

bash 复制代码

git remote add gitcode git@gitcode.com:用户名/仓库名.git
git push -u gitcode main

9.3 团队 MR 流程（GitCode）

推送功能分支。
在 GitCode 发起 Merge Request。
指定审核人。
根据意见修改后再次推送。
通过后合并。

10. 同时使用 GitHub + GitCode（双远程）

10.1 配置两个远程

bash 复制代码

git remote add origin git@github.com:用户名/仓库名.git
git remote add gitcode git@gitcode.com:用户名/仓库名.git
git remote -v

10.2 双端推送

bash 复制代码

git push -u origin main
git push -u gitcode main

后续每次合并后：

bash 复制代码

git push origin main
git push gitcode main

10.3 最佳实践

统一以 main 作为发布主线。
PR/MR 只在一个平台做主审核。
另一个平台做镜像备份。
每周检查两端 main 的提交哈希一致性。

11. 其他场景：一步步操作

场景 A：你一个人开发小项目

git init 初始化。
每完成一个小功能就 add + commit。
每天结束前 push 到 GitHub/GitCode 备份。
发布版本时打标签：

bash 复制代码

git tag v1.0.0
git push origin v1.0.0

场景 B：2-5 人小团队协作

约定分支命名：feature/*、fix/*。
主分支保护，禁止直接 push。
所有改动通过 PR/MR。
至少 1 人评审通过再合并。
每天开工先 pull 更新。

常用命令：

bash 复制代码

git switch main
git pull origin main
git switch -c feature/payment
git push -u origin feature/payment

场景 C：紧急线上 Bug 修复（hotfix）

从 main 创建 hotfix/xxx。
最小改动修复问题。
补充回归测试。
快速 PR/MR 合并。
立即同步到 GitHub 与 GitCode。

bash 复制代码

git switch main
git pull origin main
git switch -c hotfix/login-null
git commit -m "fix: handle login null case"
git push -u origin hotfix/login-null

场景 D：文档团队协作（非代码）

文档按目录拆分：docs/产品/、docs/技术/。
每次只改一个主题，提交信息写清章节。
PR/MR 里描述"改动前后差异"和"影响范围"。
使用 Markdown 预览确保格式正确。

示例提交：

docs: update API auth section

场景 E：课程作业/毕业设计小组

组长建仓库并邀请成员。
每人固定自己的分支。
每周合并一次到 main。
用 issue 管任务：待办/进行中/完成。

12. 新手高频问题（带处理步骤）

Q1. push 被拒绝怎么办？

步骤：

先拉最新远程。
解决冲突。
再推送。

bash 复制代码

git pull --rebase origin main
git push origin main

Q2. 提交了不该提交的文件怎么办？

bash 复制代码

git rm --cached <文件>
echo "<文件或目录>" >> .gitignore
git add .gitignore
git commit -m "chore: remove tracked file and update ignore"

Q3. 提交信息写错怎么办？

bash 复制代码

git commit --amend -m "新的提交说明"

Q4. 冲突看不懂怎么办？

先在 VS Code 里用 Accept Both。
再人工检查逻辑是否重复或冲突。
运行项目或测试确认。
最后再提交。

13. 团队落地规范（建议直接采用）

13.1 分支命名

feature/功能名
fix/问题名
hotfix/紧急问题
release/版本号

13.2 Commit 规范

feat: 新功能
fix: 修复
docs: 文档
refactor: 重构
test: 测试
chore: 杂项

13.3 PR/MR 模板

改了什么。
为什么改。
如何验证。
风险和回滚方式。

14. 一页速查命令

bash 复制代码

# 初始化 / 克隆
git init
git clone <url>

# 提交
git status
git add .
git commit -m "message"

# 分支
git switch -c feature/xxx
git switch main
git merge feature/xxx

# 远程
git remote -v
git pull origin main
git push origin main

# 双远程
git push origin main
git push gitcode main