FPGA工程Git常用操作手册

一、基础概念

1.1 核心区域划分

工作区：你电脑里能看到的工程文件夹，直接修改代码的地方
暂存区 ：git add 之后文件存入的临时区域，用于筛选本次要提交的内容
本地仓库 ：git commit 之后代码存入的本地版本库，所有历史版本都保存在这里
远端仓库：Gitee/GitHub 上的云端仓库，用于备份和多人协作

1.2 关键名词解释

HEAD：指针，永远指向你当前所在分支的最新一次本地提交，可理解为「当前版本定位标记」
master/main：主分支，用于存放验证通过的稳定版本
功能分支：基于主分支创建的临时分支，用于新增功能调试，不影响主分支稳定代码

二、首次提交源码流程（从0到远端备份）

适用于仓库初始化后，第一次批量提交源码文件。

2.1 检查仓库状态

在工程任意子目录均可执行，查看当前文件状态：

bash 复制代码

git status

红色文件：未跟踪/未暂存的修改
绿色文件：已进入暂存区，等待提交

2.2 添加指定文件到暂存区

仅添加当前目录下所有 .sv 源码文件

bash 复制代码

git add *.sv

递归添加工程所有子目录下的 .sv 文件

bash 复制代码

git add '*.sv'

注意：单引号不可省略，作用是让 Git 全局匹配所有层级子目录

2.3 撤回暂存区的文件

如果误添加了临时文件，将其撤出暂存区（不删除本地文件）：

bash 复制代码

git reset HEAD 文件名

2.4 提交到本地仓库

填写清晰的提交说明，完成本地版本存档：

bash 复制代码

git commit -m "提交说明：比如首次提交核心SV源码"

2.5 推送到远端仓库（首次推送）

第一次推送主分支需要绑定远端跟踪关系：

bash 复制代码

git push -u origin master

绑定成功后，后续推送直接执行即可：

bash 复制代码

git push

三、功能调试分支工作流（推荐）

新增功能、修改逻辑调试时使用，完全不影响主分支稳定代码，改坏可一键复原。

3.1 新建功能分支并自动切换

基于当前主分支的稳定版本，创建调试分支：

bash 复制代码

git checkout -b 分支名
# 示例：git checkout -b feat_debug

3.2 查看所有分支

bash 复制代码

git branch

带 * 标记的为当前所在分支

3.3 切换分支

bash 复制代码

# 切回稳定主分支
git checkout master

# 切回功能调试分支
git checkout feat_debug

3.4 功能验证通过：合并到主分支

bash 复制代码

# 1. 先切回主分支
git checkout master

# 2. 将调试好的功能分支合并进来
git merge feat_debug

# 3. 同步推送到远端备份
git push

3.5 功能验证失败：废弃调试分支

bash 复制代码

# 1. 切回主分支，代码自动恢复为稳定版本
git checkout master

# 2. 可选：删除废弃的调试分支
git branch -D feat_debug

四、代码回退与复原方法

4.1 仅修改了文件，未执行 git add（工作区回退）

改完发现逻辑错误，直接恢复成上一次提交的原样：

bash 复制代码

git restore 文件名
# 示例：git restore top.sv

4.2 已执行 git add，未 commit（暂存区回退）

bash 复制代码

# 1. 先从暂存区撤回
git reset HEAD 文件名

# 2. 再恢复文件内容
git restore 文件名

4.3 已执行 git commit，未 push（本地提交回退）

回退到上一个稳定版本，丢弃本次错误提交：

bash 复制代码

git reset --hard HEAD^

HEAD^ 代表上一个提交版本，HEAD~3 代表往前第3个版本
也可通过 git log --oneline 查看提交哈希，指定回退到对应版本：
bash 复制代码
```
git reset --hard 版本哈希值
```

五、常用查询命令

查看提交历史（精简显示）
bash 复制代码
```
git log --oneline
```
查看当前分支
bash 复制代码
```
git branch
```
查看远端仓库地址
bash 复制代码
```
git remote -v
```
一键跳转到仓库根目录
bash 复制代码
```
cd $(git rev-parse --show-toplevel)
```

六、注意事项与避坑指南

子目录执行 ：所有 git 命令在工程任意子目录都可执行，Git 会自动向上查找 .git 目录，作用范围为整个仓库，仅文件路径显示为相对路径。
通配符使用 ：不加引号的 *.sv 仅匹配当前目录；加单引号的 '*.sv' 由 Git 解析，递归匹配所有子目录。
临时文件 ：.old 后缀、temp_ 开头的调试文件建议不要提交，保持仓库仅存放有效源码。
仿真产物 ：建议在仓库根目录添加 .gitignore 文件，忽略 .fsdb、.log、编译中间目录等非源码文件，保持仓库干净。