tags:

GitHub 协作入门指南

面向新协作者的 GitHub 核心概念 + 全套实操流程，以 content 仓库为例演示文件的增删改操作。

一、GitHub 核心概念

🗂️ Repository（仓库）

仓库是项目的"根容器"，包含所有代码、文档、历史记录。

🌿 Branch（分支）

分支是从某个提交节点"分叉"出来的独立开发线，互不干扰。

分支类型 用途
main / master 主分支，生产级别代码，受保护
dev 集成测试分支，日常开发合流到这里
feature/xxx 功能分支，单个功能一个分支
fix/xxx 修复分支，针对某个 bug
release/xxx 发布分支，上线前的候选

常用操作：

git branch                    # 查看所有本地分支
git checkout -b feature/add-intro   # 新建并切换到功能分支
git checkout main             # 切换回主分支
git branch -d feature/add-intro     # 删除已合并的分支

📌 Commit（提交）

Commit 是一次"保存快照"，记录"改了什么"和"为什么改"。

git add 文件名        # 暂存
git add .            # 暂存所有变更
git commit -m "feat: 新增简介章节"   # 提交，附说明
git log --oneline    # 查看历史提交

Commit 消息规范（推荐）：

feat: 新功能
fix: 修复 bug
docs: 文档变更
chore: 构建/工具/配置类变更
refactor: 重构（不改功能）

🔀 Pull Request（PR）

PR 是"请求将你的分支合并到目标分支"的正式流程。

PR 包含：

典型 PR 流程：

feature/add-intro  →  (PR)  →  dev  →  (PR)  →  main

🐛 Issue（议题）

Issue 是任务追踪系统，用于记录 Bug、需求、讨论。

用途 示例
Bug 报告 [BUG] 点击按钮无响应
功能需求 [FEAT] 增加暗色模式
讨论 [DISCUSS] 目录结构规划
任务 [TASK] 整理 README

Issue 可以：

🍴 Fork vs Clone

操作 说明
Fork 在自己账号下复制一份仓库，适合无直接写权限时贡献代码
Clone 把仓库克隆到本地，用于本地开发

👥 Collaborator（协作者）

仓库 Owner 可在 Settings → Collaborators 邀请协作者，赋予 Read / Write / Admin 权限。

协作者有直接 push 权限，不需要 Fork，直接克隆后在分支上工作即可。

二、协作者完整操作流程

以 content 仓库为例，演示新增、修改、删除文件的全套流程。

🔧 前置准备（仅首次）

# 1. 克隆仓库到本地
git clone https://github.com/your-org/content.git
cd content

# 2. 配置身份
git config user.name "你的名字"
git config user.email "you@example.com"

# 3. 确认远端
git remote -v
# 输出：origin  https://github.com/your-org/content.git

✅ 操作一：新增文件

场景： 在 articles/ 目录下新增一篇文章 hello-world.md

# Step 1：从最新 main 拉取，创建功能分支
git checkout main
git pull origin main
git checkout -b feature/add-hello-world

# Step 2：创建新文件
mkdir -p articles
cat > articles/hello-world.md << 'EOF'
# Hello World

这是第一篇文章。
EOF

# Step 3：暂存并提交
git add articles/hello-world.md
git commit -m "feat: 新增 hello-world 文章"

# Step 4：推送到远端
git push origin feature/add-hello-world

# Step 5：在 GitHub 上创建 PR
# 浏览器打开：https://github.com/your-org/content
# 点击 "Compare & pull request"
# 填写 PR 标题和描述，提交

PR 合并后，同步本地：

git checkout main
git pull origin main
git branch -d feature/add-hello-world   # 清理已合并分支

✏️ 操作二：修改文件

场景： 修改 articles/hello-world.md 的内容

# Step 1：新建修改分支
git checkout main && git pull origin main
git checkout -b fix/update-hello-world

# Step 2：修改文件
echo "\n## 补充章节\n\n这是后来添加的内容。" >> articles/hello-world.md

# 或用编辑器直接修改
# code articles/hello-world.md

# Step 3：查看变更
git diff articles/hello-world.md

# Step 4：提交
git add articles/hello-world.md
git commit -m "docs: 为 hello-world 补充章节内容"

# Step 5：推送并创建 PR
git push origin fix/update-hello-world

🗑️ 操作三：删除文件

场景： 删除不再需要的 articles/draft.md

# Step 1：新建删除分支
git checkout main && git pull origin main
git checkout -b chore/remove-draft

# Step 2：删除文件
git rm articles/draft.md

# 或先手动删除再 git add：
# rm articles/draft.md
# git add articles/draft.md   ← git add 能感知到删除

# Step 3：确认状态
git status
# 输出：deleted: articles/draft.md

# Step 4：提交
git commit -m "chore: 移除废弃的 draft 文章"

# Step 5：推送并创建 PR
git push origin chore/remove-draft

🔄 完整操作流程图

main(最新) 
  │
  ├─ git checkout -b feature/xxx     ← 新建分支
  │
  │  在本地做增删改 + git add + git commit
  │
  └─ git push origin feature/xxx     ← 推送到远端
       │
       └─ GitHub 上创建 PR
            │
            ├─ Code Review / CI 检查
            │
            └─ Merge 合并进 main
                 │
                 └─ git pull origin main（同步本地）

⚠️ 常见问题

Q: push 时提示"rejected"怎么办？

# 可能是 main 有新提交，先合并
git pull origin main --rebase
git push origin feature/xxx

Q: 如何撤销最后一次 commit（还没 push）？

git reset --soft HEAD~1   # 撤销 commit，保留文件变更

Q: 如何解决合并冲突？

git pull origin main
# 手动编辑冲突文件，找到 <<<< ==== >>>> 标记并处理
git add 冲突文件
git commit -m "fix: 解决合并冲突"

三、快速参考卡

操作 命令
克隆仓库 git clone <url>
新建分支 git checkout -b <branch>
查看状态 git status
暂存文件 git add <file> / git add .
提交 git commit -m "message"
推送 git push origin <branch>
拉取更新 git pull origin main
查看历史 git log --oneline
删除文件 git rm <file>
查看差异 git diff

source: https://docs.github.com/en/get-started
适用于 content 仓库协作者入门培训