Commit Bodies That Explain Why

Writing commit bodies that explain why a change was made is a fundamental habit for maintainable software. Most developers focus on the subject line, which usually answers what happened. However, the commit body is the only place where the context of a decision lives forever alongside the code. When a colleague or your future self runs a git blame two years from now, a subject like "update auth logic" provides little value. The body should explain the trade-offs, the bug reproduction steps, or the reason why a specific library was avoided.

The Anatomy of a High Quality Commit

A perfect commit follows a specific structure that separates the summary from the detailed explanation. This structure is often called the Conventional Commits specification, but even without strict tooling, the logic remains the same.

1. The Subject: A concise summary of the change in 50 characters or less.
2. The Blank Line: Essential for git tools to distinguish the title from the body.
3. The Body: A detailed explanation of the intent. This is where you justify the change.

Why the Why Matters

Code explains how a feature works. If you need to know how the logic flows, you read the source. The commit message serves a different purpose. It explains the "why" behind the implementation. Perhaps there was a specific edge case in a third party API that forced a non-intuitive work-around. Perhaps a more elegant solution was skipped because it caused a memory leak in a specific environment. Documenting these decisions prevents future developers from undoing your work in an attempt to "clean up" the code.

Challenges in Writing Detailed Commits

Maintaining high standards for commit bodies is difficult in fast-paced environments. Developers often face several friction points:

• Context switching: Writing a detailed essay after a long debugging session feels like an interruption.
• Memory fade: If you wait until the end of the day to commit, you might forget the specific reasons for a small change.
• Terminal limitations: Writing multi-line messages in a basic terminal editor like Nano or Vim can be cumbersome for those who prefer graphical interfaces.

Standard git workflows often lead to "fix" or "wip" messages. To fix this, teams can use git hooks to enforce length, or they can leverage AI agents to draft the initial explanation based on the staged changes.

Leveraging AI Agents for Commit Messages

Modern development environments now include AI agents that can read your diffs and suggest commit bodies that explain why things changed. These agents, such as Claude Code or OpenCode, analyze the logic flow and identify the intent.

When using an agent, the workflow changes. Instead of typing a quick message, you ask the agent to review your staged changes. The agent looks at the added and removed lines, considers the context of the files, and proposes a message. You should always review these suggestions to ensure they accurately reflect your intent.

How Different Tools Handle Git Context

Different tools take various approaches to assisting with git history.

Agents are particularly good at connecting dots between multiple files. While a human might describe the change in one file, an agent can explain how the change in auth.ts correlates with the update in session.sql.

Implementing This in Your Workspace

If you use Deska, you can integrate this process into your daily flow without leaving your environment. Deska is a local-first desktop application that provides an infinite canvas for your development tools. Within this canvas, you can run multiple coding agents as panels side by side.

You can have a terminal open to run your tests, a code editor to make changes, and an agent like Claude Code or Codex CLI in a neighboring panel. Once your tests pass, you can ask the agent to "write a commit message for my staged changes." Because Deska allows these tools to run in a unified workspace, the agent has the necessary context to see what you have been working on.

If you are away from your desk, you can even use the Deska mobile app to check the status of your tasks through the secure relay. This allows you to monitor long-running agent processes that might be refactoring code and preparing those detailed commit bodies.

Best Practices for Agent Assisted Commits

To get the most out of an agent when generating commit bodies that explain why, follow these steps:

• Stage your changes incrementally. Small, atomic commits are easier for both humans and AI to describe accurately.
• Provide a hint to the agent. If there is a non-obvious reason for a change, mention it in the chat before asking for the commit message.
• Use the Ask Deska assistant to manage your panels. You can say "open a terminal and show git status" to see your current state before involving an agent.
• Keep your API keys managed or provide your own to ensure the agent has the capacity for long-form reasoning.

Common Pitfalls to Avoid

Even with AI assistance, certain habits can degrade the quality of your git history.

• Avoid repeating the code. If the code says x = 5, the commit body should not say "set x to 5." It should say "increase the timeout to 5 seconds to reduce connection drops on slow networks."
• Do not let the agent hallucinate reasons. If the agent suggests a reason you did not intend, edit it immediately.
• Never commit sensitive information. Since Deska is local-first, your code stays on your machine, but remember that commit messages are often pushed to shared repositories. Check your privacy settings and ensure your .gitignore is properly configured.

FAQ

How to write a multi line git commit message?

In the terminal, you can run git commit without the -m flag. This opens your default text editor, allowing you to write a subject, leave a blank line, and then write a detailed body. Alternatively, you can use multiple -m flags, where each one starts a new paragraph.

Can AI agents understand my project context?

Yes, agents like Claude Code or OpenCode can read your local files to understand the architecture. In Deska, these agents run as panels and have access to the files you specify, allowing them to write commit bodies that explain why a change fits into the larger system.

What is the ideal length for a commit body?

While there is no hard limit, a commit body should be as long as necessary to explain the decision. Usually, 72 characters per line is the standard for readability in terminal viewers. The goal is clarity, not brevity.

Getting Started with Deska

Improving your git history is just one part of a better developer experience. By organizing your tools on a spatial canvas, you reduce the mental overhead of window management. You can download the app for Mac, Windows, or Linux to start building your own custom workspace.

To begin, visit the download page and install the version for your operating system. Once installed, you can follow the getting started guide to set up your first workspace and connect your preferred AI agents. This setup allows you to focus on writing code while agents help maintain the documentation in your commit history.