STM32 项目 Git 版本管理入门教程
适合人群:从未使用过 Git 的 STM32 嵌入式开发初学者 工具准备:Git for Windows(Git Bash)、GitHub 账号、VPN/代理(可选)
本文面向 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