Git 与 GitHub 完整使用指南

0. 这是什么

Git 是一个分布式版本控制系统：它记录项目里每一次文件的改动，让你随时回退、对比、并行开发，不依赖网络就能工作。

GitHub 是一个托管 Git 仓库的云端平台，提供 Pull Request、Issues、Code Review、Actions（CI/CD）等协作功能。Git 不等于 GitHub —— Git 是工具，GitHub 是其中一个托管服务（同类还有 GitLab、Gitee、Bitbucket 等）。

版本控制简史

1. 安装与配置

1.1 安装

• Windows：下载 Git for Windows（git-scm.com），安装时勾选 "Git Bash" 与 "Add to PATH"。
• macOS：brew install git，或安装 Xcode Command Line Tools：xcode-select --install。
• Linux：sudo apt install git（Debian/Ubuntu）或 sudo dnf install git（Fedora）。

验证安装：git --version 应输出类似 git version 2.x.x。

1.2 首次配置（只需一次）

# 全局配置（对所有仓库生效）
git config --global user.name  "你的名字"
git config --global user.email "you@example.com"

# 凭据缓存，避免每次 push 都输密码
git config --global credential.helper store

# 默认分支名设为 main
git config --global init.defaultBranch main

# 中文文件名不乱码（Windows 必须）
git config --global core.quotepath false

# 换行符自动转换：提交时 CRLF→LF，检出时 LF→CRLF（Windows）
git config --global core.autocrlf true
# macOS/Linux 用这行：
git config --global core.autocrlf input

1.3 连接 GitHub（SSH 推荐）

# 1. 生成 SSH 密钥
ssh-keygen -t ed25519 -C "you@example.com"   # 一路回车

# 2. 启动 agent 并添加密钥
eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_ed25519

# 3. 复制公钥
cat ~/.ssh/id_ed25519.pub    # 复制全��输出

到 GitHub → Settings → SSH and GPG keys → New SSH key 粘贴。验证：ssh -T git@github.com，看到 Hi 用户名! 即成功。

1.4 图形化配置：编辑 ~/.gitconfig

# 常用编辑器设为 VS Code
git config --global core.editor "code --wait"

# 好看的 log 别名（装完立刻用）
git config --global alias.lg "log --oneline --graph --all --decorate"

# diff 和 merge 工具（安装相应软件后）
git config --global diff.tool vscode
git config --global difftool.vscode.cmd "code --wait --diff \$LOCAL \$REMOTE"
git config --global merge.tool vscode
git config --global mergetool.vscode.cmd "code --wait \$MERGED"

配置后 git lg 就是精简美观的图形化 log；git mergetool 用 VS Code 解决冲突。

2. 核心概念

• 工作区（Working Directory）：编辑器里直接看到的文件。
• 暂存区（Staging Area / Index）："待提交清单"，git add 把改动放进来。
• 本地仓库（Local Repository）：Git 保存历史的地方，git commit 生成一次快照。
• 远程仓库（Remote）：GitHub 上的副本，git push/pull 与它同步。

2+. Git 内部原理

理解 Git 的存储模型，很多"魔法"就变成常识了。

四种对象

Git 的核心是一个内容寻址的文件系统。每个对象都有一个 SHA-1（40 位十六进制）标识。.git/objects 里存着四类对象：

.git 目录里有什么

.git/
├── objects/        # 所有对象（blob/tree/commit/tag）
├── refs/           # 引用（heads/分支名、tags/标签、stash）
│   ├── heads/      # 本地分支指针文件
│   └── remotes/    # 远程分支指针
├── HEAD            # 当前所在分支的指针
├── index           # 暂存区的二进制文件
├── config          # 仓库级配置
├── hooks/          # Git Hooks 脚本
└── logs/           # reflog 数据

3. 单人本地工作流

3.1 初始化 / 获取仓库

git init              # 本地新建仓库
git clone git@github.com:用户名/仓库名.git     # 克隆远程仓库

3.2 日常三连

