STM32 项目 Git 版本管理实战指南

提交说明建议遵循规范，例如 feat 表示新增功能，fix 表示修复 bug，这样在查看历史时更清晰。

远程同步

将本地仓库关联到 GitHub 并推送：

# 关联远程仓库
git remote add origin https://github.com/你的用户名/仓库名.git

# 确认分支名称（新版 Git 默认为 main，旧版可能是 master）
git branch -m master main

# 推送代码
git push -u origin main

推送成功后，浏览器访问仓库地址即可看到文件列表。验证是否成功是必要的步骤，防止因网络问题导致静默失败。

日常更新流程

每次修改完代码后，无需重复初始化，只需三步走：

1. 查看状态：git status 了解哪些文件被修改。
2. 暂存修改：git add . 将所有改动加入暂存区。
3. 提交并推送：git commit -m "描述本次修改" 然后 git push。

第二次之后推送直接用 git push 即可，不需要再加 -u origin main。

常见问题排查

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

现象：提示 .gitignore 文件内容不一致。 原因：暂存区的文件内容和工作区不一致（先 add 后又修改了文件）。 解决：

git rm --cached -r -f .
git add .

错误 2：remote origin already exists

现象：报错远程仓库已存在。 解决：直接查看当前地址是否正确，若正确则直接推送；若不对则修改：

git remote set-url origin https://github.com/你的用户名/仓库名.git

错误 3：Connection was reset / Failed to connect to github.com

现象：无法连接 GitHub 端口 443。 原因：网络问题或被墙。 解决：

• 设置代理（需有代理工具）：

  git config --global http.proxy http://127.0.0.1:7890
  git config --global https.proxy http://127.0.0.1:7890
  

• 使用 SSH 方式（推荐）：生成密钥并添加到 GitHub，将远程地址改为 [email protected]:...。
• 使用国内平台如 Gitee 替代。

错误 4：Authentication failed

现象：HTTPS 密码验证失败。 原因：GitHub 已不支持密码登录。 解决：使用 Personal Access Token 代替密码。在 GitHub Settings → Developer settings → Personal access tokens 生成 token，推送时在密码处填入 token。

命令速查

• 初次提交流程：cd 进入目录 → git init → 配置 .gitignore → git add . → git commit → git remote add → git push。
• 日常更新：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

记住核心流程：add 暂存 → commit 本地存档 → push 上传云端。遇到问题先看终端提示，再对照上述方案排查。