开发速查

主题

Git 实战手册（GUI 用户视角：VS Code + GitHub Desktop） ​

提交规范（团队约定） ​

  • 语言：中文
  • 格式：<类型>: <描述>，类型与描述之间用半角冒号 + 空格（可加作用域 <类型>(模块): <描述>）
  • 描述：说明"做了什么 / 为什么"，避免"改了点东西""修复bug"这类废话
类型含义适用场景示例
feat新功能新增需求 / 页面 / 接口feat(订单): 新增导出 Excel
fix修缺陷修复 bug、异常fix: 修复分页越界崩溃
style格式不影响逻辑的改动（缩进、空格、格式化）style: 统一缩进为 2 空格
refactor重构不改行为的内部结构优化refactor: 抽取公共请求方法
docs文档改注释、README、文档docs: 补充接口鉴权说明
test测试增删改测试用例test: 补充登录边界用例
chore杂务构建、依赖、配置等chore: 升级 vite 到 5.x

示例对比：

  • ❌ 修复了登录的问题
  • ✅ fix(登录): 验证码校验失败导致无法登录

GUI 提示：VS Code 提交框、GitHub Desktop 都只填一行消息，按上面格式写即可；GitLens 提交时也能直接套用。

一、先搞懂「四个区」（看懂这个，后面全通） ​

工作区(改代码) ──add──> 暂存区 ──commit──> 本地仓库 ──push──> 远程仓库
                        <─reset──          <─pull────

第一个该装的插件：GitLens。每行代码显示谁/何时改的（blame），提交历史、对比、stash 都比原生强，是 GUI 用户的命令行替代品。

1.5 GUI 工具分工：VS Code 暂存 + GitHub Desktop 提交 ​

先分清「暂存」≠「提交」：

改文件 → 点 +（暂存，进绿色"已暂存"区）→ 点 ✓（提交，才生成一条记录）
  • 暂存（add）：只是把改动放进暂存区（中间区），不产生提交记录，随时可取消
  • 提交（commit）：把暂存区内容固化，生成一条提交记录

GitHub Desktop 的默认特性——没有"单独暂存"这一步：

  • 左边列表显示的是未暂存的改动（蓝色对勾 = 该文件有变更，不是已暂存）
  • 顶部只有 Changes / History，没有 Staged / Unstaged 分区
  • 点 Commit 按钮时，GitHub Desktop 一次性把全部未暂存改动"暂存 + 提交"
  • 所以「攒着不提交」= 别点 Commit（改动一直停在未暂存列表）；但**"从一堆里挑几个文件单独暂存"它做不到**

推荐的 GUI 分工（这套最顺）：

需求用哪个怎么操作
逐文件暂存 / 取消暂存（挑几个 add）VS Code源代码管理面板，文件上点 +（暂存）/ −（取消）；绿区 = 已暂存
检查暂存区里到底存了什么VS Code绿区（Staged Changes）看得最清楚
攒改动先不提交任选停在未暂存 / 已暂存区都行，别点 Commit
最终提交（写规范 message）GitHub Desktop填 Summary → Commit 全部
拣选某个提交到当前分支GitHub Desktop右键目标提交 → Cherry-Pick

一句话：VS Code 管"暂存"（精细控制），GitHub Desktop 管"提交 + 拣选"。两者搭配，日常最省心。

二、文件名大小写设置 ​

Windows 的问题 ​

Windows 文件系统大小写不敏感（EditQuail 和 editquail 指向同一个文件夹），但 Git 区分大小写。如果不配置，本地改大小写后 Git 不识别为"重命名"，提交后别人 pull 下来大小写对不上 → import 404 → 反复横跳。

设置 + 主流方案 ​

bash
# 1. 开启 Git 大小写敏感（推荐，全局设一次永久生效）
git config --global core.ignorecase false

# 2. 检查当前值
git config --get core.ignorecase   # 返回 false 表示已开启

