小乌龟Git全程图形化操作指南：嵌入式本地版本管理与Gitee私有云备份实战

前言

对于单片机开发者（STM32/Keil）、硬件工程师（Altium Designer）以及Python脚本编写者而言，代码和设计的版本管理往往被忽视。一旦项目复杂或需要跨设备工作，混乱的文件版本会成为灾难。本文提供一套全程图形化、无需命令行的解决方案，使用TortoiseGit（小乌龟）建立本地版本控制，并自动备份到Gitee私有仓库，确保你的项目安全且可追溯。

一、环境准备与基础配置

安装TortoiseGit
下载并安装 Git for Windows（官方基础环境）
下载并安装 TortoiseGit（图形化壳层）
（可选）安装中文语言包以获得中文界面
首次配置（必须做！）

在项目文件夹中：
右键 → TortoiseGit → 设置 → Git
填写全局身份信息：
- 名称：你的昵称（如 Developer）
- Email：你的邮箱（用于提交记录）
点击"确定"

二、创建本地仓库与.gitignore配置

2.1 初始化仓库

新建项目文件夹（如 D:\STM32_Project）
进入文件夹 → 右键空白处 → Git在这里创建版本库
保持默认（不要勾选"创建裸仓库"）→ 确定
出现绿色对勾标志，表示初始化成功

2.2 创建.gitignore文件（关键步骤）

在项目根目录新建文本文档，改名为 .gitignore（确保显示扩展名），粘贴以下内容：

gitignore 复制代码

# ============================================
# 嵌入式+硬件开发综合忽略规则
# 适用：STM32/Keil + VS Code/Python + Altium Designer
# ============================================

# ============================================
# 1. Keil/STM32 工程文件
# ============================================
# 个人IDE配置（窗口布局、断点等）- 必须忽略
*.uvoptx
*.uvguix.*
*.uvmpw.*
*.dbgconf

# 编译生成文件（全部忽略）
*.axf
*.bin
*.hex
*.elf
*.map
*.lst
*.dep
*.crf
*.d
*.o
*.obj
*.lib
*.lnp
*.iex
*.htm

# 编译输出目录
Objects/
Listings/
Debug/
Release/
build/

# 分散加载文件（如果用Keil默认的，取消下面注释）
# *.sct

# ============================================
# 2. VS Code + Python项目
# ============================================
# Python字节码
__pycache__/
*.py[cod]
*$py.class
*.so
.Python

# 虚拟环境（可重建）
env/
venv/
ENV/
.venv

# VS Code个人配置（保留工作区设置）
.vscode/settings.json
.vscode/launch.json
.vscode/*.code-snippets

# Jupyter Notebook检查点
.ipynb_checkpoints

# 测试与分发
*.egg-info/
dist/
build/
.pytest_cache/
.coverage
htmlcov/

# ============================================
# 3. Altium Designer电路设计（关键！）
# ============================================
# 自动生成文件和目录
History/
__Previews/
Project Logs for */
Project Outputs for */

# 项目结构（可重建）
*.PrjPcbStructure

# 报告和临时文件
*.Cam
*.Drc
*.html
*.txt
*.~SchDoc
*.~PcbDoc
*.~PrjPcb
*.SchDocPreview
*.PcbDocPreview
*.PcbLibPreview
*.SchLibPreview

# 制造输出文件（Gerber等应在Release附件提供）
Gerber/
Drill/
*.GTL
*.GBL
*.GTO
*.GBO
*.GTS
*.GBS
*.GKO
*.GM1
*.DRL
*.APR
*.APR_LIB

# 仿真结果
*.sdf
*.sdb

# ============================================
# 4. 通用单片机/PlatformIO
# ============================================
.pio/
.pioenvs/
.piobuild/
.clang_complete
.gcc-flags.json
*.elf
*.eep
*.lss
*.sym

# ============================================
# 5. 系统通用垃圾文件
# ============================================
*.log
*.tmp
*.cache
.DS_Store
Thumbs.db

重要提示：

保留文件：.uvprojx（Keil项目）、.SchDoc（原理图）、.PcbDoc（PCB设计）
必须忽略：Objects/、History/、__pycache__/、Gerber/

三、日常版本管理核心流程

3.1 标准工作循环

复制代码

开始工作 → 编码 → 阶段性提交 → 继续工作 → 提交 → ... → 结束工作推送云端

3.2 提交更改（核心操作）

第一步：添加文件

新建文件后 → 右键点击文件 → TortoiseGit → 添加（Add）
或直接在提交窗口勾选"未版本控制"的文件

第二步：提交

在文件夹空白处右键 → Git提交© → "master"
在弹出窗口中：
- 左侧勾选要提交的文件（红色=修改，蓝色=新增）
- 填写清晰的提交说明：
  复制代码
```
feat: 添加ADC多通道采样功能

- 配置DMA传输
- 实现四通道轮询
- 测试通过：采样率1kHz
```
点击 "提交" 按钮

第三步：查看历史

右键 → TortoiseGit → 显示日志
双击某次提交可查看具体修改了哪些文件

3.3 分支管理（强烈推荐）

为什么要用分支：

master：稳定版本，随时可编译运行
dev：日常开发，新功能试验场

操作流程：

创建开发分支：
- 右键 → TortoiseGit → 创建分支 → 名称输入dev → 确定
切换到开发分支：
- 右键 → TortoiseGit → 切换/检出 → 选择dev → 确定
开发完成后合并：
- 切回master → 右键 → TortoiseGit → 合并 → 选择dev → 确定

3.4 撤销与急救操作

场景操作步骤注意

放弃未提交修改右键文件 → TortoiseGit → 还原（Revert）会丢失当前修改，回到上次提交状态

