There are many ways to use git, none of them more or less technically correct than the other. Except for mine, obviously. I’m the only person who uses git correctly. Read on, that you may be enlightened:
In commit titles, I write a short title in the imperative mood. In commit message bodies, I describe the enclosed change as if I were writing an email. I attach relevant trailers including a developer certificate of origin at the bottom. For example:
drm/panel: novatek-nt35560: Fix invalid return value
Fix bug in nt35560_set_brightness() which causes the function to
erroneously report an error. mipi_dsi_dcs_write() returns either a
negative value when an error occurred or a positive number of bytes
written when no error occurred. The buggy code reports an error under
either condition.
Fixes: 8152c2bfd780 ("drm/panel: Add driver for Sony ACX424AKP panel")
Signed-off-by: Brigham Campbell <me@brighamcampbell.com>
I use git’s rebase and amend operations to iterate on the history. I rewrite history regularly until the moment my commits enter the history of a shared git branch. When merging my changes, I do not squash commits.
Why do I go through the trouble of meticulously developing the git history? I care about the history. I want to know that years after I’ve made a change, another developer can use the git pickaxe, log, and blame to understand why I made it, what it does, and how it fits into the larger history of the repository. A literate, intentional git history is an investment which can pay dividends.
What Dividends?
A couple months ago, I was working on an embedded Linux device with a small RGB565 TFT display. The team had written a custom kernel driver to allow the kernel to push pixels to the display. I was tasked with updating it to a more recent release of Yocto.
After I determined that our custom driver would require updates due to changes
in the upstream kernel graphics subsystem API, I began investigating the
kernel’s hardware support. I identified the upstream panel-mipi-dbi driver as
an alternative to our own custom driver. Switching to the upstream driver would
relieve us of the need to maintain our own driver.
After making the necessary changes to use the upstream driver, the display showed a garbled framebuffer. At the time, I wasn’t quite as familiar with git. For a while I had wondered if it was a bug in our own code. The answer was in the git history of the Linux kernel:
$ git log --oneline --grep Fixes drivers/gpu/drm/tiny/panel-mipi-dbi.c
9c1798259b94 drm/tiny: panel-mipi-dbi: Use drm_client_setup_with_fourcc()
Since the kernel version shipped with our Yocto release, there had been one bug
fixed in the panel-mipi-dbi driver. It was the same bug I had been
experiencing. To be sure, the informative commit message described the exact
symptoms I observed:
RGB565 displays such as the CFAF240320X no longer
render correctly: colors are distorted and the content is shown twice
horizontally.
After backporting 9c1798259b94 into our Yocto build, the issue was resolved.
This was only possible because the commit’s author described the fix to the
driver well. In the commit message, they included a Fixes: trailer and a
plain English description of the problem the commit solved.
But I Don’t Need History
I hear you: “My code is not nearly as complicated as the Linux kernel. I never read the git history because I don’t need to. Why would I spend so much time and effort caring about something that nobody looks at?”
Maybe you never look at the history because there’s little to be found there. Most git repositories are stuck in a negative feedback loop:
Nobody reads the history
| ^
because... because...
V |
Nobody writes intentional commits
You can’t see a return on your investment into a more intentional git history until after you have invested.
Naturally, I don’t think everyone should adopt the git rebase workflow specifically. I personally find it easier to develop a more meaningful history by iterating on it with git rebase. The fact is, there are plenty of reasonable ways to collaborate with git. I do think, however, that the history we author often deserves more attention than it gets.