GitHub Git 速查表（葡萄牙语版）深度解析：training-kit 开源课程中的 Git 命令行实战手册

• 文档
• 教程

本文以 training-kit 开源仓库中的葡萄牙语（pt-PT）版本速查表 downloads/pt_PT/github-git-cheat-sheet.md 为骨架，逐条解读 Git 日常高频命令的语义、适用场景与底层机制，并结合仓库内配套的英文原版速查表与 git-guides 系列教程展开纵深说明。读完本文，你将掌握从 Git 安装配置、仓库创建、日常增删改提交，到分支协作、临时保存、历史浏览与远程同步的完整命令行工作流，并理解每条命令背后的版本控制原理。

一、这份速查表是什么：training-kit 多语言速查表家族

training-kit 是 GitHub Professional Services 团队维护的开源教学材料仓库，核心资产是一系列多语言 Git/GitHub 速查表。以本仓库为例，除本文剖析的葡萄牙语版本外，还收录了英文原版 downloads/github-git-cheat-sheet.md、简体中文版、繁体中文版，以及德语、法语、日语、韩语、俄语、西班牙语等数十种语言版本（位于 downloads 目录下各语言子目录中）。此外还有 高级版速查表、Git 概念 Beta 版、submodule 与 subtree 对比 等进阶材料。

葡萄牙语版速查表以layout: cheat-sheet布局渲染为双栏卡片式页面，按"安装配置 → 创建仓库 → 提交更改 → 分支 → 文件管理 → 忽略规则 → 临时保存 → 历史操作 → 远程同步"九大功能区组织内容，每条命令都配有一句简洁的功能说明。下文将逐区展开，并结合仓库源码级证据扩充参数细节与使用边界。

二、安装 Git：桌面客户端与命令行工具

速查表将安装环节分为三类渠道：

• GitHub for Windows / GitHub Desktop：GitHub 官方提供的桌面客户端，为最常用的操作提供图形化界面，同时内置命令行工具，用于覆盖更高级的场景；两类客户端都会自动更新。
• GitHub for Mac：macOS 平台的对应桌面客户端。
• Git for all platforms：面向 Linux 及其他 POSIX 系统的 Git 发行版，可从 Git SCM 官方网站获取对应平台的安装包。

这里需要理解一个关键点：GitHub Desktop 是"协作平台客户端"，Git 才是底层版本控制系统。正如 git-guides/git-overview.md 所阐述的，Git 负责底层的版本控制（快照、分支、合并），GitHub 则是构建在其之上的协作平台（远程托管、Pull Request、代码评审、集成测试）。桌面客户端封装了常用操作，但终端（命令行）才能覆盖 Git 的全部能力——这也是速查表以命令行指令为主的原因。

Git 核心发行版由 C、Shell、Perl 与 Tcl 编写，其优势在于：分支轻量廉价、变更以 SHA 哈希压缩存储（对文本文件效率极高，但对二进制文件不友好）、仓库可互联以便多人协作。

三、配置 Git：身份信息是提交的"签名"

任何提交（commit）都携带作者身份信息，速查表首先要求配置用户名与邮箱：

$ git config --global user.name "[nome]"

配置与 Git 提交关联的用户名。

$ git config --global user.email "[endereco-de-email]"

配置与 Git 提交关联的邮箱地址。

--global标志表示作用于当前用户的所有本地仓库（系统级配置文件~/.gitconfig）。除此之外，Git 配置还存在另外两个作用域：

• --local（默认）：仅作用于当前仓库，写入该仓库.git/config；
• --system：作用于系统所有用户，写入系统级配置文件。

作用域从小到大覆盖，--local的配置优先级最高。英文原版速查表还补充了一条常用配置：

$ git config --global color.ui auto

开启命令行输出的颜色高亮，让git status、git diff等命令的输出更易读。

配置完成后，可用git config --list查看当前生效的全部配置。务必在首次提交前完成此步骤，否则 Git 会尝试从系统推断身份，甚至拒绝提交并提示需要设置user.name与user.email。

