Vivado FPGA 项目 `.gitignore` 到底该怎么写？

做 FPGA 项目时很多人第一次把 Vivado 工程丢进 Git仓库很快就会变得又大又乱。明明只改了几行 RTLgit status却刷出一大片.runs、.cache、.gen、波形文件和日志。再过几轮协作仓库里混进一堆自动生成内容后面谁都不敢轻易清。这篇就专门把这件事理一遍Vivado 工程里哪些内容应该提交哪些应该忽略.gitignore里几个最容易写错的地方又是什么。一句话先说结论Git 要保存的是“设计意图”和“可再生成工程的信息”而不是 Vivado 运行后吐出来的全部结果。为什么 Vivado 工程特别需要.gitignoreVivado 和一般的软件工程不太一样。一个工程目录里除了我们真正关心的 RTL、约束、脚本、IP 配置还会生成大量中间文件综合和实现目录仿真输出波形文件缓存目录日志和临时文件Bitstream、DCP 这类构建结果这些文件有几个共同特点体积大变化频繁很多都可以重新生成提交到 Git 后几乎没有 review 价值所以.gitignore的核心思路非常简单保留自己写的内容保留能重建工程的配置忽略工具自动生成结果先弄清.gitignore到底生效在哪很多人以为.gitignore写上规则就万事大吉其实不是。它只对“还没有被 Git 追踪的文件”生效。如果某些文件已经进过版本库后面再补.gitignore这些文件不会自动消失。这时候要做一次索引刷新gitrm-r--cached.gitadd.gitstatus这里的--cached很关键它只会把文件从 Git 的追踪列表里移除不会删掉你本地文件。如果确认状态没问题再提交一次gitcommit-mchore: update gitignore and remove generated files.gitignore里最常用的几个匹配符号Vivado 工程里经常会用到下面几个规则写法含义*匹配当前层级任意字符**跨多层目录匹配/表示目录层级!反忽略把前面忽略的内容重新放回来举几个最常见的例子*.log表示忽略所有日志文件。ip/**/hdl/表示忽略ip/下面任意深度的hdl目录。!ip/**/*.xci表示把ip/目录下所有.xci文件重新纳入版本管理。ip/、ip/*、ip/**到底有什么区别Vivado 工程里最容易写错的就是 IP 相关规则尤其是想保留.xci、忽略其余自动生成文件的时候。这三个写法差别不小写法作用ip/忽略整个ip目录及其全部内容ip/*只忽略ip下面第一层内容ip/**忽略ip下所有层级内容很多人会这么写ip/ !ip/**/*.xci看起来像是“先忽略整个 IP 目录再把.xci放回来”但这样经常不生效。原因是父目录已经整体被忽略Git 很可能不会继续往里面扫描。更稳妥的写法是ip/** !ip/ !ip/**/ !ip/**/*.xci这套规则的意思是先忽略ip下所有内容再把目录层级本身恢复出来最后只保留.xci如果你有自己手写的 wrapper 也放在ip/下还可以补一条!ip/**/*_wrapper.v这里不建议偷懒写成!ip/**/*.v因为这样会把 Vivado 自动生成的hdl/*.v、sim/*.v也一并恢复仓库马上又会脏起来。Vivado 工程里哪些应该保留这个问题其实可以用一句话判断它是不是你手工维护、而且丢了之后很难准确恢复的内容。通常建议保留这些内容是否保留原因rtl/保留自己编写的 RTL 源码tb/保留Testbench 和验证代码constraints/保留XDC 管脚与时序约束scripts/保留Tcl、Python、Shell 自动化脚本docs/保留设计说明、调试记录、学习笔记*.xpr可保留Vivado 工程入口文件*.xci必须保留IP 配置文件是重建 IP 的关键*_wrapper.v视情况保留手工维护的封装文件README.md保留项目说明和构建方式其中最值得强调的是*.xci。如果你项目里用了 FIFO、ILA、FIR、DDR MIG 这类 IP真正要纳入版本管理的核心通常不是生成出来的一堆 HDL而是这个 IP 的配置文件。只要.xci在工程就有机会在另一台机器上重新生成。哪些内容更适合直接忽略下面这些一般都不建议进 Git内容原因.cache/Vivado 缓存目录.runs/综合与实现输出.sim/自动仿真目录.gen/自动生成文件.hw/Hardware Manager 相关数据ip_user_files/IP 导出结果*.dcpDesign Checkpoint体积大且可重建*.bit、*.bin、*.mcs典型构建产物*.ltxILA probe 文件*.jou、*.log、*.str日志类文件*.wdb、*.vcd仿真波形结果ex_design/IP example design通常没必要入库如果你的仓库里这些内容已经很多了建议尽早清一次不然后面每次切分支、合并、拉代码都会很痛苦。一种比较干净的 IP 管理方式我更推荐把ip/目录当成“配置文件区”尽量只放各类 IP 的.xci例如ip/ ├── ila/ │ └── ila_top/ │ └── ila_top.xci ├── fifo/ │ └── fifo_async/ │ └── fifo_async.xci └── fir/ └── rbw_filter/ └── rbw_filter.xci而自己写的封装、调试适配模块则尽量放回 RTL 目录rtl/ └── debug/ └── ila_wrapper.v这样目录职责会很清楚ip/放 IP 配置rtl/放自己维护的源码后面.gitignore也更容易写干净。一份可以直接复用的 Vivado.gitignore如果你现在就想整理工程可以直接从下面这份开始# # Vivado generated folders # *.cache/ *.hw/ *.ip_user_files/ *.runs/ *.sim/ *.gen/ ex_design/ # # Vivado generated files # *.jou *.log *.str *.backup.log *.debug *.dcp *.bit *.bin *.mcs *.ltx # # Vivado IP management # Keep only IP configuration # ip/** !ip/ !ip/**/ !ip/**/*.xci # Optional: keep manually written wrappers !ip/**/*_wrapper.v # # Simulation results # *.wdb *.vcd # # Editor files # .vscode/ *.code-workspace # # Operating system files # Thumbs.db desktop.ini # # Temporary files # *.tmp *.bak *.swp *.un~这份规则不一定覆盖你所有工程但对大多数常见的 Vivado FPGA 项目已经够用了。如果你工程结构比较特殊比如需要额外保留某些脚本生成结果wrapper 全放在ip/下仓库里还混了 SDK、驱动或上位机代码那就在这份基础上按项目结构微调不要一上来就无脑复制别人的完整模板。改完以后怎么检查规则有没有生效最直接的办法有两个。第一种看状态gitstatus第二种精准定位某个文件为什么被忽略gitcheck-ignore-v文件路径例如gitcheck-ignore-vip/ila/ila_top/hdl/ila_v6_2_syn_rfs.v它会告诉你到底是.gitignore里的哪条规则生效了。排查“为什么这个文件还在”或者“为什么这个文件不见了”时这个命令很好用。最后收个口Git 到底该保存什么如果把这件事再压缩成一句工程化判断标准那就是Git 应该保存这些RTL 源码 约束文件 Testbench IP 配置 脚本 文档Git 不应该保存这些缓存 自动生成源码 综合与实现结果 Bitstream 仿真波形 日志真正好用的仓库不是“什么都在”而是别人拿到以后知道该看什么也知道怎么重新生成剩下的东西。对 Vivado 工程来说.gitignore写对了后面的协作、备份和版本回退都会轻松很多。如果你也在整理 FPGA 工程仓库建议先把ip/和.runs/这两块捋干净收益通常是最大的。