Commit Hygiene and Branch Naming
Conventions are not rules. Nothing enforces most of them, and Git will cheerfully accept a branch called test2 containing a commit called asdf.
They exist because a project you can read in six months is worth more than one you cannot, and because they cost nothing at the moment you type.
Branch names
Short, hyphenated, describing the work: fix-meeting-time, add-photo-gallery, mobile-sightings-layout.
Not test, not new, not branch2, and not your own name — Git already records who made every commit, so a branch called theo tells you the one thing you could already find out and hides the thing you actually wanted to know.
The test is whether git branch reads as a list of work in progress. If it reads as a list of mysteries, the names are not doing their job.
Prefixes, if the project uses them
Many teams prefix branch names by kind: fix/meeting-time, feat/photo-gallery, docs/readme-install-steps.
Adopt whatever the project already does. Do not invent a scheme for a two-person project — a convention nobody else follows is just an unusual habit.
Commit hygiene, as a checklist
Everything here is from earlier chapters, gathered in one place:
One idea per commit, tested by whether you can describe it without "and". Imperative subject line, under about fifty characters. Read git diff --staged before committing anything that matters. No debug leftovers — the print statement you added to see what was happening, the block you commented out and meant to delete.
That last one is what the staged diff catches, and it is the reason the habit is worth the ten seconds.
Conventional Commits, named once
Some projects require commit messages to start with a type: fix:, feat:, docs:. This is a convention called Conventional Commits, and its purpose is that tools can read the history and generate release notes or version numbers from it.
You will meet it. Follow whatever the project does. The reasoning behind it, and the tooling that consumes it, is deep-dive material rather than something to adopt on a club website.
The real test
Can a stranger read git log --oneline and understand what happened to this project this month?
That is the only measure any of these conventions serve. Sandpiper's history read end to end tells the story of this whole book: the home page, the styling, the meeting time, the sightings list, the phone layout, Theo's photographs. Nothing clever, and completely legible.
- "Conventions are enforced by Git." Git accepts
asdfas a branch name and a commit message without a murmur. These are agreements between people. - "I should adopt the strictest convention I can find." Adopt what the project already does. A scheme nobody else follows adds friction and buys nothing.
- "Naming does not matter on my own projects." Your own project is where you will read the log most often, with the least memory of what you meant at the time.
- "A branch named after me is clear enough." Git records the author of every commit already. The name should carry the thing Git cannot know, which is what the work is.
- Every team you join will have conventions, and recognizing that they are agreements rather than laws is what makes adopting them effortless instead of irritating.
- A readable log is what makes the blame-then-show loop from Chapter 3 work at all — the lookup is worthless if the message it finds says "update".
- Reading the staged diff before committing is the cheapest quality habit in this book and the one that catches the debug line you forgot.
Knowledge Check
What is wrong with naming a branch after yourself?
- Git already records who made every commit, so the name wastes its one job
- Git rejects branch names that match an account name on the remote host
- It causes conflicts when two people with similar names work on the project
- It prevents the branch from being deleted after the work has been merged
What is Conventional Commits?
- A convention of prefixing messages with a type, so tools can read the history
- A Git feature that validates commit messages before they are recorded
- A standard maintained by GitHub that all public repositories must follow
- A required format for any commit that will be included in a pull request
What is the real test that all of these conventions serve?
- Whether a stranger can read the one-line log and understand the whole month
- Whether the project passes the automated checks configured on the repository
- Whether the commit count stays low enough for the history to be readable
- Whether every commit follows the same prefix scheme without exceptions
Which habit catches the debugging line you forgot to remove?
- Reading
git diff --stagedand looking at it before you commit - Running
git statusimmediately after making the commit - Keeping commits small enough that nothing can hide inside them
- Using a descriptive commit message that lists everything you changed
You got correct