"Tidy repo policy" - how to make it work with Vivado

Call: +44 (0)23 8098 8890

Posted 6th May 2020, By Tom J
Vivado plus Git icons

At ITDev our values drive our decision making, the way we work and our relationships with our clients, suppliers and peers. We believe in a Smart approach to everything we do, whether that involves cutting edge video encoder development, the latest in open source software development, or something as comparatively trivial as maintaining a neat and tidy project repository.

This blog describes several workflows we have used to limit the number of files which need to be under version control when using Vivado, allowing for smaller and simpler project repositories. A repository should of course contain any source HDL files, the focus of this blog is on workflow suggestions for managing projects which also contain block designs and IP instances.

All FPGA engineers will be familiar with using version control systems in one form or another, and often when we use FPGA design tools such as Xilinx’s Vivado or Intel’s Quartus, we will end up with a large volume of temporary or otherwise inessential files which are generated during the build process. This is especially true for projects which contain multiple Xilinx/Intel IP instances. Maintaining a clean, streamlined and easy to use repository means deciding which of these files should be kept under version control. This can sometimes be challenging, especially since it is not always clear which files are absolutely necessary in order for FPGA tools to work, and which files can be safely discarded and regenerated later. One example would be that when using Altera’s Platform designer in Quartus Pro, removing a .qsys file may not cause failures in the build flow, but will prevent future edits to the IP cores. This can obviously cause problems further along in the development process, and highlights why an in-depth understanding of what the design tools are doing is useful.

Method 1: Keeping everything under version control

After a Vivado project is created it can be difficult to decide which of the project files should be placed under version control. The simplest method is, of course, to commit everything in a project repository, including all of the files generated during IP elaboration as well as log files and output files.


  • No chance of losing files
  • Extensive history of logs and reports
  • Maximum flexibility for IP upgrades, version changes


  • Large and cluttered repository
  • Potential for large and confusing changesets between commits
  • Potential to encounter unnecessary merge issues

Method 2: Partial version control using a tcl script

Vivado contains a tool to wrap an entire project into a tcl script. When Vivado is opened the script can be sourced to regenerate the project.

In the Vivado GUI select:

file->project->write tcl

and Vivado will generate a tcl script containing all the information necessary to regenerate the project. Only the tcl script and IP directories need to be kept under version control, the project file and sub-directories do not need to be committed. You can select whether the generated tcl script also contains any block design tcl scripts, or if they should be kept separately. When opening Vivado, use the tcl console to navigate to the project directory and source the tcl script, this will regenerate the project in its entirety.


  • Lean and tidy repository
  • No project file to commit – only the tcl script
  • Similar method as exporting a BD (Block Design)


  • No record of build logs
  • Must be careful to source the tcl script from the appropriate directory
  • Changesets are not always clear

Method 3: Lean version control using the project file and selected sources

Choosing which files to commit is fairly straightforward if you understand how Vivado manages a project. By using a text editor you can examine the Vivado project file:


to see which files are being sourced when the project opens. The project file will reference all HDL source files and the <pinout_filename>.xdc file. In order to source IP cores, the project file will reference:


Along with the BD file/tcl script, these files represent the bare minimum needed to regenerate the project, block design and IP cores. This means it can be possible to greatly reduce the number of files in a repository, albeit with a sacrifice in flexibility around such things as IP modification, version changes etc.


  • Very lean repository
  • Clear changesets


  • No record of build logs
  • Potential to break things if not handled carefully
  • Can encounter issues when switching vivado version


I’ll demonstrate below by building a small FPGA implementation containing a block design and a single instance of a Xilinx IP core, which targets a Xilinx Zynq Ultrascale+ development board. The repository had been intentionally reduced to the smallest possible size. Let’s take a look at the repository properties before we start a build.

This is the ‘clean’ pre-build directory immediately after checkout from the project repository. The single IP core has only it’s .xci file committed, and there is a tcl script to re-generate the block design. There is also a mixture of VHDL and Verilog source files as well as the Vivado project file and a constraints file. This directory contains 21 files in 5 folders, which constitute all the files necessary for someone to check out the repository and begin development, including opening the project in Vivado and building the FPGA image:

  • <PROJECT_NAME>.xpr
  • <IP_NAME>.xci
  • <BLOCK_DESIGN>.tcl
  • HDL source files

If we open the project in Vivado and source the tcl script file to re-generate the block design, then run both the synthesis and implementation stages, we end up with the following in the same project folder:

FPGA repository screenshot

We can see that the project folder has increased in size by a factor of over 300 during the build process, with Vivado creating several hundred folders and sub-folders containing files which have been generated during the IP elaboration, synthesis and implementation stages. This is a good demonstration of how bloated a version controlled repository can become if all files are blindly committed.


To summarise, it is usually best to take elements from each of these methods to tailor a version control strategy specific to each project. Each approach has its own merits and drawbacks, but by combining a good understanding of how Vivado works with some best practices for version control, it is possible to have a tidy, lean and easily maintainable repository which contains everything the engineers will need.

How ITDev Can Help

At ITDev we believe good engineering practice is essential to delivering high quality, engineered designs. Aligned with this we run a series of events and workshops to help develop industry best practices through collaborative sharing and learning. 

Our team of engineers has extensive experience in FPGA design for both Xilinx and Intel (formerly Altera) devices. We provide technology consultancy as well as hardware & software design services. Initial discussions are always free of charge, so if you have any questions, or would like to find out more, we would be delighted to speak to you. Email us or call us on +44 (0)23 8098 8890.


Main image: Vivado and Git

IET Enterprise Partners logo

Latest Blog Posts

Our product development process
Posted 24th September 2021, By Steve W
In his first in a series of blogs addressing the product development process, Steve looks at how to avoid the pitfalls ...
An empty office and desserted Science Park
Posted 29th January 2021, By Jon O
Having started 2021 much as we ended 2020, we thought it would be good to look back to before the pandemic and reflect on how the year turned out against ...more
Higher level testbench reusing lower level components
Posted 5th January 2021, By Tom J
ITDev recently engaged with an ASIC design company. This blog outlines our verification strategy, and how our knowledge of UVM allowed us to achieve high test ...more
Ladybug in sight
Posted 3rd August 2020, By James H
If debugging a Linux driver is bugging you, this 'how to' guide explains how to approach this using the function tracer within ftrace to find out what’s going ...more

Latest News

Variety is the spice of life
Posted 15th July 2021
The newly re-modeled cafe on the Science Park has put us in a culinary mood but keep on reading and you'll see there's another reason why we chose a spice rack ...more
Supply chain management
Posted 7th June 2021
Recent activities in May include focusing on a number of product development enquiries, helping an aerospace client with support issues and starting ...more
Deep tech
Posted 10th May 2021
News this month includes details of further engagement with our client on Android audio device driver development and a new partnership with the world’s first ...more
SKA at night
Posted 31st March 2021
As our work tends to focus on ‘technologies’ rather than ‘markets’, it’s normal for our portfolio of projects to cover a range of industries.