四、创建仓库：git init与git clone两条路径

速查表给出两种建立仓库的方式：

$ git init [nome-do-projeto]

以指定项目名创建一个新的本地仓库。

$ git clone [url]

下载一个已有项目，包含其完整历史。

git init与git clone是互斥的两条起点路径，正如 git-guides/git-init.md 强调的：启动新项目时二选一，不要同时使用。它们的适用场景截然不同：

场景一：本地已有项目，尚未纳入版本控制 →git init

git init会在当前目录（或指定目录）创建隐藏的.git目录，其中存储了 Git 使用的全部对象与引用（objects 与 refs），正是这个隐藏目录把普通文件夹变成了 Git 仓库。该命令整个项目生命周期只运行一次，后续即使协作者加入也无需重复执行。初始化后的标准衔接流程是：

1. 在 GitHub 上创建空远程仓库；
2. git remote add origin <URL>将远程 URL 以人类友好的名字origin存入本地配置；
3. git add暂存现有文件、git commit生成首个快照；
4. git push -u origin main推送到远程并建立持久的跟踪关系，此后直接git push/git pull即可。

git init的常用变体还包括git init <directory>（初始化指定目录）与git init --bare（创建裸仓库，仅作远程仓库使用、不承载日常开发）。

场景二：远程仓库已存在 →git clone

如 git-guides/git-clone.md 所述，克隆得到的不是单个文件，而是完整仓库——全部文件、全部分支、全部提交，这正是分布式版本控制系统的核心优势：每位开发者本地都持有一份完整历史，可以在特性分支上自由改动。克隆通常只在项目接入时执行一次。常用选项包括：

• git clone --single-branch：只克隆单个分支，可用git clone [url] --branch [branch] --single-branch指定具体分支；
• git clone --sparse：只填充根目录文件，适合超大仓库的性能优化；
• git clone --mirror：不带工作区的镜像克隆，常用于异地仓库同步或自动化测试；
• git clone --recurse-submodules：克隆后同时初始化并拉取子模块。

克隆完成后，git remote -v可查看默认关联的远程origin；针对 fork 工作流，还可将原仓库添加为第二个远程（惯例命名为upstream）以持续同步上游更新（详见 git-guides/git-remote.md）。

五、跟踪与提交更改：工作区、暂存区与历史的三段式流转

速查表以"进行更改（Fazer alterações）"为主题列出六个命令，它们构成了 Git 最核心的日常循环——工作区 → 暂存区 → 提交历史：

$ git status

列出当前项目中所有已修改的文件，并显示当前所在分支、暂存状态以及本地分支与远程分支的相对位置。如 git-guides/git-status.md 所言，这是"任何时候都值得先跑一遍"的安全命令——它只输出信息、绝不改动仓库；在合并冲突时还会精确指出哪些文件是冲突源。

$ git diff

逐行显示尚未暂存（pre-stage）的文件改动差异。

$ git add [ficheiro]

将文件加入暂存区（staged），使其可被纳入下一次提交。

$ git diff --staged

逐行显示已暂存的改动差异（即下一次提交将记录的内容）。英文原版中对应的表述是git diff --cached，两者等价。

$ git reset [ficheiro]

将文件移出暂存区（unstage），但不删除工作区中的文件内容。

$ git commit -m "[mensagem descritiva]"

将已暂存的改动永久记录进版本历史，-m后的描述性消息即提交说明。

关于git add与git commit的组合用法，git-guides/git-add.md 给出了关键补充：

• git add <path>暂存指定文件或目录，是最安全清晰的用法；
• git add -A暂存全部新增、修改、删除的文件（含点开头的文件与仓库高层目录）；
• git add .递归暂存当前目录全部内容；
• git add -u只暂存已跟踪文件的修改与删除，不包含新文件；
• git add -p以交互方式逐块选择暂存，便于把同一文件中的多个逻辑改动拆分为不同提交。

