Summary： Git is a system for source files versioning. That means that it can keep track of the changes of your project. It was developed for programming source files but it can be used with any kind of files. You can use it for a single project on your hard drive, sync it with your own server or to a massive server like github. Git is a very complex tool and there is a lot of great learning materials on the Internet. This article is meant like a starter to show some Git possibilities.
“Git is a free and open source distributed version control system designed to handle everything from small to very large projects with speed and efficiency. “ - https://git-scm.com/
Git is a system for source files versioning. That means that it can keep track of the changes in files. It is more suited for programming source files but it can be used with any kind of files. And the distributed part means that you can use it for a single project on your hard drive, sync it with your own server or to a massively multi user server like github.
But why use Git as it does not understand KiCad files? There are still many good reasons for Git and KiCad combintaion:
Git is a very complex tool and there is a lot of great learning materials on the Internet. This article is meant more like a starter to show the possibilities than a comprehensive reference.
Project – files of your project
Repository – place where the files are stored. Project can have multiple repositories. It can be as simple as .git sub directory in your working directory or a multi-user server with thousands of users and repositories like github...
Clone – process of creating new working directory from a repository
Commit - „snapshot“ of your files at given time. Snapshot are identified by a hash ID – usually only first few letters are used. Commit is the basic unit of project change. You should commit as often as possible with the logically related changes in files. It is up to the user to find his/her way how to organize commits.
Merging – process of merging multiple commits. i.e. if you do some work in your project and at the same time someone else makes changes on the remote server. When you try to send your commits to the server Git will inform you that there are commits on the server and that these commits need to be merged with yours. Git can automatically merge the commits if there are no conflicts. With KiCad it means that you need to merge the changes manually most of the time. This is the main disadvantage of using Git with KiCad.
Working directory – this is the actual directory with your files. You can create as much working directories as you need by cloning. The working directory can be “dirty” - that means that there are changes in your directory that are not committed. Some operations can not be done on dirty directories – i.e. changing branch, reverting to a previous commit, …. This is to protect you from loosing your work.
First you need to install Git for your operating system. The procedure is well documented on Git website. You can either use it from command line or you can use one of many GUIs. One of the most popular GUI for Windows is https://tortoisegit.org/ . We will use commands for the command line in this article but it is easy to do the same in most of the GUIs.
In this article we will create a simple repository in your existing KiCad project. You can connect it to remote repositories (i.e. on github) later if you want.
First you need to initialize Git in your project directory. Do it with
git init
Git will not touch any files in the directory and it will just create the .git sub directory where Git stores all its files. The project directory is the first working directory from now on.
Now you can add files under Git control using
git add *
This command will take all the files and add them under Git control. It still does not do anything with the files, it just instructs Git to monitor the changes in these files.
Now you can commit them with
git commit -a
Git will ask for a commit message and then it will store the actual version of the files. Ususally it is better to close the files in KiCad so you are sure that the files are properly saved to disk.
You can see history of your files with
git log
As Git can not show you the changes in files visually be sure to write a good and descriptive commit messages – i.e. “Rerouted MCU power traces”. There are tools to visually show differences between two KiCad commits but they are out of scope of this article.
You can revert your repository to previous commit by
git reset --hard commitID
this is useful for the case when you need to return to a previous version. If you want to just look at previous version it is better to clone project into a temporary working directory and revert there:
cd temporary_directory
git clone file:///path-to-your-project
git checkout commitID
The main difference is that in the first example (git revert) you reverted the whole directory to the specified commit and next commits will continue based on that commit. With git checkout you are in „detached head state“ - that basically means that your next commits would not belong to any branch. You can make a new branch based on that commit if you want to continue working on this version but you are not yet sure if you want to revert the whole project.
Branches are great tool to organize your files. For example you can create a branch of your project, do some experiments and either merge it into your main branch or abandon it. Your main branch is by default named master or main.
For example you want to try change micro USB connector to USB-C. You can create a new branch named usbc:
git checkout -b usbc
this will create new branch and switch your working directory to it. Now you can create commits in this branch.
If you want to return to the master branch:
git checkout master
And you can merge the usbc branch into the actual branch with:
git merge usbc
The merging process can be automatic if there are changes only in one branch or if the changes do not conflict. It there are conflicts, you need to resolve them – this can be very tedious work in KiCad.
Tags can be used to mark important commits - i.e. „schema finished“, „gerbers sent for fabrication“,…
You can create a tag with
git tag -a gerberssent
you can switch to previously definied tag by
git checkout gerberssent
You can set your repository to track the remote repository. This means that you can send your commits to the remote repository (push) and receive commits from it (pull). Typical example is github. Simpler example for small team is shared folder on a server.
git remote add origin https://github.com/user/repo.git
git push origin
git pull origin
Submodule is another project “linked” into your project. With KiCad they can be useful for organizing your libraries.
For example you can create separate project with the library of your vetted parts and then add it to your KiCad project as submodule. It will add the current version (head) of the submodule and you need to update it manually if needed. This means that even if there are changes in the library it will not change in your project without you knowing…
Git is a very versatile tool and while it is oriented more towards programming it can be very useful with any other files – like KiCad Projects.