STM32 项目 Git 版本管理入门教程

三、配置 .gitignore

为什么需要 .gitignore？

STM32 项目编译后会产生大量中间文件（.axf、.o、.map 等），这些文件不需要上传，通过 .gitignore 告诉 Git 忽略它们。

在项目根目录创建 .gitignore 文件

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

检查 git status 输出

• ✅ 应该看到：APP/BSP/Core/Drivers/ 等源码目录
• ❌ 不应该看到：*.axf *.o *.map 等编译产物

五、提交代码到本地

git commit -m "feat: initial commit - STM32 项目初始提交"

提交说明规范（可选）

也可以直接写中文：git commit -m "初始提交：STM32 项目"

成功提示：

[main (root-commit) xxxxxxx] feat: initial commit

六、推送代码到 GitHub

# 第一步：关联远程仓库
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

八、常见错误与解决方法

❌ 错误 1：staged content different from both the file and the HEAD

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 .

❌ 错误 2：remote origin already exists

error: remote origin already exists.

原因： 远程仓库地址已经设置过了

解决：

# 查看当前设置的地址
git remote -v

# 如果地址正确，直接推送即可
git push -u origin main

# 如果地址不对，修改地址
git remote set-url origin https://github.com/你的用户名/仓库名.git

❌ 错误 3：src refspec main does not match any

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

❌ 错误 4：no branch named 'master'

fatal: no branch named 'master'

原因： 本地分支已经是 main，不存在 master

解决： 不需要改名，直接推送：

git push -u origin main

❌ 错误 5：Connection was reset / Failed to connect to github.com port 443

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

❌ 错误 6：Authentication failed

fatal: Authentication failed for 'https://github.com/...'

原因： GitHub 账号密码验证失败（GitHub 已不支持密码登录）

解决： 使用 Personal Access Token 代替密码

1. GitHub → Settings → Developer settings → Personal access tokens
2. 点击 Generate new token
3. 勾选 repo 权限
4. 生成后复制 Token
5. 推送时密码处填入 Token

九、日常使用命令速查

初次提交流程

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 操作流程图

开始 │ ├─ 新项目？ │ ├─ 是 → git init → 配置.gitignore → git add . → git commit → git remote add → git push │ └─ 否 ↓ │ └─ 修改了代码？ └─ 是 → git add . → git commit -m "说明" → git push

💡 核心记忆口诀： add 暂存 → commit 本地存档 → push 上传云端 出了问题先看提示，再对照本文错误列表解决！