13太保玩转github-第02太保-胆勇谨厚-本地客户端与Git/gh基本功

三套入口不是三套流程，先把基本功练成条件反射text[读者] 会用 Git，但 Desktop、命令行、gh 各记一套[痛点] 换台机器就复现不出昨天的操作[现在读] springaialibabapractice 要求本地流程可复现[读完] 能统一三入口，产出可验证的本地配置文档``````text[旧方案] 桌面点几下 + 命令行补两刀 + gh 现查现用 | v[新需求] 多维护者协作，同一仓库、同一提交规范 | v[冲突] 三套入口三套记忆，Git 状态在脑子里对不上 | v[后果] 提交混入无关文件，PR 描述现编，换台机器重来我是老李，手里维护的是 lifuchun522/springaialibabapractice。第 01 篇把仓库骨架和分支约定立住了，这一篇要解决的问题更土：同一件事，团队里三个人能用三种方式做出来，结果还不一样。《新五代史》写这位太保「胆勇过人」，又写他「谨厚」，受戒之后能长期自律。放到工具链上，胆勇是敢直接上手敲命令，谨厚是不给自己留侥幸——配置写一次、流程记一次，以后不再靠记忆救场。任务是围绕「本地客户端」把 GitHub 的产品能力落到这个仓库上：不是只看界面会点哪里，而是做完之后有可验证的配置、可复现的输出、可交接的文档。三套入口要不要统一成一条流程？这些配置该写进仓库，还是留在个人机器上？如果只有老李能跑通，这套流程算不算成立？# 01、故事周三下午，仓库要新增一个 GitHub 操作文档目录。同事按自己的习惯动手：打开 GitHub Desktop，File → Clone repository，Current branch → New branch 建了分支，改完文件在 Changes 里写了 Summary，点了 Commit，然后就停住了——他不知道 PR 在哪里建。换到另一台机器上，老李用命令行三分钟走完同一条路：clone、switch、add、commit、push、gh pr create。两件事都做成了，但没人说得清哪一步必须验证、哪一步可以随手点。当前方案是「谁的机器谁说了算」：有人用命令行，有人用桌面客户端，还有人用 IDE 内置的 Git。变化在于，githubops/NN-*教程分支要和项目自身的chapter/NN-*功能分支并行存在，仓库开始多人并行维护，靠「我记得我推过了」已经不够。冲突也在这里：Desktop 把 Git 状态藏在按钮后面，命令行把状态摆在眼前，两者本身并不冲突；真正冲突的是没人规定过哪一步用哪个入口、哪一步必须留下证据。工具越顺手，越容易在无约束的状态下各走各的。> 三入口并行> 一条线未定> 手熟非本事> 可复现才算# 02、问题旧方案在单机单人的时候毫无问题：一个人、一台机器、一套肌肉记忆，快且省事。一旦换人换机器，记忆链就断在第一步。业务影响是可感知的：PR 里混进.env、IDE 临时文件、日志；评审时间被消耗在区分「真改动」和「噪音」上；历史追溯困难，回滚时不知道该回滚哪一处。技术表现同样可观测：git status里堆着一批未跟踪的本地文件；git diff --stat显示整文件重写；本地有提交而远端没有；gh pr create因为未认证直接失败；提交信息五花八门，无法按范围过滤历史。本章要拿到的可验证完成标准：- 新克隆的仓库，按docs/github-ops/02-local-clients.md执行，能走完 clone → 分支 → 提交 → push → PR 全链路；- 提交的 diff 只包含预期文件，不出现换行符噪音；- 提交完成后git status干净；- 文档里记录的命令输出与实际执行结果一致，别人能照着复跑。这四条都能被第三方核对，不是「感觉差不多了」。> 记忆不可靠> 状态要摆明> 标准能验证> 流程才算成# 03、原理这一章只讲三个支撑后面所有操作的原理。第一，三个入口，一个内核。GitHub Desktop、git、gh 最终都作用在同一份 Git 对象库和同一套 GitHub 平台上。Desktop 是一个真正的 Git 客户端，它把工作区、暂存区、本地提交、推送这些状态可视化，但它不是 GitHub SaaS 的替代品：分支保护、PR 评审、Actions、权限都在平台那一侧。把这条边界想清楚，才不会出现「我在本地提交了，为什么没人来评审」的错觉。第二，提交的边界由暂存区决定，不由编辑器决定。git add -p允许你只暂存某一个 hunk，Desktop 的 Changes 勾选框是同一件事的图形表达。谁控制了 index，谁就决定了这次提交表达什么语义。这条原理解释了后面所有「diff 里为什么多出无关文件」的问题。第三，认证是账号级能力，仓库里不该出现凭据。gh auth login、SSH key、HTTPS 凭据管理器解决的是「你是谁」，这是一次性问题；而.env、token 文件属于内容，必须被.gitignore挡住。把这两件事分层，才能避免把密钥写进历史的灾难。反直觉判断：图形客户端用得越顺，越需要命令行。因为 GUI 把最容易出问题的那部分状态——index、远端跟踪引用、换行符转换——藏到了界面之后，而排障恰恰要从这些状态开始。> 界面遮状态> 命令见真身> 边界在暂存> 凭据不入仓# 04、架构text[输入] 一次本地改动 | v[模块] 工作区 / 暂存区 / 本地仓库 / 远端 | v[数据/状态] index、HEAD、分支引用、远端跟踪引用 | v[处理] add → commit → push → PR | v[输出] 远端分支 + Pull Request + 评审记录边界：三套入口共用同一台状态机，不能各自演一套。Desktop 覆盖的是最常用的那条路径，gh 覆盖的是仓库与 PR 级别的操作，git 覆盖其余一切。任何入口做的动作，都应该能被另外两个解释和验证。收益：一次配置、三条入口、一个结果。换机器只需要重放配置，不需要重放记忆。代价：需要先把策略定下来——默认分支名、pull.rebase的取舍、换行符策略——并且把这些策略写进仓库，而不是写进个人笔记。前期会多花一点时间。适用条件：单仓库、多维护者、走 PR 评审流程的团队。如果只有一个人且永不复现，这套约束并不划算。> 一内核三面> 同状态同源> 策略先统一> 再谈快与慢# 05、实战一次目标：跑通最小但完整的链路，并产出本章产物。环境（以你本机实际安装版本为准）：Git for Windows 或 macOS 系统 Git、GitHub Desktop、GitHub CLI（gh）。依赖：网络可访问 github.com；账号对lifuchun522/springaialibabapractice具备读写权限。第一步，全局配置，只做一次，属于账号级：bashgit config --global user.name "你的名字"git config --global user.email "你的邮箱"git config --global init.defaultBranch maingit config --global pull.rebase falsegit config --global core.autocrlf true # Windows；macOS/Linux 视团队策略取 input 或 falsegit config --list --show-origin````core.autocrlf` 必须与团队策略一致，`pull.rebase` 也要显式设定，不要让 Git 用默认行为替你决定。第二步，克隆仓库并建教程分支：bashgit clone https://github.com/lifuchun522/springaialibabapractice.gitcd springaialibabapracticegit switch -c githubops/02-local-clientsgit status示例输出：consoleOn branch githubops/02-local-clientsnothing to commit, working tree clean第三步，写 `.gitignore`，把不该进仓库的东西挡在外面：gitignore.env.env.**.loglogs/.idea/.vscode/.DS_StoreThumbs.dbtarget/build/再补一份 `.gitattributes`，把换行符从个人设置升级为仓库契约：gitattributes* text=auto eol=lf*.bat text eol=crlf*.cmd text eol=crlf*.png binary*.jpg binary第四步，GitHub Desktop 侧，菜单保持官方英文形式：- File → Clone repository：确认远端仓库地址与本地目录；- Current branch → New branch：创建 `githubops/02-local-clients`；- Changes → Summary / Description → Commit：Summary 写提交主题，Description 写动机；- Push origin：把本地提交推到远端；- Branch → Create pull request：从当前分支直达 PR 页面。第五步，命令行侧，同一条流程的另一种表达：bashgit add -pgit add docs/github-ops/02-local-clients.mdgit statusgit commit -m "docs(gh02): document desktop git and gh workflows"git push -u origin githubops/02-local-clients第六步，gh 侧的认证与 PR：bashgh auth logingh auth statusgh repo view --webgh pr create --fill````gh pr create --fill会用提交信息预填标题与正文，但它只是省去手打，最后仍然要人工确认内容再提交，自动填充不等于可以跳过评审。第七步，写产物文档docs/github-ops/02-local-clients.md，至少包含三块内容：Desktop 英文菜单到中文解释的对照表、Git 与 gh 常用命令速查、三入口等价关系表，并附上本次的验收记录。对照表示例：| Desktop 菜单（英文） | 中文解释 | 对应的 git / gh 命令 || --- | --- | --- || File → Clone repository | 文件 → 克隆仓库：把远端仓库拉成本地目录 |git clone|| Current branch → New branch | 当前分支 → 新建分支：基于当前 HEAD 建分支并切换 |git switch -c|| Changes → Commit | 变更 → 提交：把已勾选的改动写成本地提交 |git add -p+git commit|| Push origin | 推送源端：把本地提交推到 origin |git push -u origin|| Branch → Create pull request | 分支 → 创建拉取请求：从当前分支发起 PR |gh pr create --fill|验收方式：在一台干净的机器或一个全新的克隆目录上，照文档从零执行，能走到 PR 创建成功，并且git status干净、git diff --stat只有预期文件。说明：本节中的命令与界面路径来自 GitHub 官方文档（Desktop 入门见 https://docs.github.com/en/desktop/overview/getting-started-with-github-desktop ，gh 命令手册见 https://cli.github.com/manual/gh ）。具体命令输出与截图需要你在自己的环境执行后补入docs/github-ops/，未在当前环境实测的部分以下为预期结果。> 先配再动手> 一次只一事> 输出留证据> 他人能重放# 06、排查## 诊断一：Desktop 里提交成功，GitHub 上看不到现象：在 Desktop 里点了 Commit，界面提示成功，但远端分支上没有新提交。怀疑：提交只写进了本地仓库，或者被推到了另一个分支。检查：git status、git log --oneline -3、git log origin/githubops/02-local-clients --oneline -3。证据：git status输出Your branch is ahead of ‘origin/githubops/02-local-clients’ by 1 commit，本地日志比远端多一条。根因：Commit 和 Push 是两个动作。Commit 是纯粹的本地对象写入，Push origin 才是网络动作，Desktop 把它们放在两个按钮上，命令行把它们放在两条命令里。修复：点 Push origin，或者执行git push -u origin githubops/02-local-clients。**错误尝试：** 在 Desktop 里再点一次 Commit。为什么错误：Commit 是本地幂等动作，重复提交会让同一份改动变成两个提交，历史更乱；而且它完全没有触碰「没有推送」这个真正的问题。正确顺序是先读状态，再决定是推还是改。## 诊断二：只改了几行，diff 却被标成整文件重写现象：git diff --stat显示整个文件被删再加，内容其实只改了几行。怀疑：Windows 工作区的 CRLF 与仓库里的 LF 之间发生了转换。检查：git config core.autocrlf、仓库根目录是否存在.gitattributes、git diff --stat的具体行数。证据：diff 中每一行都同时出现在减号和加号里，文字内容一致，只有行尾不可见。根因：工作区使用 CRLF、仓库使用 LF，缺少统一策略时，Git 会把行尾差异当成内容差异。修复：加入.gitattributes（* text=auto eol=lf），让core.autocrlf与团队策略一致，然后执行git add --renormalize .重新规范化，并把这批规范化单独提交一次，避免和业务改动混在一起。**错误尝试：** 让每个人自己去编辑器里把换行符改成 LF。为什么错误：编辑器设置属于个人环境，不可复现也不可审计，下一个人克隆下来会再次重演同样的问题。策略必须落在仓库里。## 诊断三：gh 命令报未认证现象：执行gh pr create时提示需要先认证。怀疑：本机未登录，或者登录的 token 缺少所需权限。检查：gh auth status。证据：输出显示未登录到 github.com，或者缺少repo相关 scope。根因：gh 使用的是账号级凭据，与 Git 推送用的凭据是两套东西，登录一次不等于另一套也配好了。修复：执行gh auth login重新登录并选择需要的 scope；使用 SSH 的场景在 GitHub 网页端 Settings → SSH and GPG keys 检查公钥是否已登记，凭据本身不要写进仓库，也不要贴进文档。> 先看状态表> 再谈改代码> 强推非解法> 证据定根因# 07、优化V2 的全部改动都来自第 06 章的证据，不做无依据的加固。根因归纳成三条：状态不可见、策略不可复现、凭据与内容混在一起。修改一：把策略写进仓库。新增.gitattributes，* text=auto eol=lf，二进制文件单独声明，让换行符从个人设置变成仓库契约。修改原因：诊断二证明问题出在策略缺失，而不是某台机器。新行为：任何机器克隆后，行尾转换规则由仓库决定。验证：重新克隆后git diff --stat不再出现整文件重写。修改二：把排除规则写进.gitignore。.env、.env.、.log、logs/、.idea/、.vscode/、target/、build/一律不入仓。修改原因：诊断一暴露的git status噪音。新行为：提交后工作区干净。验证：git status输出 working tree clean。修改三：把提交边界显式化。统一用git add -p或 Desktop 的 Changes 勾选，一次提交只表达一件事；提交信息采用docs(gh02): …这类前缀，便于按范围过滤历史。修改原因：混提交让回滚和评审变贵。新行为：每个提交可以单独回滚。验证：git log --oneline中每条提交描述自洽。修改四：把三入口映射成同一张流程表，写进docs/github-ops/02-local-clients.md，Desktop 的五个菜单路径与 git、gh 命令一一对照。修改原因：诊断一的本质是入口之间没有对照关系。新行为：任选一个入口都能查到等价操作。验证：让另一位维护者只看文档完成一次贡献。修改五：把认证分层写清楚。账号级凭据（SSH key、gh token）只在 Settings 检查，不进仓库；项目级配置（.gitignore、.gitattributes）进仓库。修改原因：诊断三说明身份与内容必须分层。新行为：文档里永远不出现任何密钥。验证：对文档做一次关键字自查。以上验证方式都需要在实际环境中执行后记录真实输出，本文不提供任何推测性的性能或收益数字。> 契约进仓库> 排除进配置> 提交只一事> 换机亦如初# 08、演进```text[同一输入：一次本地改动] | +--[V1] 靠记忆选入口 / 代价：状态不可见、换机重来 | +--[V2] 契约进仓库 + 三入口映射 / 代价：需先统一策略，前期多花时间 |[Trade-off]得到：可复现、可审计、可交接失去：随手一点的自由，以及「我这台机器能跑」的侥幸边界：单仓库多维护者收益最大；个人玩具仓库不值得```逐项比较：正确性方面，V1 依赖个人记忆，V2 依赖仓库内契约，后者可以被第三方验证。稳定性方面，V2 消除了换行符与未跟踪文件带来的噪音，diff 更稳定，评审更聚焦。复杂度方面，V2 多了两个配置文件与一份文档，新人的阅读成本上升，这是明确的代价。成本方面，V2 是一次性前期投入，收益从第二位维护者加入时开始兑现。适用范围方面，适合走 PR 评审的多人仓库；单人短周期实验仓库不必套用。遗留问题方面，分支合并策略在团队层面仍需显式约定，pull.rebase只是把它显性化，并没有替你做出选择；同时 Desktop 与 gh 的版本更新可能调整菜单位置，文档需要随版本维护。> 旧法靠记忆> 新法靠契约> 得失皆明处> 边界自划清# 09、洞见## 9.1 入口可以多，流程只能有一条反直觉判断：工具越多，越应该砍流程，而不是给每个工具配一套流程。Desktop、git、gh 是三面镜子，照的是同一份状态；一旦允许它们各自为政，成本不是线性增加，而是组合爆炸。判断标准很简单：这次操作，能否用另外两个入口解释清楚？## 9.2 影响克隆结果的进仓库，影响你是谁的在账号层反直觉判断：把配置写进教程，比写进仓库更难维护。教程会过期，仓库里的.gitattributes每次克隆都会生效。凡是影响「别人克隆后得到什么」的，进仓库；凡是只影响「你是谁」的凭据、SSH key，留在账号层，在 Settings 里检查即可。## 9.3 提交边界是设计出来的，不是攒出来的git add -p与 Desktop 的勾选框表达的是同一个真相：一次提交的语义由 index 决定。提交前滚一遍变更列表，是成本最低的一次自我评审，也是后续回滚粒度的决定因素。## 9.4 排障从状态开始，不从操作开始反直觉判断：遇到问题第一反应是「再点一次、再敲一次」，往往是在制造更难回滚的历史。先看git status、git log、gh auth status，把状态读明白，操作才有方向；强制覆盖和强推通常只推迟了问题的暴露时间。> 多面不多流> 契约入仓库> 提交先设计> 排障先看态# 10、系统落地原来有什么：一个只有提交历史、没有本地操作约定的仓库，每个人一套习惯，靠记忆维持一致性。本篇新增了什么：docs/github-ops/02-local-clients.md这份本地客户端操作规范，以及其中的 Desktop 菜单对照表、Git 与 gh 命令速查、三入口等价关系表；仓库层面的.gitignore与.gitattributes契约；一条从 clone 到 PR 的三入口等价流程。分支落在githubops/02-local-clients，建议提交信息为docs(gh02): document desktop git and gh workflows。现在能做什么：任意一位维护者，在一台干净机器上按文档执行，可以独立完成一次完整贡献，并且产出的 diff 只包含预期文件，结果可被他人核对。还缺什么：分支合并策略（pull.rebase与合并方式）还没有在团队层面写死；缺少自动化守门，比如检测敏感文件是否被误提交、检查换行符规范化；缺少 PR 模板与评审清单，评审质量仍然依赖评审者的经验。下一步如何演进：把本地流程接到仓库自动化上，用 GitHub Actions 做最低限度的守门，把「靠人记得」的部分继续迁移到「靠机制保证」，让本地客户端规范从文档变成流程的一部分。> 旧仓无约定> 新约入版本> 尚缺自动化> 且行且补齐# 11、小结```textQ1 → 要统一：三个入口共用一条可验证流程，而不是三套习惯Q2 → 影响克隆结果的写进仓库，影响身份的在账号层检查Q3 → 换人按文档在干净环境重放一次，能走到 PR 创建成功就算可复现状态 → 本地三入口已收敛为一条流程，产物落在 docs/github-ops/```> 三问皆有答> 一档可重放> 流程已收敛> 余下自动化# 12、作业## 12.1 理解题：为什么说 GitHub Desktop 不是 GitHub SaaS 的替代品？参考答案：Desktop 是运行在本地的 Git 客户端，负责工作区、暂存区、本地提交与推送这一段；平台侧的分支保护、PR 评审、Actions、权限属于 SaaS 能力。二者是同一条流程的不同段落，不能互相替代。把它当成 SaaS 用，就会出现「我在本地提交了，为什么没人评审」的错觉。## 12.2 实战题：在一个全新克隆的目录里，把 clone → 分支 → 提交 → push → PR 完整走一遍，并记录输出。参考答案：git clone→git switch -c githubops/02-local-clients→ 修改文件 →git add -p→git commit -m "docs(gh02): …"→git push -u origin githubops/02-local-clients→gh pr create --fill。验收看三点：git status干净、git diff --stat只含预期文件、远端出现对应 PR。真实输出需要你自己采集并写入docs/github-ops/。## 12.3 排障题：git diff --stat显示整个文件被重写，如何定位与修复？参考答案：先看git config core.autocrlf和是否存在.gitattributes，判断是否为行尾差异；确认后用.gitattributes统一为* text=auto eol=lf，执行git add --renormalize .` 单独提交一次规范化。不要用强制覆盖或者强推来掩盖问题，那样只会把问题推给下一个人。## 12.4 架构判断题：团队里有人只用 Desktop、有人只用命令行，是否应该禁止其中一种？参考答案：不应该。要禁止的是「未被定义流程」，而不是工具本身。正确做法是把三入口映射到同一张流程表，指定每个动作的等价操作与验收点，工具选择自由、状态与流程一致。判断依据依旧是那句话：这次操作能否用另外两个入口解释清楚。> 题题问边界> 答答要证据> 手练加脑练> 功到自然成# 13、思考回到本篇的核心冲突：问题从来不是「哪个客户端更好用」，而是「同一个动作在三套入口下是否得到同一个可复现的结果」。工具的自由度越高，流程的确定性就越值钱。把影响克隆结果的配置写进仓库，把只影响身份的东西留在账号层，把每一次提交的边界显式设计出来——这三件事做完，本地客户端才真正从熟练度变成基本功。> 工具可多面> 流程须一条> 契约先落定> 功在可重放