修改最后一次提交提交窗口勾选"修改上一次提交（Amend）" 仅适用于尚未推送到远程的提交

临时保存进度右键 → TortoiseGit → 贮藏更改（Stash）→ 输入描述适合紧急切换任务，完成后"弹出贮藏"恢复

四、关联Gitee私有仓库（云备份）

4.1 在Gitee创建私有仓库

访问 https://gitee.com 注册/登录
右上角 "+" → 新建仓库
填写配置：
- 仓库名称：英文（如stm32-motor-control）
- 仓库介绍：简短描述项目
- 私有/公开：务必选择"私有"（带锁图标🔒）
- 初始化仓库：取消勾选 "初始化readme文件"
- 分支模型：选择"单分支模型（只创建master分支）"
点击 "创建"
复制HTTPS地址：https://gitee.com/你的用户名/仓库名称.git

4.2 配置本地仓库关联远程

右键项目文件夹 → TortoiseGit → 设置 → Git → 远端
填写：
- 名称：origin（标准远程仓库名）
- URL：粘贴刚才复制的HTTPS地址
- 推送URL：留空（默认与URL相同）
- Putty密钥：留空（使用HTTPS不需要）
点击 "添加/保存" → 确定

4.3 首次推送代码到Gitee

右键空白处 → TortoiseGit → 推送（Push）
配置选项：
- 远端：选择origin
- 本地分支：master
- 远程分支：勾选并输入master
- 设置上游/跟踪远程分支：勾选（建立长期关联）
- 强制推送：不勾选
点击 "确定"
身份验证：
- 用户名：Gitee手机号/邮箱
- 密码：Gitee登录密码
- 勾选"记住凭证"（Windows会保存，后续无需重复输入）

验证成功：刷新Gitee网页，应能看到所有本地文件和提交历史。

五、多设备同步工作流

5.1 场景说明

在公司电脑A开发，回家后用电脑B继续工作。

5.2 电脑A（上传）

text 复制代码

编码完成 → 右键 → Git提交 → 填写说明 → 右键 → TortoiseGit → 推送 → 完成

5.3 电脑B（下载）

首次获取：

新建文件夹 → 右键 → Git克隆
URL输入：https://gitee.com/用户名/仓库名.git
点击确定，下载完整项目

日常更新：

开始工作前：右键 → TortoiseGit → 拉取（Pull）
工作完成后：右键 → TortoiseGit → 推送（Push）

5.4 冲突处理

如果两台电脑修改了同一文件的同一位置：

拉取时会提示冲突
TortoiseGit会弹出冲突解决工具
手动选择保留本地修改、远程修改，或合并两者
解决后重新提交并推送

六、嵌入式开发特别注意事项

6.1 Keil项目配置要点

保留：.uvprojx（项目文件，含源文件列表和编译选项）
忽略：.uvoptx（个人调试配置，含断点和窗口布局）
分散加载：如果使用自定义.sct文件（如外接SRAM），从.gitignore中删除*.sct规则，确保提交该文件

6.2 Altium Designer项目管理

必须版本控制：.SchDoc、.PcbDoc、.PrjPcb、.SchLib、.PcbLib
必须忽略：History/（AD自动生成，Git已管理历史）、Project Outputs for */（Gerber等制造文件）
大文件处理：如果.PcbDoc超过50MB，使用Git LFS或单独备份，避免仓库膨胀

6.3 Python脚本管理

确保忽略__pycache__/和虚拟环境目录
保留requirements.txt记录依赖
保留.vscode/tasks.json（如果定义了编译/烧录任务），但忽略settings.json（个人设置）

七、常见问题排查

问题现象原因解决方案

提交按钮灰色不可用文件未添加到版本控制右键文件 → TortoiseGit → 添加；或在提交窗口勾选"未版本控制"文件

推送被拒绝（rejected）云端有本地没有的提交先执行拉取（Pull）合并更新，再推送

忘记Gitee密码 Windows凭证过期控制面板 → 凭据管理器 → 删除gitee相关凭据 → 重新推送输入密码

忽略文件失效文件已被Git追踪右键文件 → TortoiseGit → 删除并添加到忽略列表

中文注释显示乱码编码问题 TortoiseGit设置 → 差异查看器 → 勾选"使用UTF-8编码"

误删文件恢复需要找回历史版本右键 → TortoiseGit → 还原 → 选择文件；或从日志中导出旧版本

八、每日检查清单

工作开始前

（多设备时）拉取最新代码：右键 → TortoiseGit → 拉取

工作进行中

小步提交：每完成一个功能点（如配置好一个外设）就提交一次
提交信息规范：使用前缀如feat:（新功能）、fix:（修复）、docs:（文档）
及时贮藏：紧急切换任务时，使用贮藏更改保存进度

工作结束后

提交所有修改：右键 → Git提交
推送到云端：右键 → TortoiseGit → 推送
验证：登录Gitee网页确认代码已上传

每周维护

查看分支图：右键 → TortoiseGit → 版本分支图，确保结构清晰
清理分支：删除已合并的临时分支
检查仓库大小：确保没有意外提交大文件

九、总结

使用TortoiseGit管理嵌入式和硬件项目的核心原则：

隔离垃圾：通过完善的.gitignore确保编译输出和临时文件不进入版本控制
原子提交：小步快跑，每个功能点独立提交，历史清晰可追溯
云端保险：Gitee私有仓库作为远程备份，确保代码永不丢失
分支隔离：master保持稳定可运行，dev用于大胆尝试新功能

现在就开始：选择一个现有项目，按本文步骤配置，30分钟后即可享受专业级的版本管理体验。