Git and CircuitPython

Programming without version control is hard. Each time I try something, I risk breaking what was already working. More often than not, I find I don't remember how I got it working. Or maybe there's a persnickety little typo I just can't find. Or maybe the program hasn't changed, and something else is causing the issue. Without version control, how can I know?

Programming with CircuitPython is fun. Getting started is easy. Making changes is fast. I started with a working example, and added another sensor, and changed the name, and now it... wait. Why isn't it working? What happened? What changed?! I wish I had git.

The problem

In a normal git repository, the version history is stored inside the hidden .git folder. But these histories can take up a lot of space, which is a problem since CircuitPy devices only have a couple MB. As an added nuisance, each commit would be a write that triggers auto-reload. It would really be nice if there was a way to use git directly on the CircuitPy drive, but have the actual .git folder somewhere on your local computer. Although there is such a method released back in git 2.5 called git worktree, it expects the new directory to be empty. So what can we do?

Creating a worktree

Let's say you have a brand new git repository. Perhaps you just made it. Mine is called "demo". Inside, there is a .git folder. Cool.

Let's add a worktree with git worktree add ../circuitpy. Now there is a new folder inside the .git directory called worktrees containing a new folder named circuitpy containing git metadata.

./.git:
config  description  HEAD  hooks/  info/  objects/  refs/  worktrees/
./.git/worktrees:
circuitpy/
./.git/worktrees/circuitpy:
commondir  gitdir  HEAD  index  refs/

There is also a folder next to "demo" called "circuitpy", containing a .git file pointing to the circuitpy metadata. Here's what's in mine:

gitdir: /home/marshal/Documents/circuitpy-sensor/.git/worktrees/circuitpy

This .git file is what we need to copy to the CIRCUITPY drive.

(Files starting with a dot are hidden by default, but you can see them by enabling "show hidden files" in your file browser.)

The gitignore

Now in the CIRCUITPY drive, make a .gitignore. This is a good defaut:

boot_out.txt
.*
lib/
sd/
settings.toml

I excluded settings.toml because it usually contains secrets like your WiFi password. If you need something to start with, you can always put some defaults in settings.toml.example and copy it to settings.toml when you program a new device.

Updating from a git repo

Say you have newer commits in your repository and want to update your device?

• To fast-forward your branch, use git rebase
• To see local changes, use git status
• To discard all local changes use git checkout .
• To update only some files use git reset or git checkout. This gets confusing quickly so be careful.

What about git worktree repair?

Repairing the worktree isn't strictly necessary - the .git file in CIRCUITPY points to a valid worktree, and that's enough for commits to work. But if you do, make sure to first delete the worktree you copied from, or git will get confused and duplicate the worktree.