而 git-guides/git-commit.md 阐明了提交的两阶段设计：提交应当是"逻辑原子"的变更单元，git commit只会把暂存区内容写入历史——不执行git add时git commit不会提交任何东西。常用变体：

• git commit -am "mensagem"：对已被 Git 跟踪的文件跳过暂存步骤，直接提交；
• git commit --amend：用新提交替换最近一次提交（仅适用于尚未推送的提交，常用于修正提交消息笔误或补充遗漏文件）。

从 downloads/github-git-cheat-sheet.md 英文原版可看到，这一功能区的英文标题是 "Make changes"，强调提交信息应当叙述性强、能讲述仓库演化的故事（推荐使用祈使句，如 "update the README"）。

六、分支：轻量指针驱动的并行历史

速查表用"Branching（平行历史）"概括分支的用途：创建版本历史的平行副本，在隔离环境中工作。涉及命令如下：

$ git branch

列出当前仓库的所有本地分支。

$ git branch [nome-do-branch]

创建一个新分支。

$ git switch -c [nome-do-branch]

切换到指定分支并更新工作目录（-c表示创建后立即切换）。

$ git merge [nome-do-branch]

将指定分支的历史合并进当前分支。

$ git branch -d [nome-do-branch]

删除指定分支（-d仅在分支已合并时允许删除，未合并分支需使用-D强制删除）。

理解分支的关键在于：分支是"指向某个提交的轻量可移动指针"（参见英文原版速查表的术语表）。git-guides/git-overview.md 进一步指出：

• 分支极其廉价，创建大量分支完全没问题，分支应"为用途而建"而非"为人而建"；
• 新分支的父节点是当前HEAD所指向的位置（可以是另一个分支、某个 tag 或任意提交），典型工作流是从代表最新生产代码的main分支切出特性分支；
• 任何提交都落在当前"检出的"分支上，所以提交前用git status确认所在分支是好习惯。

关于命令演变：速查表使用的是较新的git switch -c，传统写法是git checkout -b [branch-name]，两者等价；git switch与git checkout均可用于切换分支（见 git-guides/git-overview.md 与 git-guides/git-clone.md 中的用法）。合并是 Pull Request 背后的核心 Git 操作——当多人在同一文件不同区域并行修改时，Git 能够处理合并冲突，这正是分布式协作得以成立的基础。

七、文件管理：删除与重命名已跟踪文件

速查表"更改文件（Alteração de ficheiros）"区覆盖了已纳入版本控制的文件的删除与重命名：

$ git rm [ficheiro]

将文件标记为从本地仓库移除，并同时从文件系统中删除（已暂存）。

$ git rm --cached [ficheiro]

将文件移出版本控制，但保留在工作目录中。

$ git mv [ficheiro-original] [ficheiro-renomeado]

重命名文件并将其暂存，等待提交。

这三个命令揭示了"Git 跟踪的是变更而非文件本身"的特性：

• git rm是"删除并暂存"的快捷方式，等价于手动删除文件后执行git add（暂存删除）；
• git rm --cached的典型用途是把误纳入版本控制的大型文件或敏感文件（密码、令牌）移出跟踪，同时保留本地副本——这正是git add与git rm语义不对称的常见场景（git add用 "add" 一词同时也暂存删除操作）；
• git mv会保留文件历史，使git log --follow之类的历史追踪命令能够跨越重命名查找演化记录。

八、忽略文件：.gitignore与忽略清单检查

速查表给出一个经典.gitignore示例：

*.log build/ temp-*

并说明：项目根目录下的.gitignore文件可防止与这些模式匹配的文件/目录被意外纳入版本控制。三种模式分别代表：

• *.log：匹配所有以.log结尾的文件（通配符*匹配任意字符序列）；
• build/：匹配整个build目录及其全部内容（末尾斜杠表示目录）；
• temp-*：匹配所有以temp-前缀命名的文件或目录。

