Pull up git log --oneline on a project—or open the Magit log with l l from the status buffer and you might see two slightly different stories.
Either you’ll see this:
f31e4a2 WIP c8b29f1 some minor edits 9aa55d3 chugging through 8f72cc0 some tweaks 3d19c44 some more tweaking
Or you’ll see something like this:
f31e4a2 Finished the confrontation scene w/ Megan c8b29f1 Fleshed out Ethan's backstory in chapter two 9aa55d3 Bar fight scene, in 8f72cc0 Further developed Ethan's voice 3d19c44 Initial commit, project structure and outline
Both sets of commits represent the same amount of work. The only difference is the two minutes it took to write a real commit message instead of a placeholder.
There’s been a lot of discussion in recent years about what to name your branches, which can be anything you want. However, has anyone taken a hard look at some of the hard-coded git terminology, like the word “commit”? In my Git For Writers handbook, I compared commits to “save states” or “snapshots.” I’d always felt the word “commit” sounded too permanent and fixed, but that’s not the case at all.
The word commit has a richer meaning than at first appears. Derived from a Latin root meaning to entrust, it’s the same as committing something to memory, or entering a transaction into a ledger, more like a notation than a final verdict. That’s exactly what you’re doing when you commit your work in git: entrusting a session or chunk of work to the record. Nothing is declared finished or locked in, but you are merely saying: this is what I did today or this is where I was when I stopped today.
Your commit history is a manuscript about your manuscript
Every commit is like a moment in the life of your project. When you string those moments together with clear, meaningful messages, something useful emerges. You can look back and see not just what you wrote, but how you wrote it.
Think of all the information you might glean from a well-documented commit log.
- When did the project pick up speed?
- Was there a lull, and at what point?
- What have you been battling with recently?
- What are you avoiding?
- Which sections were more difficult?
- Was there a lot backtracking?
- When did the current change direction?
The journey is not visible in the finished project itself, which is fine; the reader need not know how you got there. But as the writer, you ought to know how it happened.
What a well-told commit history looks like
Here is an example commit log for a short story project, read from oldest to newest.
a1f3309 Initial commit, project structure and notes b22e117 Opened the story, established the narrator's tone cc49852 Drafted the first scene, setting and introduction d78f441 Pushed through the second scene, conflict introduced e830192 A turn, starting to click f91b004 Rough draft complete g04a215 First revision pass, tightened the opening h17d331 Cut the second paragraph of scene one entirely i2a8c62 Addressed group critique notes, softened the ending j30f577 Final proofread pass k498d00 Submitted to Mudflap Review
You may also consider tagging the final commit with something like “first_submission,” or “version1.”
Reading that log tells you the story about the story. You can see where you found the piece (“starting to click”). You can see the revision arc. You can see when external feedback came in and what changed. You even notated when it was submitted, which might be unnecessary, but that would depend on your chosen level of depth.
The commit message is a creative act itself
The moment right after a writing session is a great time to consider what you accomplished. The session is fresh in your mind. You know exactly what happened. And if you’re unsure, you can look at the unstaged changes.
Something I really like about Magit is how can easily split and stage individual hunks. This can help you group changes, or exclude certain edits, under one specific commit.
Instead of typing “did some stuff” and moving on, take a few seconds and answer the question: what actually happened in this session?
You may consider:
- Did you finally solve a problem that had been blocking you?
- Did you write a scene you’re genuinely proud of?
- Did you make an ugly but necessary structural cut?
- Did you break through and hit a flow state you hadn’t felt in weeks?
Create a decent commit message about it.
Here are some examples:
- Solved the third-act problem, moved the confrontation earlier
- Cut 800 words from chapter four, much tighter now
- Rewrote the opening line, finally have something I like
For years, I wrote pretty limp commit messages, like “Some minor editing” and “more minor editing,” etc. Looking back, this tells you almost nothing about your process. You’d have to look at individual diffs to actually see what happened.
A good commit message costs almost nothing to write but can really help elucidate the dizzying twists and turns of a long writing project, and can also help keep you on track when you get lost in the weeds.
Commit data tells a second story
Beyond the messages, the data inside each commit tells you something about what kind of work you were doing.
Run this command to see the number of lines changed in each commit:
git log --oneline --stat
See where your patterns lie.
In the early drafting phase, you may see more insertions. In the revision phase, you may see the ratio shift as more deletions appear.
If you’re seeing a revision pattern when you should be in full drafting mode, that’s useful data. It might mean you’re editing too early, or that’s just your style and not a big deal. The numbers and graphs can help make your otherwise invisible habits visible.
A few principles for writing good commit messages
Commit at natural stopping points. Every paragraph is perhaps too frequently. But once a week is perhaps too much. Commit when you feel good about what you did on a section or specific area. Think about that metaphor of entering a record into the ledger.
In a previous post on this topic, I suggested that doing a commit every 250 words changed was a pretty good metric. This is highly subjective. If your case, it might be closer to 500 or 1000 words changed. But I’d say 250 is still a good low end. You probably wouldn’t want to commit to fewer words, unless perhaps you solved a critical problem or hit a milestone and want to note that in the history. It’s up to you.
Use the word-diff for a review of what you just did. This is one of the most valuable git master-level techniques I’ve employed over the years. Before committing, take a moment to review your changes at the word level—what you deleted and what you added:
git diff --word-diff HEAD~1
In Magit, press d r from the status buffer. Magit’s diff view highlights added and removed words, which gives you the same at-a-glance picture of what changed.
With this information, you can write a stellar commit message.
Write the message now, don’t wait.
Be honest in the message. If the session was hard, say so. If you had the best session in months, notate that. Your future self will appreciate it.
Use notes if you need more details. Commit messages are best kept to one line, but notes can give you more space to ramble on.
Use tags for major milestones. A commit message records the daily work. A tag records the landmark.
git tag -a rough_draft -m "Rough draft finished, 62,000 words"
When you look back on the project, tags let you jump directly to the moments that mattered most.
Basically, let your commits tell the story. I think you’ll get a lot of value out of this.
If you have any comments or questions about this workflow, or if you have some similar strategies, be sure to leave me a comment below.
Leave a Reply