本文面向 STM32 嵌入式开发初学者，介绍 Git 版本管理基础。内容包括 Git 基本概念、工作区与仓库流程、.gitignore 配置（针对 MDK/EIDE 编译产物）、本地仓库初始化、代码提交与推送至 GitHub 的操作步骤。此外，还整理了常见错误（如远程地址冲突、认证失败、分支问题）的解决方案及日常命令速查表，帮助开发者规范化管理嵌入式项目代码。
适合人群：从未使用过 Git 的 STM32 嵌入式开发初学者 工具准备：Git for Windows（Git Bash）、GitHub 账号、VPN/代理（可选）
Git 是一个版本管理工具，可以记录你每次修改代码的历史，随时可以回退到任意版本。
工作区（你的项目文件夹） → git add → 暂存区（准备提交的文件列表） → git commit → 本地仓库（保存在本机的版本记录） → git push → 远程仓库（GitHub 云端）
| 命令 | 作用 |
|---|---|
git init | 初始化本地仓库 |
git add . | 添加所有文件到暂存区 |
git status | 查看当前状态 |
git commit -m "说明" | 提交到本地仓库 |
git push | 推送到远程仓库（GitHub） |
git remote add origin 地址 | 关联远程仓库 |
git remote -v | 查看远程仓库地址 |
git log --oneline | 查看提交历史 |
打开 Git Bash 执行：
git config --global user.name "你的名字"
git config --global user.email "你的邮箱"
+ → New repositoryCreate repositoryhttps://github.com/你的用户名/仓库名.git
STM32 项目编译后会产生大量中间文件（.axf、.o、.map 等），这些文件不需要上传，通过 .gitignore 告诉 Git 忽略它们。
cd /f/你的项目路径
touch .gitignore
用记事本或 VSCode 打开，填入以下内容：
# ============================================
# MDK-ARM 编译产物
# ============================================
MDK-ARM/*/
# MDK 用户个人配置文件
MDK-ARM/*.uvguix.*
MDK-ARM/*.uvoptx
MDK-ARM/DebugConfig/
MDK-ARM/RTE/
# ============================================
# EIDE 自动生成/缓存目录
# ============================================
EIDE/.cmsis/
EIDE/.vscode/
EIDE/build/
EIDE/.arts/log/
# ============================================
# Drivers 中不必要的大型库
# ============================================
Drivers/CMSIS/DSP/DSP_Lib_TestSuite/
Drivers/CMSIS/NN/
Drivers/CMSIS/RTOS/
Drivers/CMSIS/RTOS2/
Drivers/CMSIS/docs/
# ============================================
# 系统/编辑器垃圾文件
# ============================================
Thumbs.db
.DS_Store
*.suo
.gitignore 必须在 git add .之前配置好git add . 后才修改 .gitignore，需要清空暂存区重来# 第一步：进入项目目录
cd /f/你的项目路径
# 第二步：初始化 Git
git init
# 成功提示：
# Initialized empty Git repository in .../你的项目路径/.git/
# 第三步：先只添加 .gitignore
git add .gitignore
# 第四步：确认 .gitignore 没问题后，添加所有文件
git add .
# 第五步：查看暂存区内容是否正确
git status
APP/BSP/Core/Drivers/ 等源码目录*.axf *.o *.map 等编译产物git commit -m "feat: initial commit - STM32 项目初始提交"
| 类型 | 含义 | 示例 |
|---|---|---|
feat | 新增功能 | feat: 添加霍尔传感器驱动 |
fix | 修复 bug | fix: 修复串口通信异常 |
docs | 修改文档 | docs: 更新注释说明 |
refactor | 代码重构 | refactor: 优化低功耗逻辑 |
chore | 其他修改 | chore: 更新.gitignore |
也可以直接写中文：
git commit -m "初始提交：STM32 项目"
[main (root-commit) xxxxxxx] feat: initial commit
# 第一步：关联远程仓库
git remote add origin https://github.com/你的用户名/仓库名.git
# 第二步：确认分支名称（看括号里是 main 还是 master）
# 如果是 master，改名为 main
git branch -m master main
# 第三步：推送
git push -u origin main
To https://github.com/你的用户名/仓库名.git
* [new branch] main -> main
Branch 'main' set up to track remote branch 'main' from 'origin'.
打开浏览器访问：
https://github.com/你的用户名/仓库名
能看到项目文件 = 上传成功 ✅
每次修改完代码后，执行以下三步：
# 第一步：查看修改了哪些文件
git status
# 第二步：添加所有修改
git add .
# 第三步：提交（修改说明内容）
git commit -m "feat: 描述本次修改内容"
# 第四步：推送到 GitHub
git push
第二次之后推送直接用
git push即可，不需要加-u origin main
error: the following file has staged content different from both the file and the HEAD: .gitignore (use -f to force removal)
原因： 暂存区的文件内容和工作区不一致（先 add 后又修改了文件）
解决：
git rm --cached -r -f .
git add .
error: remote origin already exists.
原因： 远程仓库地址已经设置过了
解决：
# 查看当前设置的地址
git remote -v
# 如果地址正确，直接推送即可
git push -u origin main
# 如果地址不对，修改地址
git remote set-url origin https://github.com/你的用户名/仓库名.git
error: src refspec main does not match any
error: failed to push some refs
原因： 本地还没有任何 commit，分支不存在
解决：
# 先确认是否有提交记录
git log --oneline
# 没有记录则重新提交
git add .
git commit -m "feat: initial commit"
git push -u origin main
fatal: no branch named 'master'
原因： 本地分支已经是 main，不存在 master
解决： 不需要改名，直接推送：
git push -u origin main
fatal: unable to access 'https://github.com/...': Failed to connect to github.com port 443
原因： 网络问题，无法访问 GitHub（被墙）
解决方法一：设置代理（需要有代理工具）
# 把 7890 换成你代理软件实际的端口号
git config --global http.proxy http://127.0.0.1:7890
git config --global https.proxy http://127.0.0.1:7890
# 再次推送
git push -u origin main
解决方法二：取消错误的代理设置
git config --global --unset http.proxy
git config --global --unset https.proxy
git push -u origin main
解决方法三：使用 SSH 方式（彻底解决）
# 生成 SSH 密钥
ssh-keygen -t rsa -b 4096 -C "你的邮箱"
# 查看并复制公钥
cat ~/.ssh/id_rsa.pub
# 去 GitHub 添加公钥：
# Settings → SSH and GPG keys → New SSH key → 粘贴
# 修改远程地址为 SSH
git remote set-url origin [email protected]:你的用户名/仓库名.git
# 推送
git push -u origin main
解决方法四：使用 Gitee 国内平台
# 去 https://gitee.com 注册并新建仓库
git remote set-url origin https://gitee.com/你的用户名/仓库名.git
git push -u origin main
fatal: Authentication failed for 'https://github.com/...'
原因： GitHub 账号密码验证失败（GitHub 已不支持密码登录）
解决： 使用 Personal Access Token 代替密码
repo 权限cd /f/项目路径
git init
touch .gitignore # 创建并编辑 .gitignore
git add .
git status # 检查暂存内容
git commit -m "初始提交"
git remote add origin https://github.com/用户名/仓库名.git
git branch -m master main # 如果分支是 master 才需要执行
git push -u origin main
git add .
git commit -m "描述修改内容"
git push
git status # 查看当前状态
git log --oneline # 查看提交历史
git remote -v # 查看远程仓库地址
git branch # 查看分支
# 撤销 git add（未 commit）
git rm --cached -r -f .
# 撤销最后一次 commit（保留文件修改）
git reset --soft HEAD~1
# 查看某次提交的内容
git show 提交 ID
开始 │ ├─ 新项目？ │ ├─ 是 → git init → 配置.gitignore → git add . → git commit → git remote add → git push │ └─ 否 ↓ │ └─ 修改了代码？ └─ 是 → git add . → git commit -m "说明" → git push
💡 核心记忆口诀：
add暂存 →commit本地存档 →push上传云端 出了问题先看提示，再对照本文错误列表解决！
微信公众号「极客日志」，在微信中扫描左侧二维码关注。展示文案：极客日志 zeeklog
将字符串编码和解码为其 Base64 格式表示形式即可。 在线工具，Base64 字符串编码/解码在线工具，online
将字符串、文件或图像转换为其 Base64 表示形式。 在线工具，Base64 文件转换器在线工具，online
将 Markdown（GFM）转为 HTML 片段，浏览器内 marked 解析；与 HTML 转 Markdown 互为补充。 在线工具，Markdown 转 HTML在线工具，online
将 HTML 片段转为 GitHub Flavored Markdown，支持标题、列表、链接、代码块与表格等；浏览器内处理，可链接预填。 在线工具，HTML 转 Markdown在线工具，online
通过删除不必要的空白来缩小和压缩JSON。 在线工具，JSON 压缩在线工具，online
将JSON字符串修饰为友好的可读格式。 在线工具，JSON美化和格式化在线工具，online