How to Write Clear Git Commit Messages for Capstone and Team Projects

A good commit message is a short note to your future self and to anyone who reviews your work. In a capstone or group project it also becomes the history of how the system grew: why the login page changed, when the appointment status was added, and which teammate fixed the double-booking bug. Vague messages like update, fix or asdf waste that history.

This post is a practical guide to writing clear Git commit messages for student teams. No fancy hooks or commit templates are required — just habits you can start using on the next push.

What a Useful Commit Message Looks Like

Think of the first line as a newspaper headline for the change. Keep it short (about 50–72 characters), write it in the imperative mood ("Add", "Fix", "Rename"), and say what changed from the reader's point of view:

Add double-booking check on appointment save

Reject a new appointment when the same doctor already has
a Scheduled booking at that date and time. Cancelled and
No-Show rows are ignored so the slot can be reused.

The optional body (separated by a blank line) explains why, not a line-by-line list of the diff. Git already shows the diff; the message should capture the reason.

A Simple Pattern: type + short summary

Many teams prefix the subject with a short type. You do not need a formal Conventional Commits setup for a school project — a small shared list is enough:

• feat: a new user-facing feature (feat: add patient search by phone)
• fix: a bug fix (fix: stop crash when birthdate is empty)
• docs: README or comments only
• style: formatting, no behavior change
• refactor: same behavior, cleaner structure
• chore: tooling, zip packaging, dependency bumps

If your group already uses ticket IDs, put them at the end or in the body: fix: correct overdue count on dashboard (CAPS-42).

Examples: Weak vs Clear

Habits That Help Capstone Teams

1. One idea per commit. Mixing "add doctors CRUD" with "change button color" makes reviews and rollbacks harder. If you did two unrelated things, make two commits (or git add -p to stage only part of the work).
2. Commit before you switch tasks. When your partner needs the login page and you are mid-feature, commit (or stash) so the branch stays understandable.
3. Write the message after you review the diff. Run git diff --staged, then write the subject. You will notice leftover debug prints before they land in the shared branch.
4. Prefer small, frequent commits over one giant "submit today" dump. Defense panels and future maintainers can follow the story; bisecting a bug also becomes possible.
5. Agree on English (or one language) for subjects. Mixing Taglish slang in subjects and formal English in the README confuses everyone during merge reviews.

A Short Team Checklist

Paste this into your group chat or README:

[ ] Subject is imperative and specific (Add / Fix / Rename…)
[ ] Subject is under ~72 characters
[ ] Body explains why if the change is non-obvious
[ ] Commit contains one logical change
[ ] No passwords, API keys or personal data in the diff
[ ] README updated when setup steps changed

What About Merge Commits and "Update README"?

Default merge messages like Merge branch 'feature/login' into main are fine — Git writes those. For README-only updates, still say what you changed: docs: document default admin login is more useful than update readme six times in a row.

If you amended or rebased already-pushed commits on a shared branch, coordinate with the team first. Rewriting history without warning is how classmates lose hours of work.

Conclusion

Clear commit messages cost a minute and save everyone time later — during code review, during your capstone defense, and when you reopen the project months after graduation. Start with a short type, a specific subject, and one idea per commit. Your repository will read like a story instead of a pile of "updates".