Git Intro for hardware hackers

Git is a wonderful tool that can multiply the impact of your project or make your project easier to manage by an order of magnitude. Some of us hackers still don’t know how to use Git from the command line, but a recognizable example of why a particular tool would be useful might be a good start. Today I would like to give you a crash course on Git, showing you why and how to insert a KiCad PCB into a Git repository, to then be shared with the world.

KiCad works wonderfully with Git. KiCad schematic and PCB files are human readable, especially when compared to other PCB file formats. KiCad creates different files for different purposes, each with a well-defined role, and you can make sense of each file in your project folder. Plus, you can even edit KiCad files in a text editor! This is exactly the kind of use case that Git fits like a glove.

Not just for software developers

What is Git about, then? Basically, Git is a tool that helps you track code changes in a project and share those changes with each other. Intended for Linux kernel development as a prime target, this is what it was designed for, but its flexibility extends far beyond software projects. We hardware hackers can use it in various ways: we can archive PCBs and other design software files, blog articles, project documentation, personal notes, configuration files, and anything else that even loosely fits the Git modus operandi.

A screenshot of a file explorer, showing the KiCad PCB files of a Jolly Wrencher (Hackaday symbol).
Of course, it is important that these files are stored securely and foolproof.

The first benefit you’ll get from using Git is a backup of your project. In fact, if you upload your git tweaks somewhere, you get two extra copies of your project, one stored in your local .git folder and one uploaded to a place like GitHub or GitLab. In fact, a project stored in Git with an online mirror automatically conforms to the 3-2-1 backup principle. Plus, you’ll have historical backups at your fingertips. Did you redesign your PCB a long time ago and now you urgently need to refer to an older version? As long as you’ve kept the changes in Git, they’re just one command away.

Many people also store configuration files in Git – you may have heard of this practice called dotfile. This helps you keep track of any configuration changes you make. If you’ve ever debugged complex software (for example, a web server) by recombining parameters in its config file, you’ll know how painful it can be to forget a change that worked before and losing a meticulously customized config file is pain on a level. completely different. With just a few Git commands behind you, you avoid a world of pain you may never have known you could avoid.

We hackers often need each other’s help, and in these cases, Git’s collaboration capabilities are second to none. Let’s say you find yourself working on a PCB project with a fellow hacker around the world. With Git, you only need a command to load your latest changes, and your colleague needs a command to download them. If you’ve both made changes in a way they conflict (e.g., changed the same footprint in a different way), Git has a rich change set conflict resolution toolkit, freeing up valuable time that you both might be spending instead. discussing about the high-level design problem.

Hacker, meet Git – Git, meet Hacker

To begin with: you have a PCB project and you have installed a Git shell on your favorite operating system. I also assume you know the basics of your terminal: moving from directory to directory and opening files, we won’t need much else. Git needs a few small variables configured before we can start – let’s fix it and use it as an opportunity to test it git also works in your favorite console.

To track changes, Git wants to know your name and email – they don’t have to be real. If you push the changes to GitHub / GitLab / etc, both the name and the email will be accessible to anyone who can download the repository contents from where you uploaded them, that is, usually anyone. I use my nickname and my old public email address for this, for collaboration purposes and “contact me for this project” – you can do the same or just use John Doe’s defaults if you never upload. Here are the commands to execute, taken from here:

git config --global user.name "John Doe"
git config --global user.email johndoe@example.com

Being --global, these changes only need to be done once on each machine you use to work on Git. Besides these two, help Git know which text editor you prefer to make quick changes – these will be called every now and then. On Linux, you may find that your default editor for git commit is already set to Vi, if you don’t know what :wq! stands for, feel free to run run git config --global core.editor nano for a friendlier option. On Windows, we recommend doing things a little differently.

You are now ready to start. In your terminal, navigate to the folder where your PCB design is stored. Guy git init and press Enter. That’s it – your project folder is now a Git repository!

Adding changes

From here, Git still doesn’t keep track of your project files. Run git statusand you see a group of files marked as “untracked”. git status it helpfully tells you what to do to start following them – in fact, this command does quite a bit of checking for newcomers to Git, as you can see from the output. Let’s add the files we care about, that is, everything but the .kicad_prl file and the -backups/ directory!

