📚 课程目录第2章搭建版本控制仓库

2. 搭建版本控制仓库

任务目标

为嵌入式项目建立Git版本控制仓库，完成仓库初始化、分支策略配置与忽略规则设置，使源码变更可追踪、可协作、可回滚。本案例以典型STM32裸机工程为对象，演示从零搭建仓库的完整流程。

环境准备

需要Git 2.20+（git --version验证），操作系统不限。嵌入式编译工具链（arm-none-eabi-gcc等）不属于本案例范围，仅需源码目录结构即可完成仓库搭建。

仓库初始化与首次提交

在项目根目录执行以下命令完成初始化与首次提交：

# 初始化仓库
git init

# 配置用户信息（首次使用Git时必需）
git config user.name "Your Name"
git config user.email "your.email@example.com"

# 创建主分支并切换
git branch -M main

# 添加所有文件并提交
git add .
git commit -m "Initial commit: STM32 bare-metal project skeleton"

首次提交前需确认.gitignore已正确配置（见下文），避免将编译产物纳入版本管理。

分支策略配置

嵌入式项目建议采用主干开发+短期特性分支策略：main分支始终保持可编译状态，开发在feature/*分支进行，通过develop分支集成验证后合入main。执行以下命令建立分支结构：

# 创建develop分支
git branch develop

# 创建特性分支示例（实际开发时按需创建）
git branch feature/sensor-driver

# 推送所有分支到远程（若已配置远程仓库）
git push -u origin main develop feature/sensor-driver

若尚未配置远程仓库，可暂不执行推送命令。分支保护规则（如禁止直接推送main）需在GitLab/GitHub等平台设置，不属于本地Git命令范畴。

忽略规则配置

嵌入式项目需忽略编译产物、IDE配置和临时文件。创建.gitignore文件并写入以下内容：

# 编译产物
build/
*.o
*.elf
*.hex
*.bin
*.map
*.lst

# IDE配置
.vscode/
.idea/
*.swp
*.swo

# 调试与日志
*.log
*.tmp
.cache/

# 第三方库（若使用子模块则不应忽略）
# libs/

验证忽略规则是否生效：

# 查看将被跟踪的文件列表
git status --short

# 确认build目录和.o文件未被跟踪
git check-ignore build/main.o

若git check-ignore输出对应文件路径，说明忽略规则正确生效。

验证方法与通过标准

仓库结构验证：执行git log --oneline，应看到至少一条提交记录（Initial commit）。
分支验证：执行git branch -a，应列出main、develop和feature/sensor-driver三个分支。
忽略规则验证：在项目根目录创建临时文件test.o，执行git status，该文件不应出现在未跟踪列表中。
源码完整性验证：执行git ls-files，确认所有源码文件（.c、.h、.s、.ld等）均被跟踪，而编译产物未被跟踪。

常见问题

误提交编译产物：若已提交build/目录，执行git rm -r --cached build/将其从跟踪列表移除，再提交一次即可。
分支命名冲突：若feature/sensor-driver已存在，可改用feature/sensor-driver-v2等唯一名称。
换行符警告：Windows环境下建议在仓库根目录添加.gitattributes文件，内容为* text=auto，统一换行符处理。