Git 扫盲：版本控制与你的第一行代码托管

系列说明：这是「新生开发环境搭建」系列的第 3 篇。第 1 篇里我们已经用 Scoop 装好了 Git，这一篇让它真正为你干活。

一、你一定经历过「最终版」灾难

先不谈工具，谈一个你大概率经历过的场景。

期末交课程设计，你的文件夹里躺着这样的东西：课设.docx、课设-修改.docx、课设-修改2.docx、课设-最终版.docx、课设-最终版2-打死不改版.docx。改到第三天，你发现自己想用的其实是「修改 2」里的一段代码，但那段的最新版混在「最终版」里，两个文件都开着，来回比对，生怕改错。

代码的世界里这个问题更严重：程序是几十个文件联动的，你「回退到昨天的版本」实际是回退几十个文件；小组作业里队友和你同时改一个文件，谁的算数？

Git 就是为这些问题而生的「代码时光机 + 合并器」：它给项目的每个历史时刻拍快照，你随时可以回到任何一帧；它还专门设计了处理多人同时修改的机制。今天这节课只求一件事——你亲手把这套东西跑起来。

🎓 讲师提示：「最终版灾难」的文件夹截图（提前 P 一个夸张的）开场效果好。强调 Git 解决的两件事——回退、合并——分别对应个人与团队两大场景。

二、三个核心概念：工作区、仓库、提交

Git 的世界模型可以压缩成三个词：

仓库（repository）：被 Git 管理的项目文件夹。文件夹里会有一个隐藏的 .git 目录，Git 的全部历史记录都存在里面——所以「把项目回退到上周」不需要任何备份文件，历史就在项目自己肚子里。

提交（commit）：一个快照，一份「存档」。你每完成一个小目标（修好一个函数、写完一个页面），就拍一张快照，附带一句说明「这次改了啥」。项目的历史就是一串快照连成的链，每一环都能随时回去。

工作区：你眼前正在编辑的文件。改动先发生在工作区，攒到一定程度，打包成一个 commit 存档。

日常的工作流因此固化成一个节奏：改代码 → 存档 → 继续改 → 再存档。会这个节奏，Git 的核心你就已经会了。剩下的命令都只是在描述这个节奏。

三、初次配置：告诉 Git 你是谁

每次提交快照都要署名，所以先用两条命令登记身份（打开 PowerShell）：

git config --global user.name "你的名字"
git config --global user.email "你的邮箱"

名字用拼音或英文更保险，邮箱建议用你 Gitee 账号的注册邮箱（下一节要注册）——这两行不配置，后面 commit 会直接报错拒绝执行，是新手第一个高频报错。

顺带一个推荐配置，让 git log 这类长输出在按 q 退出前可翻页浏览，避免终端显示错乱：

git config --global core.pager "less"

🎓 讲师提示：让学生互相检查邻座是否配好，git config --global user.name 不带参数会回显当前值，比 --list 更快定位漏配的人。

四、单人实战：五分钟走完一个来回

光说不练假把式。用一个真实的小项目走完整流程。

第 1 步：建仓库

cd D:\Code
mkdir my-first-repo
cd my-first-repo
git init

git init 执行后输出一行「Initialized empty Git repository」，这个文件夹从普通文件夹升格为 Git 仓库，.git 隐藏目录随之诞生。

第 2 步：写点东西，做第一次提交

新建 hello.py，随便写一行 print("hello git")，然后：

git add hello.py
git commit -m "第一次提交：添加 hello.py"

git add 的意思是「把改动准备进下一次存档」（后面细讲），git commit -m "..." 才是真正拍快照，-m 后面是这次的说明。说明写清楚很重要——三个月后的你，要靠这些话找回改动的上下文。

第 3 步：看历史，再穿越回去

git log

你会看到一条提交记录：一串哈希值（就是这张快照的编号）、作者、时间、你的说明。现在改一下 hello.py（比如把输出改成两行），然后体验时光机的回放：

git log --oneline        # 更紧凑的历史视图
git checkout <哈希值>     # 穿越到指定快照（哈希值从上一条命令复制）

终端会提示你进入「detached HEAD」状态——别慌，这就是「穿越成功」的意思，此时文件夹里的文件就是那张快照当时的样子。看完敲 git checkout main 回到最新。

🎓 讲师提示：穿越环节是全场「哇」的时刻，节奏留足。detached HEAD 一句话带过即可（「这只是只读浏览状态，敲这条命令回来」），不展开展开 HEAD 概念。

五、add 这个中间站：理解 Git 的两段式设计

你可能奇怪：提交就提交，为什么先要 add 一次，两步走不多余吗？

不多余，这是 Git 的精心设计。add 把改动放进一个叫暂存区的中转站，它的价值在小组作业场景立刻显现：你和队友的代码混在一起，你只改了 a.py 和 c.py，队友改了 b.py——你 git add a.py c.py，只把你负责的文件打包提交，b.py 的改动留在工作区不碰。

一次提交只装逻辑上相关的改动，这是好习惯：「修复登录 bug」和「更新文档」就该是两个 commit。暂存区给了你挑拣改动的自由，这是 Git 比其他版本控制工具灵活的根源。