常见用途包括忽略编译产物、依赖目录（如node_modules/）、日志文件、本地环境配置与 IDE 临时文件。英文原版速查表提示可在 GitHub 官方 gitignore 模板库中找到覆盖主流语言与框架的现成模板。

验证忽略规则是否生效，使用速查表给出的命令：

$ git ls-files --others --ignored --exclude-standard

列出当前项目中所有被忽略的文件与目录。其中--others显示未跟踪文件、--ignored只显示被忽略者、--exclude-standard遵循标准排除规则（.gitignore、.git/info/exclude及全局忽略配置）。

九、临时保存：git stash暂存未提交的改动

当需要在不提交的情况下切换上下文（例如切换到另一个分支修复紧急问题）时，速查表推荐使用 stash 系列命令：

$ git stash

临时保存所有已修改文件（未提交的改动）。

$ git stash pop

恢复之前保存在 stash 中的文件。

$ git stash list

列出 stash 中的所有改动集合。

$ git stash drop

移除最近一次保存到 stash 的文件。

git stash相当于把工作目录"清理"到一个干净状态（改动被保存到 stash 栈中），git stash pop则将栈顶改动恢复到工作目录；git stash list可查看多组历史 stash（每组以stash@{0}、stash@{1}编号），git stash drop用于丢弃。此外还有git stash apply（恢复但不弹出）与git stash pop的细微差别：pop在成功应用后会从栈中移除该条记录，而apply保留记录。这一机制特别适合"提交之前发现需要先处理别的事情"的常见场景。

十、浏览版本历史：git log、git show与跨分支git diff

速查表"浏览版本历史"区提供四个命令，用于导航与检视项目历史：

$ git log

列出当前分支的版本历史。

$ git log --follow [ficheiro]

列出某个文件的历史，包含重命名记录（仅对单个文件有效）。

$ git diff [primeiro-branch]...[segundo-branch]

显示两个分支之间的内容差异（三点...语法比较的是第二个分支与两分支分叉点之间的差异）。

$ git show [commit]

显示指定提交的内容变更与元数据（作者、时间戳、提交消息等）。

git log是检视历史的主力命令，其丰富选项（如--oneline、--graph、--author、-p等）可组合出从简洁单行列表到图形化提交拓扑的多种视图。值得强调的是，提交消息本身就是历史叙事——git-guides/git-commit.md 提醒，浏览历史时人们依靠提交消息导航，因此消息应当短小、描述性强、能讲清楚仓库的演化故事。

十一、重写历史：git reset的两种形态与安全边界

速查表"操控历史（Manipular a história）"区给出两条命令，用于移除提交并重做历史：

$ git reset [commit]

将当前工作环境指向指定提交，保留本地改动，但丢弃其后继的版本历史。

$ git reset --hard [commit]

将当前工作环境指向指定提交，不保留任何改动，并丢弃后继历史。

从底层机制看，git reset移动的是HEAD指针与当前分支指针（如 git-guides/git-commit.md 所述），相当于"让中间的提交看起来从未发生过"。git reset实际有三种级别：

• --soft：仅移动指针，暂存区与工作目录均保留；
• --mixed（默认）：移动指针并重置暂存区，工作目录保留——速查表第一条命令即属此类，效果类似"取消暂存"的扩展版；
• --hard：指针、暂存区、工作目录全部重置，未提交的工作会丢失——速查表第二条命令即属此类。

英文原版速查表在此处给出了醒目警告（CAUTION）：改写历史可能带来严重的副作用。如果待改写的提交已存在于远程（GitHub），请格外谨慎：你删除的提交可能仍存在于协作者的本地仓库，当他们推送时，被"删除"的内容（可能包含密码、令牌或大文件）会悄悄回归共享历史。安全经验法则：