git status            # 查看状态
git add 文件名         # 文件加入暂存区
git add -A            # 所有改动（包括删除）
git commit -m "描述"   # 提交

3.3 交互式暂存（git add -p）——精准控制每次提交

不想把文件里所有改动一起提交？git add -p 逐块（hunk）确认，每次 y/n/s/e：

3.4 查看历史与差异

git log --oneline --graph --all    # 图形化美化历史
git log -p 文件名                   # 某文件每次改了什么
git log --since="2026-01-01"       # 按日期筛
git log --author="张三"            # 按作者筛
git diff                            # 工作区 vs 暂存区
git diff --staged                   # 暂存区 vs 上次提交
git show 提交号                     # 某次提交的详情

3.5 撤销与修改

4. 分支与合并

4.1 基本操作

git branch                # 列出本地分支
git switch -c 功能名       # 创建并切换
git switch 功能名          # 切换
git branch -d 功能名       # 删除（已合并）
git branch -D 功能名       # 强制删除
git push origin --delete 分��名   # 删除远程分支

4.2 合并

git switch main
git merge 功能名           # 把功能分支合并进当前

快进（fast-forward）：main 无新提交时指针直接前移，历史直线。
三方合并：双方都有新提交，创建"合并提交"。同一处被两边改 → 冲突。

4.3 解决冲突

<<<<<<< HEAD
（当前分支内容）
=======
（要合并进来的内容）
>>>>>>> 功能名

1. 编辑文件，保留正确内容，删除所有标记。
2. git add 文件（标记为已解决）。
3. git commit 或用 git merge --continue。

4.4 Rebase（变基）

git switch 功能名
git rebase main          # 把功能分支拼到 main 之后

4.5 Interactive Rebase — 历史编辑器

git rebase -i 是 Git 最强大的整理工具之一。在合并到 main 之前，你可以重新组织自己的提交历史：

# 编辑最近 3 次提交
git rebase -i HEAD~3

# 或从 main 分叉点开始
git rebase -i main

执行后弹出编辑器，每行一个提交，前面用关键字标记操作：

# 例：把 3 个"fix typo"合并成 1 个
pick abc123 feat: 新增登录页
fixup def456 fix typo
fixup ghi789 fix another typo
# → 最终只有一个干净的提交

5. 远程仓库

git remote -v                        # 查看远程
git remote add origin 地址            # 关联（origin 是默认名）
git push -u origin main              # 首次推送 + 设跟踪
git push                             # 之后直接 push
git pull                             # 拉取合并（= fetch + merge）
git pull --rebase                    # 变基式拉取（更干净）
git fetch                            # 只下载不合并
git clone 地址                       # 克隆

5.1 落后于远程时

push 被拒 → git pull --rebase → 解决冲突（如有）→ git push。

5.2 多远程仓库（Fork 项目必备）

git remote add upstream git@github.com:原作者/项目.git
git fetch upstream
git merge upstream/main      # 同步上游最新代码

6. GitHub 协作

6.1 创建仓库

1. GitHub 右上角 + → New repository。
2. 填名称，选 Public/Private，勾 Add a README file。
3. Create repository，然后 git clone。

6.2 Fork + Pull Request 标准流程

6.3 PR 要点

• 标题清晰，描述说明"做了什么 / 为什么 / 怎么测"。
• 一个 PR 只做一件事，方便 review 和回滚。
• 善用 Review 行内评论；Labels、Assignees、Reviewers。
• 用 fixes #23 / closes #23 在 PR 描述中自动关 issue。
• Draft PR：未完成时先发草稿，标记 ready 后再请求 review。

6.4 Issues、Projects、Wiki、Gist

• Issues：任务/Bug/需求。用 #编号 跨引用。可设模板（Bug Report / Feature Request）。
• Projects：看板视图管理任务流（支持表格、日历、路线图）。
• Wiki：项目文档沉淀。
• Gist：代码片段分享，自带版本管理，可嵌入博客。
• Releases / Tags：git tag -a v1.0.0 -m "发布说明" && git push --tags。
• Discussions：论坛式讨论区，适合 Q&A 和公告。