日常有两个补充命令：

git status     # 看当前状态：哪些改了没暂存、哪些暂存了没提交
git add .      # 把工作区全部改动放进暂存区（单人快速开发时常用）

git status 是你最好的朋友——任何时候不知道自己在哪一步了，先跑一下它。

六、SSH 密钥：让你和 Gitee 免密相认

接下来要把代码推到云端。本地和远程服务器之间的身份验证，Git 用的是 SSH 密钥：一对数学上关联的钥匙，私钥留在你电脑里绝不外传，公钥贴到 Gitee 上。以后你连 Gitee，它用公钥验证你手里的私钥，验通过就放行——全程不需要输密码。

生成密钥对（邮箱换成你自己的）：

ssh-keygen -t ed25519 -C "你的邮箱"

一路回车用默认设置即可，密钥生成在 C:\Users\你的用户名\.ssh\ 下。然后查看公钥内容并复制：

type ~\.ssh\id_ed25519.pub

输出的整行内容（以 ssh-ed25519 开头、以你的邮箱结尾）就是公钥，type 命令会把它打印在屏幕上，复制时要完整复制一整行。

🎓 讲师提示：高频事故是「把私钥（无 .pub 后缀）贴到网站上」和「复制公钥漏了开头结尾」。提醒：文件名带 .pub 的才是公钥，贴出去的一定是它。

七、Gitee：把仓库放到云端

代码只在你电脑上，硬盘一坏全剧终；小组协作更需要一个所有人都能访问的中转站。Git 是工具，还需要一个托管代码的云端平台，国内的选项就是 Gitee（gitee.com）——服务器在国内，速度快、不卡门，学校网络环境友好。

注册与准备：打开 gitee.com 注册账号，然后进入「设置 → SSH 公钥」，把上一节复制的公钥完整粘贴进去，标题随便填（比如「宿舍台式机」），保存。

验证连通：

ssh -T git@gitee.com

第一次连接会问 Are you sure you want to continue connecting，输入 yes。看到「Hi 你的用户名! You've successfully authenticated」就说明钥匙对上了。

建远程仓库并关联：在 Gitee 网页上点右上角「+」→「新建仓库」，名字填 my-first-repo，不要勾选任何初始化选项（README、.gitignore 都不勾），创建。页面会显示一段仓库地址，把它关联到你本地的仓库：

git remote add origin git@gitee.com:你的用户名/my-first-repo.git

origin 是这个远程地址的代号，以后推拉都用它。

第一次推送：

git push -u origin main

刷新 Gitee 仓库页面，你的代码出现了。-u 是「记住这个关联」，以后推送只需要 git push，三个字母都不用多打。

🎓 讲师提示：建仓库时不勾初始化选项是重点——勾了会让云端仓库多一个初始提交，本地推上去会冲突，新手极易卡死在这一步。报「remote origin already exists」说明关联命令重复执行过，git remote set-url origin <地址> 修正。

八、日常节奏与团队协作第一步

到这里，本地开发的完整流程已经走通。日常开发就是三拍子节奏：

git add .          # 1. 改完代码，暂存
git commit -m "说明这次改了什么"   # 2. 存档
git push           # 3. 同步到云端

每天开工时先 git pull（把云端的新内容拉下来），收工时 push——这个节奏保持住，协作就稳了。

团队协作的完整玩法（分支、pull request、合并冲突处理）足够再讲一整节课，本系列先建立地基。但对小组作业来说，有一样东西现在就该知道：Gitee 仓库页面点「克隆 / 下载」选 SSH，复制地址，然后 git clone <地址>，队友就能把整个项目连同全部历史一起拿到自己电脑上。

顺带一提，协会也有自己的 Gitea 仓库（gitea.liuhangyv.top），后续协会项目和作业提交会在那里进行，操作方式和 Gitee 完全一样——Git 学的是通用技能，托管平台只是换了壳。

🎓 讲师提示：课程作业如需用协会 Gitea 提交，现场演示一遍 clone 协会仓库。提醒学生 Gitea 的 SSH 端口配置和 Gitee 不同，到时按协会文档走。

九、常见翻车现场与自救

commit 报错请先配置 user.name/email：第三节的两条配置没做，回去补上。

push 报 Permission denied (publickey)：公钥没贴对或没贴全。重查 Gitee 上的公钥内容是否和 type ~\.ssh\id_ed25519.pub 输出一致。

push 报 Updates were rejected：云端有你本地没有的提交（比如队友先推了）。先 git pull 合并，再 push。

不小心把不想提交的文件 add 了：git restore --staged 文件名 把它请出暂存区，文件内容不会丢。

想撤销还没 commit 的本地改动：git restore 文件名，恢复到上次提交的状态——这也是为什么要勤 commit，每一步都有得后悔。

十、写在最后

回顾这条完整的链路：Git 让改动有历史、可回退；SSH 密钥让认证免密码；Gitee 让代码有云端备份、团队能协作。至此，代码终于处于「多人、多机、可追溯」的安全状态。

工具链最后一篇，我们把写代码的「驾驶舱」配好：VS Code 与 Python 的深度集成，让前面所有工具在你的指尖融为一体。