Most engineering teams treat merge commits as an afterthought, letting Git generate generic messages like Merge pull request #123 that provide zero context about what changed or why. This creates a hidden tax on your team's productivity when debugging issues, reviewing code history, or onboarding new developers who need to understand how the codebase evolved.
A well-structured merge commit message transforms your Git history from a cryptic ledger into searchable project documentation. This guide covers how to write useful merge commit messages, configure templates and enforcement across your team, handle merge conflicts properly, and avoid common pitfalls like evil merges that break Git's debugging tools.
A useful merge commit message provides context, rationale, and traceability for a set of changes, typically by summarizing the pull request's purpose and including its number. This clarity is crucial because a well-maintained Git history acts as a project's living documentation, making it faster to debug issues, understand past decisions, and onboard new team members. Without conventions, your git log can become a cryptic record of automated messages that hide more than they reveal.
What makes a merge commit message useful for the whole team?
An unreadable Git history is a hidden tax on your engineering team. During an incident, engineers waste precious time deciphering vague commit messages like Merge branch 'main' into feature/user-auth instead of quickly identifying the source of a bug. A useful merge commit message transforms the log from a simple ledger into a searchable, understandable narrative of the project's evolution.
The goal is to provide three key pieces of information at a glance:
Context: What feature or fix is being integrated?
Rationale: Why was this change made?
Traceability: Where can I find the full discussion and code review? (e.g., the pull request)
A small investment in formatting pays huge dividends in clarity.
Unhelpful default | Clear convention |
|---|---|
|
|
|
|
|
|
Clear merge commits accelerate more than just debugging. They speed up code reviews by providing a concise summary of the incoming changes and help new engineers get up to speed by offering a readable history of how the codebase developed.
What should a merge commit format include?
A good merge commit format should be concise, informative, and machine-parsable. We recommend a single-line summary that captures the essence of the change and its associated pull request.
A robust pattern is: type: <PR-title> (#<PR-number>).
This format is a specialized version of the Conventional Commits specification. The type prefix (like feat, fix, or refactor) categorizes the change, which is invaluable for automating changelogs and versioning. Our automated release process relies on these structured commit messages to correctly bump versions and generate release notes for our SDKs.
Note: If you're using Stainless to automate versioning and changelog generation, these Conventional Commit–style merge messages are parsed by Stainless to determine semantic version increments and produce accurate release notes.
For more complex merges, you can add a body with more detail.
A list of files that had merge conflicts.
Links to related issues in your project tracker (e.g.,
Resolves: TICKET-456).A brief summary of the changes if the PR title isn't sufficient.
Here are a few examples for different scenarios.
Feature branch
Hotfix branch
Release branch
How to configure merge commit templates
Consistency is key, and the best way to achieve it is through automation and enforcement. You can configure templates and checks at the repository, local, and CI levels to ensure every merge commit follows your team's convention.
Most Git hosting platforms provide settings to enforce a commit message style for pull requests.
GitHub: In your repository settings under 'Pull Requests', you can select a merge commit message format. Options include using the PR title, the title and description, or a custom template.
GitLab: You can define a merge commit message template in your project's settings, using variables like
%{title}and%{source_branch}to construct the message dynamically.
For local development, you can configure Git to use a message template file.
First, create a template file, for example, .gitmessage:
Then, configure Git to use it for all commits, including merges:
Stainless-compatible commit template
If you use Stainless to automate versioning and changelog generation, you can create a template that enforces a Conventional Commit formatted merge message on every commit:
Finally, for the strongest guarantee, you can add a linting step to your CI pipeline. Tools like commitlint can be configured to check commit messages against your conventions and fail the build if they don't comply, preventing non-conforming merges entirely.
Should you document conflicts in merge commits?
Yes, but only when the resolution is non-trivial. If you just had to choose between two simple, conflicting lines, the default merge commit is usually enough. However, if resolving the conflict required significant logic changes, documenting your reasoning in the merge commit body can save the next developer hours of confusion.
When you resolve a merge conflict, Git automatically includes a list of the conflicting files in the commit message, commented out.
Instead of deleting these lines, uncomment them. Then, add a brief note explaining how you resolved the conflict. For a reviewer, running git show --remerge-diff <merge-commit-hash> will display the conflict resolution clearly, but this context can be lost over time. A short note in the commit body preserves that 'why' forever.
A simple template for the commit body could be:
What are evil merges and how do you avoid them?
An evil merge is a merge commit that sneakily introduces new changes that were not present in either of the parent branches. It's more than just resolving conflicts; it's adding new logic, refactoring code, or fixing a typo during the merge itself.
This practice is harmful because it breaks two of Git's most powerful debugging tools:
git blame: It will incorrectly attribute the new changes to the person who performed the merge, not the original author.git bisect: It can point to the merge commit as the source of a bug, making it incredibly difficult to find the actual root cause among all the changes being merged.
The best way to avoid evil merges is to follow a simple rule: a merge commit should only contain the changes necessary to resolve conflicts. If you spot another issue or think of a refactor while merging, resist the urge to fix it. Instead, complete the merge, then create a new, separate commit for the additional changes. This keeps the history clean and logical.
How merge commits work in SDK repositories
In a repository for a generated SDK, the Git history is often a mix of automated commits from a code generator and manual commits from developers adding custom code or documentation. Maintaining a clean history here is especially important.
When we use the SDK generator for our customers, our automated release process creates pull requests with Conventional Commit messages. This ensures that every change, whether it's a new endpoint from an updated OpenAPI spec or a bug fix in the generator, is clearly categorized. Teams creating OpenAPI specs can rely on this categorization for accurate change tracking.
This structured history allows us to automatically generate accurate changelogs and determine the next semantic version number. When developers add their own custom code to the SDK, following the same commit conventions ensures their changes are also captured in the release notes.
The same principles apply to generated subpackages, like MCP server generation from OpenAPI specs. By enforcing consistent merge commit naming across the entire repository, the history remains coherent, even with multiple sources of change.
Frequently asked questions about merge commit conventions
How do I enforce merge commit conventions across my team?
You can use a combination of repository settings on GitHub or GitLab to set default merge message formats, local Git hooks to check messages before committing, and CI pipeline steps with tools like commitlint to block non-conforming PRs.
Can I fix a merge commit message after merging?
If the merge has not been pushed to a shared remote, you can amend it locally with git commit --amend. If it has been pushed, rewriting public history is dangerous; it's often better to leave it and enforce the convention going forward.
Should squash merges use the same format?
Yes, and it's even more critical. Since a squash merge condenses all of a feature branch's commits into a single commit on the main branch, that one commit message is the only record of the change, so it must be clear and descriptive.
How do these conventions fit different Git workflows?
These conventions are workflow-agnostic but provide the most value in PR-based workflows like GitHub Flow or Git Flow, where the merge commit represents the integration of a reviewed body of work.
Can AI tools help write merge commit messages?
Yes, AI tools can help. GitHub Copilot can generate summaries for pull requests, which serve as a great starting point for a merge commit message. As AI agents become more integrated into development, we may see MCP-powered tools that can analyze a diff and suggest a perfect, conventional commit message automatically. The lessons learned from converting complex OpenAPI specs to MCP servers show how these tools can handle sophisticated API structures.
Ready to automate your SDK generation with clean, conventional versioning built-in? Get started for free.