• 仅改写尚未推送的本地提交是相对安全的；
• 涉及远程共享提交时，优先使用git revert——它通过生成一个反向提交来"撤销"变更，而不是删除历史，始终是改写历史的首选方案；
• 若已用git reset误删了提交，可用git reflog（HEAD每次指向的日志，仅保存在本地、保留 30~90 天）找回并恢复。

十二、同步远程更改：fetch、merge、push、pull四部曲

速查表"同步更改（Sincronizar alterações）"区是远程协作的核心，涉及四个命令：

$ git fetch [remote]

从远程仓库下载全部历史（更新远程跟踪分支）。

$ git merge [remote]/[branch]

将指定远程分支的历史合并进当前分支。

$ git push [remote] [branch]

将本地分支的所有提交推送到 GitHub 对应远程分支。

$ git pull

下载并合并一步完成，等价于执行git fetch && git merge。

结合 git-guides/git-pull.md 与 git-guides/git-push.md，可以理清这一区的完整机制：

远程跟踪分支是理解同步的关键概念。克隆仓库时，Git 会同时创建本地工作分支（如main）与一组远程跟踪分支（origin/main等，可用git branch --all查看）。git fetch更新远程跟踪分支，git merge再把远程跟踪分支的新提交并入当前工作分支；git pull将两步合并为一条命令。若预期会产生冲突，可先用git fetch单独拉取、择机再git merge，从而在网络断开时也能从容解决冲突。

git push默认只推送当前检出的分支；推送前先git pull是好习惯，可减少在 GitHub 上制造合并冲突的概率。常用选项：

• git push -u origin [branch]：首次推送新分支时建立上游跟踪关系，此后直接git push即可；
• git push --all：推送全部分支；
• git push --tags：发布尚未存在于远程的标签；
• git push -f：强制推送（会删除或覆盖远程已有提交，务必谨慎）。

与远程通信的命令总共只有四个（git-guides/git-remote.md）：push、clone、pull、fetch。除此之外的所有操作都只发生在本地。远程的概念也支撑了 fork 工作流：origin指向你的 fork，upstream指向原始仓库，git fetch/git pull即可持续同步上游更新。

十三、核心术语速查

结合英文原版速查表末尾的术语表（Glossary），整理葡萄牙语版涉及的核心概念如下：

十四、延伸学习：仓库内配套资源

本速查表只是 training-kit 知识体系的入口，仓库还提供以下配套材料供深入学习：

• 英文原版速查表downloads/github-git-cheat-sheet.md：含color.ui配置、git remote add origin、术语表与历史改写警告等补充内容；
• 进阶速查表downloads/github-git-advanced-cheat-sheet.md：面向高级命令与复杂工作流；
• Git 入门指南系列：git-overview（Git 是什么、为什么用、完整工作流）、git-init、git-clone、git-status、git-add、git-commit、git-push、git-pull、git-remote 等，每个命令均配有"作用原理、常见用法、参数选项、易错场景"四层详解；
• 其他语言版本：简体中文 downloads/zh_CN/github-git-cheat-sheet.md、繁体中文 downloads/zh_TW/github-git-cheat-sheet.md 等，便于对照学习。

仓库采用 Jekyll 构建、Primer CSS 样式化（见 README.md），所有速查表均以 Markdown 编写、可自由复制使用。

结语：把速查表变成肌肉记忆

本文围绕葡萄牙语版速查表的九大功能区，逐条还原了 Git 命令行高频命令的语义与用法，并借仓库内的英文原版、进阶速查表与 git-guides 系列，补齐了配置作用域、暂存区机制、reset 三级模式、远程跟踪分支、stash 栈、reflog 救援等底层细节。建议的实践路径是：先按"安装 → 配置 → init/clone"完成环境搭建，再以"status → diff → add → commit"的循环建立日常提交习惯，随后逐步引入分支、stash 与远程同步，最终借助 reset/revert 理解历史改写的能力与边界。速查表的价值在于随时查阅，而真正的掌握来自反复演练——把每一条命令放进真实的项目流程中，让它们成为你的肌肉记忆。

• 文档
• 教程