主流方案对比：

  • core.ignorecase false（推荐）：让 Git 区分文件名大小写，提交时正确记录改名。Windows 本地文件系统仍不区分，但 Git 仓库层面不会混淆。
  • core.ignorecase true（Windows 默认）：Git 不区分大小写，大小写改动在 Git 里"看不见"，容易出问题。
  • 团队约定：统一全小写命名组件/目录，从源头避免冲突。

已有冲突怎么修 ​

仓库里已同时存在 EditQuail 和 editquail 时，用 git mv 两步重命名强制修正，并通知队友清理本地残留：

bash
# 1. 两步重命名（借临时名让 Git 识别改动）
git mv src/components/EditQuail src/components/_tmp_editquail
git mv src/components/_tmp_editquail src/components/editquail
git commit -m "chore: 统一组件目录大小写为 editquail"

# 2. 队友拉取后，清掉本地残留的大写目录
git rm --cached src/components/EditQuail 2>/dev/null
git checkout -- .
# 若本地仍有 EditQuail 文件夹残留，直接删掉后重新 pull

四、Fork 模式（给无 push 权限的仓库贡献代码） ​

两个 remote：origin = 你 Fork 的副本（可读写）；upstream = 原仓库（只读，用来同步）。

bash
# 首次：Fork 后克隆自己的副本，并关联原仓库（只做一次）
git clone <你fork的地址>
git remote add upstream <原仓库地址>      # git remote -v 确认 origin + upstream

# 开发：切分支改完，推到【自己的 fork】
git checkout -b feature/xxx
git push origin feature/xxx               # 然后去 GitHub 点 New Pull Request
                                             #   选 upstream/main ← origin/feature/xxx

# 提 PR 前同步上游（避免落后/冲突）
git fetch upstream
git merge upstream/main                   # 或 git rebase upstream/main
git push origin feature/xxx               # PR 自动更新

# 长期维护：让 fork 的 main 追上原仓库
git checkout main && git fetch upstream && git merge upstream/main && git push origin main

五、附录：救场命令速查（按场景） ​

GUI 搞不定时来这里查，按"想干什么"找。

bash
# —— 看状态 ——
git status                      # 当前状态
git log --oneline --graph -10   # 简洁历史图
git reflog                      # 所有操作记录（救命用）

# —— 暂存与提交 ——
git add <file> / git add .      # 暂存
git commit -m "feat: xxx"       # 提交
git commit --amend --no-edit    # 改最近一次提交

# —— 分支 ——
git branch -a                   # 所有分支（含远程）
git checkout -b feature/xxx     # 新建并切
git branch -d feature/xxx       # 删本地分支
git push origin --delete xxx    # 删远程分支

# —— 拉取与合并 ——
git pull                        # = fetch + merge
git merge <branch>              # 合并
git merge --abort               # 放弃本次合并
git cherry-pick <hash>          # 挑提交（同仓库内）
git -C "<src>" format-patch -1 <hash> --stdout > x.patch   # 跨仓库：导补丁
git -C "<dst>" am x.patch                                  # 跨仓库：贴补丁

# —— 暂存改动 ——
git stash / git stash pop       # 收起 / 恢复

# —— 大小写配置 ——
git config --global core.ignorecase false   # 开启大小写敏感（推荐）

六、术语速查 ​

术语含义
stage / 暂存add 到暂存区，准备提交
commit把暂存区快照存入本地仓库
push / pull推到远程 / 拉取远程到本地
fetch只下载远程更新，不合入（pull = fetch + merge）
merge合并两分支（保留分叉历史）
rebase把当前分支提交"搬"到目标之后（线性历史，勿对共享分支用）
conflict冲突——两人改同一行，手动解决
cherry-pick挑某次提交搬到当前分支（同仓库用命令，跨仓库用 patch）
format-patch把 commit 导成补丁文件（跨仓库搬运第一步）
am把补丁贴入当前仓库，生成等价的新 commit（跨仓库搬运第二步）
reflog本地操作记录（救命日志）
fast-forward快进合并（目标分支直接前移，无合并提交）

© 2026 开发速查