6+. GitHub CLI（gh）——在终端操作 GitHub

GitHub CLI 让你不离开终端就能完成几乎所有 GitHub 操作：

# 安装
# Windows: winget install GitHub.cli
# macOS:   brew install gh
# Linux:   sudo apt install gh

# 首次登录
gh auth login      # 选 GitHub.com → HTTPS → 浏览器登录或粘贴 token

常用命令

6++. PR 模板、CODEOWNERS 与分支保护

PR 模板

在仓库根目录创建 .github/PULL_REQUEST_TEMPLATE.md，每个 PR 自动带入：

## 变更说明
<-- 描述做了什么 -->

## 测试方法
<-- 如何验证 -->

## 关联 Issue
Closes #

## Checklist
- [ ] 已本地测试通过
- [ ] 已更新文档
- [ ] 无新增大文件

Issue 模板

创建 .github/ISSUE_TEMPLATE/ 下多个模板（Bug Report、Feature Request 等），用 YAML 格式还能做字段校验。

CODEOWNERS

.github/CODEOWNERS 定义文件/目录的所有者，PR 改动自动请求 review：

# 全局所有者
*                 @team-leads

# 前端代码归前端团队
/frontend/        @frontend-team

# CI 配置归 DevOps
/.github/workflows/ @devops-team

分支保护（Branch Protection）

在仓库 Settings → Branches → Add rule，对 main（或任何关键分支）设置：

• Require a pull request before merging：禁止直接 push，必须走 PR。
• Require approvals：至少 N 人 approve 才能合。
• Require status checks to pass：CI（Actions）全绿才能合。
• Require conversation resolution：所有 review 评论 resolved 后。
• Require branches to be up to date：PR 分支必须 rebase 到 main 最新。
• Require signed commits：所有提交需要 GPG 签名（见后文）。

7. 团队协作流程

7.1 GitHub Flow（推荐大多数团队）

原则：main 永远可部署；任何改动走分支+PR+review；合并即发布。

7.2 Git Flow

