Git is a wonderful tool that can multiply the impact of your project, or make it easier to manage your project by an order of magnitude. Some of us hackers may not yet know how to use command-line Git, but a related example of why a certain tool would be useful can be a good start. Today, I want to give you a Git crash course – showing you why and how to put KiCad PCBs into a Git repository, to be shared with the world later.
KiCad works wonderfully with Git. KiCad’s schematic and PCB files are human-readable, especially when compared to other PCB file formats. KiCad creates different files for different purposes, each of them with a well-defined role, and you can understand each file in your project folder. What’s more, you can even modify KiCad files in the text editor! This is exactly the kind of use case that Git fits like a glove.
Not just for software developers
What about Git then? basically, Gita is a tool that helps you keep track of code changes in a project and share these changes with each other. The Linux kernel as its first target is intended for development, which is exactly what it is designed for, but its flexibility extends far beyond software projects. We hardware hackers can use it in a variety of ways – we can store PCB and other design software files, blog articles, project documentation, personal notes, configuration files and whatever else ambiguously fits into the git modus operandi .
The first benefit you’ll get from using Git is backing up your projects. In fact, if you upload your git changes somewhere, you get two extra copies of your project – one stored in your local
.git folder, and uploaded to a place like GitHub or GitLab. In fact, a project stored in Git with an online mirror corresponds to 3-2-1 Backup Principle on its own. What’s more – you get historical backups within arm’s reach. Have you redesigned your PCB long ago, and now urgently need to reference an older version? As long as you’re keeping your changes in Git, they’re a single command away.
Many people also store configuration files in Git – you may have heard of this practice called dotfiles Doing so helps you keep track of all configuration changes you’ve made. If you’ve ever debugged complex software (e.g., a webserver) by recompiling parameters in its configuration file, you’ll know how painful it can be when you forget a change that worked – And losing a carefully tailored configuration file is a pain on a whole different level. With a few git commands under your belt, you avoid a world of pain you never knew you could avoid.
Too often, we hackers need each other’s help – and for such cases, Git’s collaboration capabilities are second to none. Let’s say, you find yourself working with a fellow hacker across the globe on a PCB project. With Git, you only need one command to upload your latest changes, and your colleague needs one command to download them. If you both commit changes in such a way that they conflict (say, edit the same footprint in a different way), Git has a rich toolkit for change conflict resolution, allowing you both to have a higher Can free up precious time instead of arguing about -level design. Problem.
hacker meet git git meet hacker
For a start – you have a PCB project, and you install a git shell on the OS of your choice. I also assume that you know the basics of your terminal – going from directory to directory and opening files, we won’t need much more. Git needs to configure some small variables before you start – let’s solve this, and use this as an opportunity to test
git Also works in your console of choice.
In order to track your changes, Git wants to know your name and email – these don’t need to be genuine. If you push your changes to GitHub/GitLab/etc, both the name and email will be accessible to anyone who can download the repository contents from where you uploaded them, i.e. usually anyone . I use my surname and my old public email address for collaboration and for “contact me about this project” purposes – you can do the same, or use the John Doe default if you’ll never upload Use the. Here are the commands you should run, taken from here,
git config --global user.name "John Doe"
git config --global user.email firstname.lastname@example.org
--global, these changes only need to be made once on each machine you use for Git tasks. In addition to these two, it helps to tell Git which text editor you prefer to make quick changes – those that will be called each time. On Linux, you may find that your default editor for git commits is already set to Vi – if you don’t know what
:wq! stands for, feel free to run
git config --global core.editor nano For a more convenient option. On Windows, you’ll want to do Do things a little differently.
Now, you are all set to begin. In your terminal, go to the folder where your PCB project is stored. type
git init and press enter. That’s all – your project folder is now a Git repository!
add your changes
From here on out, Git doesn’t keep track of your project files yet. run
git statusAnd look for a bunch of files marked as “untracked”.
git status help tells you what to do to start tracking them – in fact, this command does quite a bit of handholding for git newcomers, as you can see from the output. Let’s add the files we care about – that is, everything but
.kicad_prl file and
$ git add jolly_wrencher.svg $ git add jolly_wrencher.kicad_mod $ git add jolly_wrencher_pcb.kicad_pro $ git add jolly_wrencher_pcb.kicad_pcb $ git add jolly_wrencher_pcb.kicad_sch $ git status
These files have been added to the list that Git is watching, but they have not yet acted in the project’s Git history in a way that matters. For that, we need to do a commit, which registers a bunch of file changes. Starting a repository like this, you usually do an “initial” commit – for this, you can run
git commit -m "Initial commit"Where
-m A parameter is a human-readable message explaining what the changes mean. you can also
git commit And write the message in a separate editor – see what is more convenient for you. Since the files were not previously committed, they will be archived as a whole.
a bit of commitment
A commit is a kind of “unit of work”, a way of logically changing a group. You can navigate between commits in your project history as different stages of your project’s development, separating some of the commit-implied tweaks into a separate branch so that you can have several different versions of your project from the original. Transfer commits between repositories, export and email them, and so much more.
It makes sense to logically have separate commits in different commits. Say, you edit the silkscreen on your PCB, and you add a license file as well. First, you add your
.kicad_pcb File and commit it with the message “Silkscreen: Added Pinouts”; Then, you add your
LICENSE.txt file and commit it as “Additional License”. It helps you get an overview of your project history, track down mistakes, and a myriad of other things.
if you run
git log, you will see the list of commits. Using their hash, you can move between commits when you need an older version of your project. for that, do
git checkout HASHCHARSwhere “HASHCHARS” is at least seven first characters of your commit hash (there can be more!) To revert to the latest state of your project, do
git checkout HEAD,
No need to track everything
git status still shows us
.kicad_prl And the backup directory that we don’t need to track – these two don’t have meaningful changes. To ignore these two types of files, create a
.gitignore Put the file (name starting with a dot) in the main directory of your project, and put these two entries in it:
As you can see, you can do some very simple pattern matching in there, but you can also put the actual project file names – I didn’t want to type them in, and more generic if you want to copy Version will be easy- pasting
git status already will stop showing these files, and as soon as you add and commit it
.gitignore file, these two entries will remain. Want a KiCad-specific gitignore file that covers most of the cases you’ll come across? GitHub offers a,
Git doesn’t understand binary files – it’s designed for human-readable text files that change in a meaningful way. KiCad PCB files fit that criteria – a lot of other files don’t. The thing is, each version of the binary file will stay inside you as a copy indefinitely.
.git folder, long after you’ve updated the binary file with a newer version. you don’t want to store
.zip Which changes frequently in your project’s git repository, and you don’t want to store gerber files there. It just takes up extra space and time.
Additional features at no cost
The versioning capability of git comes in handy in PCB development, and it has a lot of nuances that make it even more comfortable to use. For example, if you want to move quickly between project versions, you can attach a tag to the commit. Have you developed v2 of your PCB but still need to reference v1 files for customer support reasons? Doing
git tag v2 To tag the current commit as “v2”, do more
git tag commit v1 HASHCHARS Pointing to a commit where your PCB was still on v1. now you can
git checkout v1 And
git checkout v2 To jump between versions as needed.
Suppose, hypothetically, you have committed a
README.md file – a good practice (feel free to use My PCB Readme Template!) Let’s also say, for the sake of argument, that you just added some images to your project directory and linked them in the readme. Let’s say, you edited the readme to add some completely unrelated changes that are in a different commit – perhaps, you changed a connector on the PCB and reflected it in the readme. How do you isolate logically different changes made to the same file? use
git add --patch README.md Interactively pick and choose which parts of the file are added.
Committed something and want to divert the message of the last commit? use
git commit --amend, Need to add/remove/tweak files in last commit? add your changes and
commit --amend, Made some changes to a file and want to get rid of them instead of adding? use
git checkout path/to/file – You will lose these changes as the file will revert to its current tracked version. oh you can also use
git checkout To partially revert the changes.
Git has lots of helpful sub-commands. If you want to see current changes in your project files in console, use
git diff, Have you already added some changes and they won’t show up? use
git diff --cached, Both of these commands accept file names for a more targeted overview. Being a viable tool for most large distributed software development efforts, Git is a lot more complex. If you don’t want to, you don’t really need to use any fancy features.
Next Step: Upload
As you can see, I haven’t covered uploading to online repositories or working with others; These are topics with some important caveats. I’d like to cover GitLab as well as GitHub, so you’re not locked into the same ecosystem. I haven’t covered branches, either – a typical PCB project doesn’t require this, but we can talk about that in a future installment. Still, you can learn it as you go. You are now equipped to use Git for simple projects!