Good git commits

Good commits aren't a moral exercise. They're a tool that makes your project easier to read, easier to revisit weeks from now, and easier to show off when someone asks "how did you build this?"

Stardance reviewers and voters do look at your repo. A clean commit history is one of the cheapest signals you can send that you take your work seriously.

The two rules that matter

1. One commit, one change

Each commit should do one thing — add a feature, fix a bug, refactor a file, update a dep. If you can't summarize a commit in a sentence without using "and," it's probably two commits.

Why this matters: when something breaks, you can revert the one commit that broke it instead of unwinding a bunch of unrelated changes. When you're showing your project to a friend (or a future employer), they can scroll through and see what you actually did.

2. Write the message for the next person

The "next person" is usually you, six weeks from now, with no memory of what you were doing. Make their life easier.

A solid format:

verb subject

(optional) why this change exists,
not what the diff already shows.

Real examples:

add login throttling to prevent brute-force attempts

fix off-by-one in pagination — last page was empty

refactor: pull tag-resolution out of search controller

Versus messages that don't help:

changes
update
fix bug
asdf
final final v2

Conventional commits (optional)

Some projects use a stricter format that prefixes commits with a type:

feat: add login throttling
fix: pagination off-by-one
refactor: extract tag resolution
docs: explain the auth flow
chore: bump dependencies

This is great for projects that auto-generate changelogs or version numbers. For most Stardance projects it's overkill, but it's a nice habit. If you're on a team or want to look polished, use it.

How often to commit

Whenever you finish a coherent thing. Not "every five minutes" and not "once at the end of the week."

Heuristic: if you'd hate to lose what you just did, commit it. If you broke something for an hour while wiring up a new feature, that's one commit when it works — not twelve micro-commits documenting the broken intermediate states.

The "WIP" trap

Lots of people commit WIP messages while iterating, planning to clean up later. They never clean up later. The commits stay forever.

Two ways out:

• Commit often, then squash before pushing. git rebase -i lets you collapse a series of WIP commits into a single clean one with a real message.
• Just write a real message the first time. Honestly easier than rebasing later.

What goes in the body

Most commits don't need a body — the subject line is enough. But for non-obvious changes, the body is where you tell the story:

• Why you made the change (the diff already shows the what).
• What you considered and rejected.
• Anything weird about the implementation a reader should know.
• Issue or ticket numbers if you're tracking work somewhere.

Mistakes you'll only make once

• Committing node_modules or build artifacts. Use a .gitignore. Most generators include one — start from a template.
• Committing API keys or .env files. Always gitignore .env. If you slip, rotate the key immediately — git history is forever, even after a force-push.
• Force-pushing a branch other people are using. If you're working alone this doesn't matter. If you're not, it does.
• Letting your branch drift weeks behind main. Rebase often, or merge often. Either is fine. Doing neither is painful.

One small bonus

If you set up your editor to show commit messages alongside lines (most do via "git blame"), you'll get a free reminder of why each piece of your project exists. That's the payoff: a few seconds of effort per commit, and your codebase tells you its own story.