• main：生产环境，发布时 tag。
• develop：日常集成分支。
• feature/*：从 develop 切，合回 develop。
• release/*：从 develop 切，测试后合回 main 和 develop。
• hotfix/*：从 main 切，合回 main 和 develop。

7.3 Trunk-Based Development（短命分支）

所有人都往 main 开短分支（每天合，分支存活 < 1 天）。依赖特性开关（feature flag）控制未完成功能。适合高频发版的 SaaS 团队，要求测试和 CI 非常强。

7+. GitHub Actions CI/CD 入门

Actions 是 GitHub 的自动化引擎：代码 push 后自动测试、构建、部署。配置文件在 .github/workflows/*.yml。

最简示例：每次 push 自动跑测试

# .github/workflows/test.yml
name: Run Tests
on: [push, pull_request]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm ci
      - run: npm test

关键概念

常用社区 Action

自动部署示例

# .github/workflows/deploy.yml
name: Deploy
on:
  push:
    branches: [main]
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: 20 }
      - run: npm ci
      - run: npm run build
      - name: Deploy to Server
        run: |
          scp -r dist/* user@server:/var/www/html/
        env:
          SSH_KEY: ${{ secrets.SSH_PRIVATE_KEY }}

8. 进阶与急救

8.1 Git Stash

git stash                    # 藏起来
git stash -u                 # 包括未追踪文件
git stash push -m "说明"     # 带描述
git stash list               # 列表
git stash pop                # 恢复最近并删除
git stash apply stash@{1}    # 恢复指定号不删除
git stash drop stash@{1}     # 删除指定
git stash clear              # 清空

8.2 .gitignore

node_modules/
dist/
*.log
.env                          # 绝不可提交！
.DS_Store
Thumbs.db
__pycache__/
*.pyc
.idea/                         # JetBrains IDE
.vscode/settings.json          # 个人设置，团队建议忽略

8.3 Reflog — 强大的时光机

git reflog                   # 记录 HEAD 的每次移动（默认 90 天）
git reset --hard HEAD@{2}    # 回到 2 步前的状态

哪怕 reset --hard 删了提交，只要 reflog 里还有就能找回。

8.4 Cherry-Pick

git cherry-pick 提交号         # 拿某次提交到当前分支
git cherry-pick A..B          # 拿 A 到 B 之间所有提交（不含 A）
git cherry-pick --continue    # 解决冲突后继续

8.5 清理大文件

pip install git-filter-repo
git filter-repo --path 大文件.tar.gz --invert-paths

8.6 常见错误速解

8+. Git Bisect / Worktree / Blame

Git Bisect — 二分法定位 Bug 引入点

项目有几百次提交，某个 bug 不知道从哪次引入的：

git bisect start              # 开始二分
git bisect bad HEAD           # 当前版本有 bug
git bisect good v1.0.0        # v1.0.0 没问题
# Git 自动帮你 checkout 到中间版本，你去验证
# 如果这个版本有问题 → git bisect bad
# 如果没问题       → git bisect good
# 重复几次，Git 定位到肇事提交
git bisect reset              # 结束二分

还能自动化：

git bisect start HEAD v1.0.0
git bisect run npm test       # 每次 checkout 后自动跑测试

Git Worktree — 同时开发多个分支

不用来回 stash/switch，一个仓库同时开多个工作目录：

# 新增一个 worktree，主仓库切到 main，新目录切到 feature-a
git worktree add ../项目-feature feature-a

# 查看所有 worktree
git worktree list

# 删除 worktree
git worktree remove ../项目-feature

Git Blame — 追踪每一行代码的来源

git blame 文件名               # 每行代码是谁、哪次提交改的
git blame -L 100,120 文件名    # 只看 100-120 行
git blame -L '/func main/' 文件名  # 从 func main 开始看
git blame --since="2 weeks ago" 文件名  # 只看最近两周的改动

在 VS Code 里安装 GitLens 插件，鼠标悬停就能看到 blame 信息，更直观。

8++. Git Hooks — 自动化质量关卡

Hooks 是 Git 事件触发执行的脚本，在 .git/hooks/ 目录。常用：

推荐工具：pre-commit 框架

手动管理 hooks 脚本很麻烦，用 pre-commit 框架（Python 工具）统一管理：

# 安装
pip install pre-commit

# 创建 .pre-commit-config.yaml
repos:
  - repo: https://github.com/pre-commit/pre-commit-hooks
    rev: v4.6.0
    hooks:
      - id: trailing-whitespace    # 去掉行尾空格
      - id: end-of-file-fixer      # 文件末尾加空行
      - id: check-yaml             # 检查 YAML 语法
      - id: detect-private-key     # 检测是否误提交私钥
      - id: check-added-large-files # 拒绝大文件

  - repo: https://github.com/commitizen-tools/commitizen
    rev: v3.27.0
    hooks:
      - id: commitizen             # 校验 commit message 格式

# 安装到仓库
pre-commit install          # 安装 pre-commit hook
pre-commit install --hook-type commit-msg  # 安装 commit-msg hook

# 手动跑一遍（检查所有文件）
pre-commit run --all-files

8+++. Git 别名、GPG 签名与大文件

Git Aliases — 定制你的快捷方式

git config --global alias.co checkout
git config --global alias.br branch
git config --global alias.st status
git config --global alias.lg "log --oneline --graph --all --decorate"
git config --global alias.unstage "restore --staged ."
git config --global alias.uncommit "reset --soft HEAD~1"
git config --global alias.amend "commit --amend --no-edit"
git config --global alias.fixup "commit --fixup"

之后 git co = checkout，git lg = 图形 log，git unstage = 全部移出暂存区。

GPG 签名提交 — 防身份伪造

Git 的 user.name/user.email 任何人都可以随便填。GPG 签名能证明提交确实是你本人做的。

# 1. 安装 GPG：brew install gpg / apt install gpg / 下载 Gpg4win
# 2. 生成密钥
gpg --full-generate-key     # 选 RSA，4096 位，填写姓名和邮箱

# 3. 列出密钥，拿到 KEY ID（如 3AA5C34371567BD2）
gpg --list-secret-keys --keyid-format LONG

# 4. 配置 Git
git config --global user.signingkey 你的KEY_ID
git config --global commit.gpgsign true   # 每次提交自动签名
git config --global tag.gpgsign true      # 每次 tag 自动签名

# 5. 导出公钥并上传到 GitHub
gpg --armor --export 你的KEY_ID    # 复制输出到 GitHub → Settings → GPG keys

Git LFS — 管理大文件

Git 不擅长管大文件（视频、模型权重、PSD、数据集）。Git LFS 在仓库里只存指针，大文件存在 LFS 服务器。

# 安装（Windows/macOS 需额外安装，Linux: sudo apt install git-lfs）
git lfs install

# 追踪文件类型
git lfs track "*.psd"
git lfs track "*.mp4"
git lfs track "models/*.bin"

# 提交 .gitattributes（git lfs 自动生成的）
git add .gitattributes
git commit -m "chore: 配置 Git LFS"

# 之后正常 add / commit / push 即可

GitHub 免费额度：1GB 存储 + 1GB/月 带宽，超了需购买 data pack。

9. 图形化工具对比

命令行是核心，但图形化工具在可视化分支、解决冲突、看 diff 时有巨大优势。

10. 最佳实践

1. 频繁小提交，而不是攒一大坨。每个提交一个逻辑单元。
2. 写有意义的 commit message。用 Conventional Commits 规范。
3. 永远通过分支 + PR 改动 main，至少一人 review。
4. push 前先 pull（或 fetch），避免冲突堆积。
5. .gitignore 从第一天就建好。尤其是 .env 和构建产物。
6. 不对公共历史做 rebase / reset --hard。
7. README 写清楚：项目是什么、怎么装、怎么跑、怎么贡献。
8. 善用 .gitattributes（* text=auto）避免换行符跨平台差异。
9. 功能分支合并前用 rebase -i 整理历史。
10. 开启分支保护（必须 PR + review + CI 绿）。
11. 用 pre-commit 做自动化检查���lint、密钥泄露检测）。
12. 重要仓库开启 GPG 签名提交。
13. 大文件用 Git LFS，别直接放进仓库。
14. CI 红线：PR 上 CI 失败的提交绝不合并。

11. 实战场景演练

场景 1：多人同时改同一文件

场景 2：hotfix 紧急修复

# 1. 从 main 最新切 hotfix 分支
git switch main && git pull
git switch -c hotfix/login-crash

# 2. 修复 bug，提交
git add . && git commit -m "fix: 修复登录页崩溃"

# 3. push 并开 PR
git push -u origin hotfix/login-crash
gh pr create --title "fix: 修复登录页崩溃" --body "紧急修复，线上已挂"

# 4. PR 合入后，把修复同步回 develop（如果用 Git Flow）
git switch develop && git pull
git merge hotfix/login-crash   # 或 git cherry-pick 具体提交
git push

场景 3：提交了不该提交的密钥——如何补救

# 1. 如果还没有 push：
git reset --soft HEAD~1        # 撤销提交保留改动
# 修改代码去掉密钥，重新 commit

# 2. 如果已经 push 且只有你知道（私有仓库、没有 PR）：
git reset --soft HEAD~1
git commit --amend    # 去掉密钥后改提交
git push --force-with-lease

# 3. 如果已经 push 到公开仓库或有多个协作者：
pip install git-filter-repo
git filter-repo --path .env --invert-paths
git push --force --all
# ⚠️ 通知所有协作者：立即重新 clone，旧的本地仓库全部作废

场景 4：回顾项目一周的变化

# 本周所有提交
git log --since="1 week ago" --oneline

# 每个人的贡献量
git shortlog -sn --since="1 week ago"

# 本周哪些文件改动最多
git diff --stat HEAD '@{1 week ago}'

# 查看自己这周做了什么
git log --author="你的名字" --since="1 week ago" --oneline

12. 速查表