Git 版本控制

Git 用来记录文件的变化历史。它不仅能把代码推送到远程仓库，更重要的是让每次修改都可以比较、追踪和回退。

初始化配置

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

--global 表示该身份用于当前电脑上的所有仓库。如果只想为当前仓库设置身份，进入仓库后去掉 --global。

git config --global user.name
git config --global user.email

这两个命令可以检查配置结果。单仓库配置需要在 Git 仓库内执行，全局配置则不要求先初始化仓库。

初始化仓库并查看状态

git init
git status

git init 会在当前目录创建 .git 目录。这个目录保存版本历史和仓库配置，不要手动修改其中的文件。

git status 是最常用的 Git 命令之一，它会显示当前分支以及文件处于未跟踪、已修改、已暂存还是已提交状态。

Git 中最重要的三个区域：

工作区 Working Tree  -- git add -->  暂存区 Staging Area  -- git commit -->  本地仓库 Repository

工作区：当前磁盘上看到和编辑的文件。
暂存区：准备放入下一次提交的修改集合。
本地仓库：已经形成提交、可以追溯的版本历史。

第一次提交

创建一个练习文件：

Set-Content -LiteralPath '.\readme.md' -Value 'Hello Git' -Encoding utf8
git status

此时 readme.md 是未跟踪文件（Untracked），说明文件存在，但 Git 还没有开始记录它。

git add readme.md
git status

文件进入暂存区后，会出现在 Changes to be committed 下。git add 可以执行多次，最后一次提交会包含当时暂存区里的全部修改。

git commit -m "docs: 添加 readme"

提交（Commit）会把暂存区保存为本地仓库中的一个版本快照。每个提交都有唯一哈希值，提交信息应该简洁说明这次修改完成了什么。

不要在不确认范围时习惯性执行 git add .。更稳妥的方式是先看状态，再按文件暂存：

git status --short
git add readme.md
git diff --staged
git commit -m "docs: 完善项目说明"

查看差异

git diff

git diff 比较工作区与暂存区，显示尚未暂存的修改。

git diff --staged

git diff --staged 比较暂存区与上一次提交，适合在提交前检查“这次到底会提交什么”。

git diff HEAD

git diff HEAD 显示工作区和暂存区相对于当前提交的全部变化。

查看提交历史

git log
git log --oneline --graph --decorate --all

--oneline：每个提交显示一行。
--graph：用字符画显示分支关系。
--decorate：显示分支和标签指向。
--all：显示所有本地分支。

查看某个文件的历史：

git log --oneline -- readme.md
git show <提交哈希>

分支

开发新功能时，可以从当前提交创建一条独立开发线：

git switch -c feature/device-dashboard

分支（Branch）：指向某个提交的可移动指针。
HEAD：表示当前检出的分支或提交。

完成功能并提交：

git add src
git diff --staged
git commit -m "feat: 添加设备状态面板"

回到主分支并合并：

git switch main
git merge feature/device-dashboard
git branch -d feature/device-dashboard

仓库的默认分支也可能叫 master，应以 git branch --show-current 的输出为准，不要机械照抄分支名。

处理合并冲突

当两个分支修改了同一文件的同一区域时，Git 可能无法自动决定保留哪一份内容。

冲突文件中通常会出现：

冲突开始：<<<<<<< HEAD
当前分支的内容
内容分隔：=======
待合并分支的内容
冲突结束：>>>>>>> feature/example

处理步骤：

打开冲突文件，理解两边修改的意图。
手动整理成最终需要的内容，并删除冲突标记。
运行测试或构建，确认结果正确。
暂存并提交解决结果。

git status
git add <冲突文件>
git commit

如果尚未解决且想取消本次合并：

git merge --abort

远程仓库

查看和添加远程仓库：

git remote -v
git remote add origin https://github.com/<用户名>/<仓库名>.git

第一次推送当前分支：

git push -u origin main

此后的常用同步流程：

git pull --rebase
git push

git fetch 只获取远程更新，不自动修改当前分支；git pull 会获取并整合远程更新。在多人协作或本地有未提交修改时，先运行 git status，不要直接盲目拉取。

撤销操作

撤销前先确定修改位于工作区、暂存区还是已经提交。

取消暂存，但保留工作区修改：

git restore --staged readme.md

丢弃某个文件尚未暂存的修改：

git restore readme.md

这个操作会覆盖工作区内容，执行前必须确认修改确实不再需要。

为已经公开或推送的错误提交创建反向提交：

git revert <提交哈希>

git revert 不会改写已有历史，通常比对共享分支执行 reset 更安全。对 git reset --hard、强制推送等命令，必须先理解影响范围并确认有可靠备份。

.gitignore

.gitignore 用来声明不应被 Git 跟踪的文件，例如依赖、构建产物、本地配置和密钥文件。

嵌入式项目常见示例：

build/
.pio/
.vscode/
sdkconfig.old
*.log

.gitignore 对已经被 Git 跟踪的文件不会自动生效。密码、API Key、数据库连接串等敏感信息不应进入提交历史；一旦误提交，应立即撤销并更换泄露的密钥。

可以提交一份不含真实密钥的 .env.example，说明项目需要哪些环境变量。

嵌入式项目中的推荐工作流

确认状态 → 拉取更新 → 创建功能分支 → 小步开发与测试
→ 检查 Diff → 暂存指定文件 → 提交 → 推送 → 合并

建议：

一个提交只解决一个明确问题。
提交前检查 git status --short 和 git diff --staged。
功能分支使用清晰名称，如 feature/login、fix/ws-reconnect。
不提交构建产物、编辑器缓存、临时日志和真实密钥。
README 中记录启动、测试、构建和部署方法。
为可演示版本创建标签：git tag v0.1.0。