第2章 Git 基础与项目管理

目标概述

本章带你入门版本控制系统 Git。目标是掌握使用 Git 初始化仓库、保存代码修改（commit）、创建分支（branch）等基本操作，并将这些操作融入 Cursor 开发环境进行项目管理。完成本章后，你将能够用 Git 管理你的代码版本，在 Cursor 中查看版本状态，并为后续项目开发打下协作和备份的基础。

主要知识点

• 版本控制的作用：Git 是目前最流行的分布式版本控制系统，能记录代码历史版本、方便多人协作和代码管理。对于初学者，哪怕个人项目也建议用 Git 来保存每次代码进展，以便回退和追踪修改[35]。

• Git 基本概念：

• 仓库（Repository）：一个Git仓库就是受Git管理的项目目录，包含所有文件的历史版本信息。可以在本地创建仓库，也可以将本地仓库推送到远程平台（如GitHub）备份[36]。

• 暂存区（Staging Area）：临时区域，用于暂存将被提交的文件。git add 命令把修改加入暂存区。

• 提交（Commit）：一次文件改动的记录。通过 git commit 将暂存区内容保存为一个新版本，每个提交都有唯一ID和提交消息描述更改。

• 分支（Branch）：独立的开发线路。默认主分支通常称为 master 或 main，我们可以从主分支分叉新分支进行实验或开发新功能，完成后合并回主分支[37]。分支使得多人或多功能并行开发互不干扰。

• 远程仓库（Remote）：托管在服务器上的Git仓库，如GitHub、GitLab。可将本地提交 push 上传远程，也可从远程 pull 更新到本地，方便协作和备份[38]。

• Git 基本操作命令（在 Cursor 内置终端或系统终端执行）：

• 初始化仓库：git init 在当前项目文件夹创建一个新的Git仓库[39]。会生成隐藏的 .git 目录。

• 查看状态：git status 显示当前修改、暂存情况。

• 添加文件到暂存区：git add <文件>，常用 git add . 添加当前目录所有改动。

• 提交更改：git commit -m "提交消息" 提交暂存的更改，并附加一条说明性消息。

• 查看提交历史：git log 列出提交记录。

• 创建新分支：git branch <分支名> 创建新分支。git checkout -b <分支名> 可直接创建并切换到该分支[40]。在 Cursor 的终端运行后，状态栏会显示当前分支名称。

• 切换分支：git checkout <分支名> 切换工作目录到指定分支代码。

• 合并分支：切换到主分支，执行 git merge <分支名> 将指定分支的修改合并进来[41]。

• 关联远程：git remote add origin <远程仓库URL> 绑定远程仓库地址[42]。然后首次推送用 git push -u origin main，后续直接 git push 推送修改[43]。

• 拉取更新：git pull 从远程获取最新提交并合并。

• 在 Cursor 中使用 Git：
  Cursor 基于 VS Code，左侧有“源代码管理”（Source Control）面板（点击左边栏第三个分支图标）可视化地展示 Git 更改。但在当前 Cursor 版本，可能没有完整集成Git GUI，主要通过内置终端使用Git命令[44]。你可以在 Cursor 底部打开终端（按 Ctrl+Shift+ 或使用菜单 View -> Terminal），直接执行上述 Git 命令。提交后，Cursor 状态栏会显示当前分支及是否有未Push的提交。
  此外，Cursor 有特殊的 AI 功能可利用 Git 信息，比如在 Chat 中输入 @Commit 或 @Branch 引用当前未提交改动或当前分支相对主分支的差异[45]。这些标签可帮助 AI 了解你的改动内容，用于代码评审或错误排查。

完整代码 / 示例

情景：你正在 Cursor 中创建我们的项目目录my_chatbot，希望用 Git 保存进度。下面以实际操作演示从初始化仓库到提交代码的过程：

1. 初始化 Git 仓库：
   打开 Cursor 的终端，在项目根目录执行：

git init

• 终端输出类似：Initialized empty Git repository in /path/to/my_chatbot/.git/。此时 .git 文件夹已创建。

1. 首次提交：
   新建一个 README.md 文件，写入项目简介。然后在终端执行：

git add README.md  
git commit -m "Initial commit: add README"

• 终端提示 [master (root-commit) e1f1d2b] Initial commit: add README 等信息，表示成功提交。git status 显示工作树干净，说明没有未提交修改。

1. 创建分支开发：
   比如我们要开发 ChatBot 的命令行功能，可创建新分支：

git checkout -b feature/cli-chatbot

• 这会新建并切换到名为 feature/cli-chatbot 的分支[40]。Cursor 窗口底部状态栏将显示当前在feature/cli-chatbot分支。

1. 在分支上工作并提交：
   编写 chatbot.py 实现命令行聊天（具体实现留待第4章）。完成一个功能后，执行：

