, I started writing an ebook for my “Take on Development”. It sits fallow.
One chapter that I continue to think about is the Modes of Development; in particular the section “Modes that I can think of”.
As I was preparing for the day’s work, I recognized a new mode of thinking. It’s the mode of work that comes before Writing a Commit Message. But before I dive into that, let’s first look at Writing a Commit Message.
Writing a Commit Message
- Goal
- To create a helpful message to future developers
- Method
- Follow a well established pattern for commit messages; 50 character first line, references to issue tracker incidences, meaningful message body if the concept is complicated. Unless self evident, the message should describe the state prior to the commit, then after the commit, and provide insight into why you made the change.
- Caveat
- If I am working on a feature that will require multiple commits, I will make "disposable commits" along the way. These commits are mental placeholders. I will revisit them as I prepare a branch for merging.
At this point in my workflow, I’m explaining what I’m sending forward into the future. Yet there’s an assumption and a mode I haven’t identified. And it maps to an extent Git 📖 commands: git add. The git add command is how you stage your changes, the changes that you’ll describe with your commit message.
In the years since writing the chapter, I’ve adopted a new approach. One that’s powered by Magit. But first let’s talk about the new Modes of Development:
Staging the Commit
- Goal
- To ensure that I’m sending forward the “right” stuff.
- Method
- Using the equivalent of
git add --interactive(see Interactive Staging), I review the chunks of change (e.g. eachdiffsection).
During this mode, I’m reviewing what has changed and explicitly accepting, reverting, or skipping the possible changes. I’m switching from writing’s author to it’s editor.
While writing the commit message, I’m moving from to publisher; writing the press release and headline.
As eager as I am to just publish this change, slowing down and following these steps provides opportunities for improved understanding.
I’ve caught bugs in the editing and publishing stages, because I’ve stopped coding. While staging the commit, I’m reflecting on the specific code I’ve written. And while writing the commit message, I’ve reflected not on the specific code, but the changing state of the code.
Put another way, this is about the process of synthesis; of reflecting on the written code and writing about what’s changed and why.
Using Tools for Interactive Staging
When I first started using Git, when I was preparing to write a commit, I’d run git status. This command would show me the files I was changing. I’d then run git add my/filename to add one file.
In interactive staging, you’re instead reviewing and operating on the chunks of changes grouped by file. As I mentioned before, I use Magit for this work.
First and foremost, I devote my full attention to this; it’s the only window I have open. And the only thing in that window is the list of untracked and unstaged changes (e.g. the default Magit dispatch buffer).
Why is this important? Focus. I’m no longer writing. I’m reviewing changes. I’m in a different frame of mind; one that deserves focus.
I don’t want the rest of my editing ecosystem—such as minimaps, terminal sessions, project navigation trees, and other tabs with code in them—cluttering my current task.
Next, I begin reviewing the diff of the changed files. Within Magit I can stage, skip, or even revert each chunk. I can also highlight lines within a diff to just stage or revert those lines. Surgical precision! As I complete my actions on one region, Magit advances me to the next.
Sometimes, I’ll do all of this rather quickly; if I haven’t had any disruptions from when I first started writing the code. Responding to Slack, jumping to another project, stepping away for the evening all can count as distractions. When that is done, I begin shifting modes. Now I’m ready to begin Writing a Commit Message. For this I also use Emacs 📖; if I’m going to write something, I want to do it in my text editor!
Commit Hygiene Admonition
Use a proper editor for writing your commit message. The git commit -m "Fixing broken template" is thumbing your nose at future maintainers. If this is an important change, take time to describe and summarize it. The summary is the commit’s title (e.g. the first line). The body is the lines that come after.
I’ve wrote more about this in Commit Messages Do Matter and Leveraging Commit Messages as Pull Request Text. Too Long; Didn't Read (TL;DR 📖) All of the major remote Git services will use your commit’s title as the title of the Pull Request (PR 📖) and the body of the PR as the text of the pull request.
And to follow the principles of Publish (on your) Own Site, Syndicate Elsewhere (POSSE 📖) and Don't Repeat Yourself (DRY 📖), write those messages to the Git repository. Let them travel with you and future code maintainers.
I cannot emphasize the above enough.
But to add some additional context consider the following: Have you ever wanted to get better at using your text editor or Integrated Development Environment (IDE 📖)?
If the answer is yes, then one way to do that is to use it. And if you’re not using it to write commit messages, this is a golden opportunity to add another place of practice.
Take the time to do this. Think of your text editor as a mental muscle that you exercise and strengthen and keep flexible.
For myself, I’m always hungry to move new processes and approaches into Emacs; because I have seen the dividends in the output and I assume quality of my writing. I mention this in passing in Wrapping up Another Year for Take on Rules. Here are some posts that touch on my thoughts regarding my text editor:
Conclusion
Modernity fills life with distractions; ever hungry for our attention. Consider the state of mind your work requires and establish procedures rituals to get you there.
Want to see how I do the interatcive staging? Contact me and I could do a screen share and walk through this. I’d probably consider recording that session so we could share it out further.
And while I favor Emacs, I know that this approach is most certainly available in your editor of choice. Go forth and practice.