简介面向GitHub初学者的PDF操作指南旨在帮助开发者快速理解这一领先的代码托管与协作平台掌握用Git进行版本控制和团队开发的基础方法。压缩包内为1个PDF文件整包容量仅91KB轻量便携方便随时查阅。教程以清晰的分步讲解系统覆盖了从创建账户、新建仓库、克隆项目到提交更改、创建分支、合并请求的完整流程并说明了如何通过Issue跟踪问题和展开团队讨论以及参与开源项目贡献的具体方式。读者可以借助这些操作在云端备份代码、维护版本历史、与同伴协同修改避免文件混乱和冲突也能根据公共仓库和私有仓库的特点选择合适的管理策略。目前已有3458人学习适合正在入门Git/GitHub、希望规范代码管理习惯的开发者。1. GitHub 使用教程 PDF一份能离线查、照着敲就能跑通的实战手册GitHub 是今天开发者绕不开的平台但很多人第一次打开它时是懵的满屏英文、一堆按钮、clone 和 push 也不知道会不会覆盖别人代码。教程 PDF 的形式正好解决两个最实际的需求一是能离线随时查不用每次卡在网页加载上二是从建仓库到提 Pull Request 有一条完整的操作链路照着敲就行。这篇文章就把这条链路拆开讲清楚适合刚接触 GitHub 的新手也适合用过但没系统梳理过细节的开发者。你会发现GitHub 真正值钱的不只是存代码而是把「一个人写代码」变成「一群人协作」的那套流程。2. 吃透 GitHub 的四个核心概念仓库、分支、提交与 Pull Request很多人卡在 GitHub 入门不是因为命令记不住而是脑子里没有建立模型。GitHub 上的一切操作几乎都围绕仓库、分支、提交、Pull Request 这四个概念展开。先把它们的关系弄清楚再记命令就顺了。2.1 仓库与远端先搞懂本地和 GitHub 上的双重存在仓库Repository是一个项目的完整目录包括源代码、文档、配置文件以及 Git 自动记录的每一次修改历史。用 Git 在本地初始化一个目录后这个目录就成了本地仓库GitHub 上那个同名仓库则是远端仓库。日常开发中绝大部分操作在本地完成GitHub 承担的是备份、协作和发布入口的角色。理解「本地和远端是两个独立副本」很重要。很多新手以为在 GitHub 网页上改个文件本地就会自动同步实际上两者不会自动通信必须显式执行 push推送本地到远端或 pull拉取远端到本地。这个模型一旦建立后面所有命令都有了解释框架。# 查看当前项目的远端地址配置 git remote -v # 添加远端地址origin 只是习惯命名可以改 git remote add origin gitgithub.com:你的用户名/仓库名.gitgit remote -v会输出两行分别对应 fetch拉取和 push推送的地址。如果项目是从 GitHub 上 clone 下来的这行命令会直接显示远端地址如果是本地新建的仓库则需要手动添加。origin是约定俗成的默认命名不代表任何特殊含义你也可以叫github只是所有人都习惯用origin保持惯例能省去协作时的沟通成本。关于地址格式多说一句。https://github.com/用户名/仓库名.git和gitgithub.com:用户名/仓库名.git都能用。前者走 HTTPS 协议推送时需要输入用户名和令牌现在 GitHub 已不支持密码直接推送后者走 SSH 协议只要配好密钥推送全程无需重复认证。我的建议是新机器直接配 SSH省掉后续认证的麻烦。2.2 分支模型从 main 拉出特性分支再合回去分支是 Git 最聪明的设计。它相当于在某个提交点上切出一条平行线你在分支上的操作不会影响主线main等代码稳定后再合并回去。团队协作的标准姿势是每个人都从最新的 main 拉一条特性分支各自开发最后通过 Pull Request 审查合并。# 切换到 main 分支并拉到最新 git checkout main git pull origin main # 从当前 main 创建并切换到一个新分支 git checkout -b feature/login # 查看当前所有分支带 * 的是所在分支 git branch -agit checkout -b feature/login是git branch feature/login和git checkout feature/login两步合并的简写创建分支的同时切换过去。分支名的命名规范我一般建议用feature/新功能、fix/缺陷修复、docs/文档作为前缀后面跟简短描述。这个约定让团队在查看分支列表时能一眼看出每条分支的意图。分支模型的关键认知是分支是轻量的创建和删除几乎零成本。有些人习惯只在 main 上开发或者开一个dev分支所有人往里堆代码这在单人和小项目中能跑但人一多就会互相踩踏。正确划分特性分支后每个分支的提交历史相对独立代码审查也有了明确范围。2.3 提交与版本回退commit、reset、revert 一次说清提交commit是 Git 的核心操作相当于给项目当前状态拍一张快照并附上一段说明文字。每次提交有唯一的 SHA-1 哈希值可以随时回去查看或恢复。这条时间线就是所谓的「后悔药」只要提交过就没有真正丢失的东西。新手容易把reset和revert搞混。两者都能撤销变更但作用方式完全不同。reset是移动分支指针改写提交历史revert是创建一个新的反向提交保留原有历史。选哪个看场景本地还没推送的提交用reset随便折腾已经推送到远端并且可能被同事拉取过的提交必须用revert。命令是否改写历史典型场景对远端的影响git reset --soft是撤销 commit 但保留暂存需强制推送慎用git reset --hard是彻底丢弃本地修改需强制推送慎用git revert否撤销已推送的提交正常推送即可# 查看最近 5 条提交记录一行一条 git log --oneline -5 # 回退到某次提交但保留工作区改动 git reset --soft HEAD~1 # 生成一条反向提交撤销指定提交的改动 git revert 7a9f3c2HEAD~1表示当前提交的父提交也就是最近一次提交往前一个。git reset --soft之后改动会回到暂存区你可以重新组织提交如果想连工作区改动一起放弃用--hard但这一步没有确认提示一旦执行未提交的改动直接消失。所以我的习惯是能用revert就优先revert只在本地分支上才用reset --hard。2.4 Pull Request代码审查从不是可选项Pull RequestPR是 GitHub 协作的枢纽。它本质上是一个「请求」请仓库维护者把你的分支合并进目标分支。但它的价值远不止合并动作它同时提供了代码对比、逐行评论、自动化检查和讨论区。很多团队把 PR 当作代码评审的正式环节没有第二个人的批准代码不允许合并进 main。PR 的运作逻辑是你推送分支到 GitHub 后在网页上点击「Compare pull request」填写标题和描述指定审查者然后等待反馈。审查者可以在具体某一行代码下留言你也可以继续推送新提交到该分支PR 会自动更新对比内容不需要重建 PR。正因为 PR 把代码变更变成了可讨论的对象它才是质量控管的真正抓手。单人项目可能觉得 PR 多余但只要是多人协作哪怕是两个人也值得走一遍 PR 流程。被审查时丢脸的地方总比合并后线上故障要体面得多。3. 从 0 到 1 跑通 GitHub 工作流环境配置、推送与 PR 实操概念模型建立之后剩下的就是动手。这一章从一台干净的电脑开始完整走一遍 GitHub 工作流装 Git、配 SSH、建仓库、推代码、提 PR、合并。每一步都附命令和参数说明照着敲即可。3.1 环境准备安装 Git、配置身份并校验 SSH 连通性Git 的安装方式因系统而异安装完成后第一件事是配置全局身份。这个身份信息会写进每一次提交记录里所以要用真实常用的名字和邮箱别人通过提交记录能找到你。# 配置提交者姓名和邮箱--global 表示对当前用户全局生效 git config --global user.name 你的名字 git config --global user.email 你的邮箱 # 生成 SSH 密钥对指定 ed25519 算法和注释邮箱 ssh-keygen -t ed25519 -C 你的邮箱 # 查看公钥内容复制后粘贴到 GitHub 的 SSH keys 设置页 cat ~/.ssh/id_ed25519.pubssh-keygen会询问保存路径和口令直接回车用默认路径即可口令passphrase可以留空也可以设置一个设置了的话每次 SSH 操作都要输入嫌麻烦就用ssh-agent缓存。ed25519是目前推荐的算法比传统的 RSA 更短更安全如果用的系统比较老不支持才退回到-t rsa -b 4096。配置完成后用一条命令验证连通性# 测试 SSH 连接首次会提示确认指纹输入 yes 即可 ssh -T gitgithub.com看到类似「Hi 用户名! Youve successfully authenticated的提示就算通了。注意这条输出里可能出现一些与账户相关的信息那是 GitHub 正常返回的认证确认不用紧张。如果卡在这里先检查公钥有没有完整粘贴、有没有复制到换行符这是最常见的翻车点。3.2 把本地项目推到 GitHub初始化、关联远端与第一次 push本地项目推到 GitHub核心步骤是四件事初始化本地仓库、生成第一次提交、创建远端仓库、关联并推送。其中创建远端仓库这一步在网页上操作更快进入 GitHub 首页点「New repository」填名字和描述不要勾选「Add a README file」保持空仓库状态这样本地推送时不会有合并冲突。# 在项目根目录初始化 Git 仓库 git init # 把所有改动加入暂存区. 表示当前目录所有文件 git add . # 生成第一次提交-m 后面是提交说明 git commit -m init: 初始化项目 # 把默认分支名改为 mainGitHub 的默认分支现在是 main git branch -M main # 关联远端地址使用 SSH 格式 git remote add origin gitgithub.com:你的用户名/仓库名.git # 首次推送-u 建立本地分支与远端分支的追踪关系 git push -u origin maingit add .会把当前目录下所有未被忽略的文件加入暂存区。如果项目里有 node_modules、构建产物之类不该入库的文件必须提前创建.gitignore文件否则会把大量垃圾文件推上去。git branch -M main这条命令是应对 Git 旧版本默认分支名为master的情况-M表示强制重命名。-u参数建立追踪关系后之后在这条分支上直接敲git push即可不用每次指定远端和分支名。第一次推送成功后一个容易忽略的细节是远端仓库是否设置了权限保护。如果团队只有你一个人无所谓如果以后要多人协作建议在 GitHub 仓库设置里把 main 分支设为受保护禁止直接推送所有变更必须走 PR。这个设置能极大降低误操作风险。3.3 发起 Pull Request分支命名、提交规范与 gh 命令一个规范的 PR从分支命名就开始了。分支名要能说明意图提交信息要能讲清改动。我习惯在提交信息里用前缀区分类型feat:表示新功能fix:表示修 bugrefactor:表示重构docs:表示文档改动。这个约定不是 GitHub 强制的但配合 PR 模板使用能大幅度提高审查效率。# 确保 main 是最新的再拉出特性分支 git checkout main git pull origin main git checkout -b feature/login-page # 开发完成后查看改动内容是否正确 git status git diff --stat # 提交并推送到远端同名分支 git add . git commit -m feat: 新增登录页及表单校验 git push -u origin feature/login-pagegit status显示工作区、暂存区的状态git diff --stat只显示文件改动统计而不展开具体内容适合提交前快速检查。推送成功后可以用 GitHub 网页端发起 PR也可以安装 GitHub CLIgh在命令行完成整个流程。命令行方式对习惯终端操作的人更高效# 创建 PR--base 指定目标分支--head 指定来源分支 gh pr create --title feat: 新增登录页 --body 实现说明... --base main --head feature/login-page # 查看当前仓库所有未合并的 PR 及状态 gh pr list # 查看某个 PR 的详细改动 gh pr view 12gh pr create中--body是 PR 描述建议写清楚改动动机、测试方法和影响范围而不是只写一句「看代码」。--head指定来源分支不传时默认使用当前所在分支。gh pr list输出会带 PR 编号、标题、分支和状态编号在后续操作中会用到。gh 需要先执行gh auth login完成认证它会引导你选择登录方式整个过程在命令行里交互完成。3.4 审查与合并在命令行里完成一次完整的 code review代码审查是需要具体动作的环节。审查者要做的不是泛泛地浏览而是确认这几点改动是否符合需求、有没有明显缺陷、测试覆盖是否到位、命名和风格是否与项目一致。GitHub 网页端的 PR 页面提供了很好的逐行评论体验但命令行也能完成大部分工作流操作。# 切换到一个 PR 对应的分支进行检查 git checkout feature/login-page # 查看该分支与 main 的具体差异 git diff main...feature/login-page # 合并 PR--merge 表示生成合并提交--delete-branch 合并后自动删除远程分支 gh pr merge 12 --merge --delete-branch三点省略号main...feature/login-page表示「从 main 和该分支的共同祖先出发到该分支为止的所有改动」这是查看一个分支相对另一分支完整改动量的标准写法。gh pr merge有多种合并方式--merge保留一条合并提交--squash把该分支所有提交压缩成一条后再合并--rebase将提交逐个重放到目标分支上保持线性历史。团队风格不同选择也不同我倾向于用--squash因为特性分支上的中间提交wip、fix typo之类往往没有保留价值压缩成一条干净记录更利于追溯。审查时如果发现问题直接在网页端对应代码行下留言比命令行里写评论更直观。作者收到反馈后在该分支上继续提交新改动并推送PR 自动更新审查者再次查看即可。这个过程会循环几轮直到双方都满意才执行合并。4. GitHub 使用避坑指南认证、冲突与大文件的 5 个高频翻车点GitHub 的命令本身不难难的是各种边界情况。这一章整理了 5 个我在实际使用和教别人时反复遇到的翻车点每条按现象、原因、解决的结构讲清楚希望帮你少走弯路。4.1 HTTPS 认证频繁失效改用 SSH key 一次性解决现象使用 HTTPS 地址克隆仓库后每次git push都提示输入用户名和密码输入后依然报错认证失败。有些开发者会以为是网络问题反复重试浪费时间。原因GitHub 在 2021 年后已不再接受账户密码直接推送必须使用个人访问令牌Personal Access Token代替密码。很多人不知道这一点还在用旧习惯输入密码自然被拒绝。另外即便正确配置了令牌HTTPS 方式依然会在凭据过期后再次弹出认证提示操作体验很割裂。解决直接切换到 SSH 协议一次性配置长期免密。先按 3.1 生成密钥并把公钥添加到 GitHub 设置页然后修改远端地址# 查看当前远端地址 git remote -v # 把 HTTPS 地址改成 SSH 格式 git remote set-url origin gitgithub.com:你的用户名/仓库名.git # 验证新地址是否生效 git remote -vgit remote set-url只修改当前仓库的远端地址不影响其他仓库。改完后推送一次如果提示确认主机指纹输入yes即可。一个容易忽略的细节如果本地有多个 GitHub 账号需要配置~/.ssh/config文件为不同域名或别名指定不同密钥否则 SSH 默认只会使用id_ed25519那一把。4.2 冲突解决错误把 rebase 和 merge 的语义混在一起现象分支合并时提示冲突开发者先用git merge解决了一次又对同一个分支执行git rebase结果历史变得混乱不堪PR 里出现大量重复提交。原因merge和rebase是两种不同的集成方式。merge保留两条分支的完整历史产生一个合并提交rebase把当前分支的提交「重放」到目标分支顶端改写提交时间线。混用两者的结果往往是同一个改动被重复记录且由于提交哈希变了PR 的对比内容变得难以阅读。解决团队内约定一种主要方式不要混用。我的建议是本地分支开发时用rebase跟上远端变更保持本地分支干净推送到远端并发起 PR 后合并阶段用squash或merge不要在已推送的分支上再rebase。# 拉取远端 main 的最新变更并把当前分支的提交重放到其顶端 git pull origin main --rebase # 如果出现冲突解决后继续 rebase git add . git rebase --continue # 觉得情况失控立即中止并回到 rebase 前的状态 git rebase --abortgit pull --rebase和git pull的差别在于后者默认会产生一个合并提交前者保持线性历史。--continue在每次解决完冲突后执行所有冲突都处理完才算完成--abort是一键回到 rebase 之前的状态用于发现自己处理不了冲突时。4.3 大文件把仓库撑爆Git LFS 要在一开始就规划现象项目里放进了一个几十 MB 的资源包或者数据集提交推送都正常但之后每次 clone 和 pull 都越来越慢仓库体积直线上升甚至达到 GitHub 单仓库推荐体积上限1GB而被警告。原因Git 的设计目标是文本和代码它把每次提交的版本都完整存储。二进制大文件只要改动过一次新旧两个版本都会留在历史记录里无法通过简单删除当前文件来瘦身。这种问题一旦发生清理成本非常高涉及改写历史还可能影响所有协作成员。解决从项目早期就引入 Git LFSLarge File Storage。LFS 把大文件的内容存到独立存储中仓库里只保留一个文本指针clone 时按需拉取实际文件。这样既不影响 Git 历史上其他文件的轻量特性也不会撑爆仓库。# 安装 LFS 扩展只需一次 git lfs install # 跟踪指定类型的文件把匹配规则写入 .gitattributes git lfs track *.psd git lfs track *.zipgit lfs track的参数是文件路径模式支持通配符。执行后生成的.gitattributes文件需要和代码一起提交到仓库这样所有协作者自动应用同样的跟踪规则。关键原则是LFS 要在文件第一次入库之前就配置好。如果已经把大文件推上去了再启用 LFS 也不会自动迁移历史记录需要额外执行迁移命令而且过程复杂所以趁早规划。4.4 强制推送覆盖了同事提交reflog 是最后的后悔药现象某人执行了git push --force把本地旧历史强制推送到远端结果同事刚推上去的提交全被覆盖。团队一瞬间「丢」了代码群里一片混乱。原因--force的含义是「远端必须变成我本地这样」Git 不做任何保护直接覆盖。很多时候并不是想覆盖别人而是因为本地做了rebase导致提交历史与远端不一致普通推送被拒就顺手加了--force却没意识到远端可能有别人新提交。解决优先用--force-with-lease代替--force。这个参数会在推送前检查远端是否已发生变化如果远端有他人新提交推送直接失败而不是盲目覆盖。这是 Git 提供的安全网应该成为习惯。# 安全强制推送远端有变化时拒绝推送 git push --force-with-lease # 如果不幸覆盖了同事提交在本地找回对方提交的哈希 git reflog # 找到后创建一条分支指向那个提交重新推送到远端恢复 git branch recover-branch 3f2a1c9 git push origin recover-branchreflog记录了本地所有分支引用的变动史即使提交被reset或rebase掉了只要本地执行过就一定能找到。git branch recover-branch 3f2a1c9中3f2a1c9是被覆盖提交的哈希创建新分支后推送即可恢复。这套流程要求动作迅速因为reflog默认只保留 90 天记录且需要有人在本地留有过那个提交才行。4.5 推送被拒 non-fast-forward不是乱码是远端领先于本地现象执行git push时看到错误信息! [rejected] ... (non-fast-forward)很多新手以为是代码写错了甚至有人直接删掉本地仓库重新 clone。原因这个提示只是说「远端有你本地没有的提交」Git 为了防止覆盖他人代码而拒绝了这次推送。可能是同事推了新代码也可能是你之前推送的一条分支被其他设备更新过。解决方案不是删仓库而是先把远端变化拉下来整合。解决# 先把远端 main 的变化拉下来并重放到本地提交之上 git pull origin main --rebase # 再尝试推送 git push origin main--rebase在这里的作用是让本地提交「站在」远端最新提交之后历史保持线性不会产生多余的合并提交。如果拉取时发生冲突按 4.2 的方法处理。这个流程多跑几次就熟了遇到类似提示先别慌Git 的报错大多数是保护性提示不是灾难。5. 把教程变成自己的 PDF 速查手册整理、分类与持续更新前面把 GitHub 的核心概念、完整工作流和高频踩坑点都过了一遍但看过不算学会真正能随时调用才算。最后一个建议是把这些内容整理成一份属于你自己的速查手册导出为 PDF放在随手能打开的地方。整个过程分三步。第一步把命令按场景分类。我的习惯是在 Markdown 文件里建几个二级分类仓库操作、分支操作、提交与回退、PR 相关、冲突处理、LFS 与仓库维护。每个分类下列出命令、参数含义、典型场景以及这个命令容易踩的坑。不要贴大段解释每行保持一两句话的长度这样查的时候一眼能定位。第二步把踩坑记录做成独立清单。每次遇到问题并解决后花 5 分钟把它追加到手册里格式固定为「现象 → 原因 → 解决命令」。这些记录比任何教程都珍贵因为它们是针对你自己项目、你自己容易犯的错定制的。过半年再回看这份清单你会发现自己已经跨过了绝大多数低级错误。第三步导出 PDF 并持续迭代。多数 Markdown 编辑器或在线工具都支持导出 PDF核心是排版清晰、代码和正文有明显区分。我习惯用支持自定义主题的编辑器把代码块背景色调深、正文行距调大导出效果接近印刷品。PDF 的好处是不依赖网络、不依赖特定软件手机和电脑上都能直接打开。我自己的这份手册已经积累了三年从最初的三页基础命令长到现在包含十几类操作、几十条踩坑记录。GitHub 的界面和命令会偶尔变动但底层的 Git 模型很稳定手册里的内容多半长期有效。如果发现某条命令在最新版本里行为变了顺手记一笔更新比四处搜索找答案效率高得多。希望这份手册的思路也能帮到你。本文还有配套的精品资源点击获取