git add chatbot.py  
git commit -m "Add basic CLI chatbot functionality"

• 这样将修改提交到 feature/cli-chatbot 分支历史。使用 git log --oneline 可看到当前分支的提交记录。

1. 合并回主分支：
   假设 CLI 功能开发完毕且测试通过，我们准备合并到主分支（master）。先切换分支：

git checkout master

• 然后合并分支更改：

git merge feature/cli-chatbot

• Git 会尝试将 feature/cli-chatbot 的提交合并进 master[41]。若没有冲突，将产生一条合并提交。合并后，可选择删除特性分支：git branch -d feature/cli-chatbot。

1. 推送到远程（可选）：
   为保险起见，你可以将代码托管到GitHub远程仓库。先在GitHub上新建一个仓库，例如 my_chatbot，然后：

git remote add origin https://github.com/你的用户名/my_chatbot.git  
git push -u origin master

• 首次推送会上传所有历史并建立主分支连接[46][43]。以后只需 git push。远程仓库现在就有了你的代码备份。

练习任务：尝试在你的项目中实践上述Git操作。在 Cursor 中经常用 git status 检查文件变动，体验版本管理带来的清晰性。例如，可在不同分支修改同一文件，然后合并，观察Git如何提醒冲突并要求你解决。

操作截图或流程

1. 初始化仓库：下图展示执行 git init 后 Cursor 终端输出和左侧项目结构的变化（.git目录不会在资源管理器中显示，因为它被默认隐藏）。

2. 第一次提交：在 Source Control 面板或终端可以看到 README.md 被跟踪，新提交产生后git log显示提交ID和消息。

3. 分支切换：状态栏分支指示从 master 切换为 feature 分支。在终端执行 git branch 列出分支，可见 feature/cli-chatbot 列表中带 *（当前分支）。

4. 合并：合并成功的终端输出，以及master分支的log中出现合并提交记录。

[47]下图：使用OpenAI API的简单问答应用（将在第4章实现）。开发过程中，我们用Git管理代码版本。

(由于篇幅与环境所限，此处示意关键命令输出截图。请实际操作体会Git状态变化。)

常见错误

• 忘记提交就切换分支：当你在一个分支修改文件但尚未提交就 git checkout 切换，Git会警告工作区有未提交更改，可能引入冲突。解决：养成变更后及时 add 和 commit 的习惯，或使用 git stash 暂存改动。

• 提交消息空或无意义：新手常犯的错误是在 git commit 时忘记加 -m 参数，Git会打开编辑器要求输入提交说明；或者随便写“update”、“fix”等笼统信息。解决：写有意义的提交消息，比如“实现基本聊天逻辑”而非“修改1”。回想每次提交做了什么，再凝练成信息。

• 合并冲突：两个分支修改了相同代码段，合并时会产生冲突。Git 会在冲突的文件里插入标记 <<<<<< 和 >>>>>>。解决：打开冲突文件，在Cursor编辑器里很容易发现标记，手动选择保留或合并代码，然后删除标记。完成后 git add 并 git commit 解决冲突。初学者项目一般冲突较少，真的遇到不要怕，耐心比较改动即可。

• 远程仓库相关：

• 未设置远程就 push：会报错 fatal: No configured push destination。需先 git remote add origin ... 并指定主分支 git push -u origin master[46]。

• 凭证错误：push 时要求用户名密码（或token），若出错请检查 GitHub 账号权限，或设置 SSH Key 免密登录。2021年后GitHub不支持密码推送，需使用Personal Access Token。

• 大小写命名差异：Windows不区分大小写，Git 有时会出现文件名大小写变化无法Commit的情况（比如Readme.md改为README.md）。需要在Git配置中设置core.ignorecase=false解决。

延伸思考

1. 为什么要用 Git：对于个人学习项目，你可能觉得直接在本地存文件就行。思考一下，引入Git后你能获得哪些便利？例如，万一代码改坏了，可以通过历史记录恢复[35]；或者你可以尝试在不同分支实现不同方案，最终选择最佳。试着体会版本管理在开发中的价值。

2. 远程协作：虽然本教程项目是个人完成，但你可以邀请朋友一起在GitHub上协作开发。想象如果没有Git，会遇到怎样的文件共享麻烦？使用GitHub Pull Request流程进行代码评审有什么好处？

3. 学习资源：Git命令很多，本章只覆盖了冰山一角。推荐课后阅读廖雪峰的Git教程或Pro Git电子书，了解如 git clone（从远程复制项目）、git revert（回滚提交）、git rebase（变基）等高级用法。你也可以探索Git GUI工具（如GitKraken、Sourcetree）是否更直观。

现在，你已经拥有AI加持的编辑器和代码管理工具。接下来，我们将复习一点Python基础，为真正实现ChatBot做好准备。