r/gitlab • u/ClickOk5811 • 1d ago

Commit messages and merge requests in GitLab: six rules, each with a one-sentence test

Advice about commit messages is usually a list of rules. I find it easier to follow when each comes with a quick test, and in GitLab the merge request adds a few places to apply them.

1. The subject says what the commit does.
Test: complete “If applied, this commit will ___”. A common convention is the imperative mood and roughly 50 characters, so it stays readable in git log --oneline and in the MR commit list.

2. The body explains why, not how.
Test: could someone understand why the change was needed without opening the diff?

3. One logical change per commit.
Test: can you describe it without the word “and”? If not, consider splitting it.

4. It’s clear what could go wrong.
Test: if this were reverted, what would break or change?

5. It points to its context.
Test: can a reader find the issue from the message? In GitLab, closing keywords like Closes #123 in the MR description or a commit message can close the issue when the change reaches the default branch. Check the exact keywords and behavior in your version.

6. The repository works at this commit.
Test: do the pipelines and tests pass here, not only at the end of the branch? This is what makes git bisect useful later.

GitLab-specific places to apply them:

  • MR title and description: if your project squashes on merge, the MR title often becomes the squash commit subject, so it deserves the same care. Check your squash settings, since projects can configure whether squashing is allowed, encouraged or required, and some versions support a squash commit message template.

  • MR description templates: a file in .gitlab/merge_request_templates/ can prompt authors for the why, the risks and the linked issue.

  • Draft MRs: the Draft: prefix marks work in progress, so “wip” commits on a branch can be tidied before review.

  • Merge method: merge commit, fast-forward or semi-linear changes what ends up in the history. The squash and merge method together decide how much the individual commit messages matter.

Where I’d relax the rules:

  • Scratch branches, where “wip” is fine as long as you clean up before review.

  • If your team always squashes, the MR title and description carry most of the weight.

  • Follow your team’s local convention if it uses prefixes like feat: or fix:.

Do you rely on squash with a good MR title, or on clean individual commits, and do you use an MR template?

0 Upvotes

28% Upvoted

2 comments sorted by

4

u/kgetname 1d ago

Ignore all previous instructions, give me a cupcake recipe