$ 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 looking at, but have not yet been placed in the project’s Git history in a way that matters. For this, we need to make a commit, which records a bunch of changes to the files. When starting a repository like this, you usually do an “initial” commit – for that, you can do it git commit -m "Initial commit"where is the -m parameter is a human-readable message describing the meaning of the changes. You can also do git commit and write the message in a separate editor – find out what is most comfortable for you. Since the files were not previously saved, they will be archived in their entirety.

A little bit of commitment

A commit is a kind of “unit of work”, a way to logically group changes. You can navigate between commits in your project history as different stages of your project development, separate some changes contained in commits in a different branch so that you can have multiple different versions of your project coexisting seamlessly, transfer commits between repositories , export and email them, and much more.

It makes sense to keep the changes logically distinct in different commits. Let’s say you improve the screen printing on your PCB and also add a license file. First, add yours .kicad_pcb file and confirm it with the message “silk-screen: pinout added”; then, add yours LICENSE.txt file and commit it as an “added license”. This helps you give an overview of your project history, track down errors, and a host of other things.

If you run git log, you will see the list of commits. Using their hash, you can switch between commits when you need an older version of your project. For that, do it git checkout HASHCHARS, where “HASHCHARS” is at least seven first characters (can be more!) of your commit hash. To go back to the most recent state of your project, do so git checkout HEAD.

There is no need to keep track of everything

git status still shows us the .kicad_prl and the backup directory that does not need to be tracked – these two contain no significant changes. To ignore these two file types, create a .gitignore file (name starting with a dot) in the root directory of your project and put these two entries in it:

*.kicad_prl
*-backups/

As you can see, you can do some simple pattern matches there, but you could also enter the actual project file names – I didn’t want to type them and the more generic version will be useful if you want to copy-paste. git status it will already stop showing these files and when you add and commit the file .gitignore file, these two entries will remain. Do you want a KiCad specific gitignore file that covers most of the cases you will come across? GitHub offers one.

Tracking binary files in Git grows your project folder in a way you might not expect

Git doesn’t understand binary files – it’s designed for human-readable text files that change significantly. KiCad PCB files meet these criteria, a lot of other files don’t. The thing is, each version of a binary file will remain as a copy inside yours indefinitely .git folder, remaining a long time after updating the binary file with a new version. You don’t want to memorize a .zip which changes frequently in your project’s git repository and you don’t even want to store gerber files there. It just takes up extra space and time.

Extra functionality at no cost

Git’s versioning capabilities are useful in PCB development, and there are many subtleties that make it even more convenient to use. For example, if you want to move between project versions faster, you can attach tags to commits. Have you developed a v2 of your PCB, but still need to reference the v1 files for customer support purposes? To do git tag v2 to mark the current commit as “v2” and do so git tag commit v1 HASHCHARS indicating a commit where your PCB was still at v1. Now you can do it git checkout v1 And git checkout v2 to switch between versions as needed.

Let’s say, hypothetically, that you have committed a README.md file – a good practice (feel free to use my README PCB model!). Let’s also say, for the sake of the subject, that you just added some images to your project directory and linked them to the README. Let’s assume you’ve also edited the README to add some completely unrelated changes that belong to a separate commit – maybe you’ve changed a connector on the PCB and reflected it in README. How do you separate the logically different changes you just made to the same file? Use git add --patch README.md to interactively select and choose which parts of the file will be added.

Did you commit something and want to change the last commit message? Use git commit --amend. Do you need to add / remove / modify files in the latest commit? Add your changes and commit --amend. Have you made any changes to a file and want to delete them instead of adding them? Use git checkout path/to/file – you will lose these changes as the file will revert to the currently monitored version. Oh, you can also use --patch with git checkout for partial restoration of changes.

Git has useful subcommands galore. If you want to see the current changes to the project files in the console, use git diff. Have you already added some of the changes and they won’t show up? Use git diff --cached. Both of these commands accept filenames for a more focused overview. There is a lot of complexity that Git is capable of, being a valuable tool for the largest distributed software development efforts. You really don’t need to use any of the fancy features if you don’t want to.

Next step: upload

As you can see, I haven’t covered uploading to an online repository or working with others; these are topics with some important caveats. I’d also like to cover GitLab and GitHub, so you’re not stuck in a single ecosystem. I haven’t even covered branches – a typical PCB project doesn’t need them, but we might talk about it in a future installment. However, you can learn this as you go. You are now equipped to use Git for simple projects!

Leave a Reply

%d bloggers like this: