Git is useful tool for versioning projects. The git repository of a project can then be shared using a hosting service, like GitHub. Use it! This section describes a recommended layout of a project that can be version using git and shared with others. It assumes a basic familiarity with git and GitHub. If you do not know how to track a simple file, read the documentation.
A git repository should be initialized inside the top-level of the project directory. The project directory is the directory containing the project.pro file.
At the minimum, you should track the following files created by KiCad.
You might also need to track any custom component/footprint libraries. Instructions for that are given in a separated section. Most importantly, you should never track any files automatically generated by KiCad. Add the following .gitignore to your repository to enforce this rule.
# Generic backup files
*~
\#*
.\#*
# KiCad backup files
*.bak
*.bck
*.kicad_pcb-bak
# KiCad generated files
*.erc
*.net
*-cache.lib
*-rescue.lib
Quite often, one might need to add custom components to a KiCad schematic. The library files with all of the custom components used by the project must be included inside the repository. The makes it easy for anyone to checkout a consistent project.
There are two ways to store external libraries. They can either be included directly inside the git repository or link to an external repository using git submodules. The latter is useful if you want to share symbols among several projects. The following subsections describe both approaches.
Independent of the approach, it is important to use relative paths when adding a "User defined search path" to a KiCad project. The relative path is specified in a pop-up dialog when adding a new search path.
Start by creating a new directory inside your KiCad project called library. Next follow the KiCad tutorial on creating new components. When saving the library, use the library directory inside your project. When adding library to User defined search path, make sure answer yes to the "use relative path" dialog.
Make sure to track the following files inside the library directory.
The component libraries can be stored inside a dedicated git repository. This allows you to share the definitions between several projects without the need to maintain several copies. The git submodules features can be used to link the extra repository to the project repository. It allows one to automatically clone the library repository when the project repository is cloned. In addition the link is to a specific commit in the library repository, so the result of the clone operation will be a consistent state.
The git submodules documentation explains how to use this git feature in detail. Some helpful commands to add an external KiCad library repository as a submodule are given below.
The first step is to create a library repository. This is similar to the procedure used to track a KiCad project inside git. You should use the same .gitignore as recommended for it. The only difference is that the git repository should be initialized inside the library directory mentioned inside the Using Component Library Editor guide. Also the library directory should not be located inside your KiCad project at this stage. It will be added to the project later as a submodule.
After you have created a library repository and published it on GitHub, or want to add someone else's repository, add it to your KiCad project as a submodule. This is done by running the following command inside your project directory:
git submodule add https://gitlab.cern.ch/berkeleylab/kicad-components.git library
The second to last argument is the path to the existing library repository. The last argument is the directory that the submodule will be stored inside your project repository. It has to be added to the project's search path using the Preferences -> Component Libraries window. Make sure to define it as a relative path.
The submodule is treated as its own git repository. You can run git add/rm/commit/fetch/rebase inside the submodule directory. If you push commits, they will be sent to the library repository and the reference in the project repository will be updated.
By default, git does not clone any of the submodules. You need to tell it to do so with the --recurse-submodules option. For example,
git clone --recurse-submodules git@github.com:kkrizka/powerboard_mass_test_adapter_active.git