Back to Blog
gitcommit messagesbuild in publicdeveloper marketing

Commit Messages as Marketing: Write Commits That Double as Drafts

The commit message you write at 11:47 PM is a marketing draft if you write it right. The conventions, the patterns, and the small habits that turn git history into a content pipeline.

··6 min read

Commit Messages as Marketing: Write Commits That Double as Drafts

TL;DR

  • A well-written commit message is 70% of the marketing draft. The reframe to a post is fast; the source quality is what determines whether the reframe is worth doing.
  • The three habits: user-visible framing in the message, the "why" in the body, and conventional commit prefixes (feat:, fix:) that downstream tooling can filter on.
  • This is true even if you do not use a commit-to-content tool — your future self reading git log next month thanks you.

The commit messages most developers write are good enough for code review and useless for marketing. The commit messages that double as marketing drafts take ~5 extra seconds per commit and produce content engine input that is otherwise lost. This cluster sits inside our GitHub-to-content pillar and operationally pairs with turn GitHub commits into tweets.

Why most commit messages are bad for marketing

The default developer commit message captures what changed in the code. The marketing-grade commit message captures what changed for the user. Compare:

  • Bad: refactor: extract auth middleware into separate module
  • Better: refactor(auth): extract middleware so we can swap supabase for clerk in one place
  • Best: feat(auth): split auth middleware so we can switch identity providers without rewriting the rest of the stack

The "best" version costs an extra 10 seconds to write and contains:

  • The user-visible (or at least developer-experience) outcome
  • The why (so we can switch providers)
  • The benefit framing that translates directly to a post

Most developers default to the "bad" version because the code-review reader does not need the context — they can read the diff. The marketing reader cannot read the diff. The marketing reader needs the why captured in the message itself.

The three habits

Habit 1 — User-visible framing in the subject line

The subject line (first line of the commit) should be readable by someone who has never seen the code. The test: if you read just the subject line to a non-technical co-founder, would they understand what changed for the user?

Examples:

  • feat(billing): add one-click refunds in the dashboard — non-technical co-founder understands
  • feat(stripe): handle webhook idempotency for refund.created events — they do not

If user-visibility is hard to express in the subject, that is often a signal that the commit is internal noise and should not be content anyway. The filter does double duty.

Habit 2 — The "why" in the body

For commits that justify a body (anything more than a one-line trivial fix), write 2-3 sentences in the body explaining why this change was necessary. Not the implementation — the trigger.

Template:

feat(billing): add one-click refunds in the dashboard

A user got charged twice last week because of a Stripe webhook race
condition. The retry handler now dedupes on event ID, and the dashboard
exposes a one-click refund so we can fix issues like this without
opening Stripe directly.

Tested against the duplicate-charge scenario from the original report.

The body is the source material for the post. The post draft writes itself from the body.

Habit 3 — Conventional commit prefixes

Use the Conventional Commits convention (feat:, fix:, refactor:, chore:, docs:, style:, test:). The reason: it lets downstream tooling filter commits programmatically. Dev Cards uses these prefixes as the first-pass signal-to-noise filter:

  • feat: and fix: → likely content, surface as draft
  • refactor:, chore:, style:, docs: → likely internal, skip

Without the prefixes the tooling has to fall back to NLP classification, which works but is noisier. The 4-character prefix is the highest-leverage developer habit for downstream content automation.

The 5-second discipline

The marginal cost of writing a marketing-grade commit message is ~5-10 seconds per commit. If you ship 10 commits per day that is 50-100 seconds per day of incremental cost. The discipline:

  • Pause before typing the subject line
  • Ask: what changed for the user?
  • Type that, not what changed in the code
  • If it justifies a body, ask: what triggered this?
  • Type that

This habit becomes automatic by week 2-3 and produces a git log that is itself a marketing artifact. Even if you never run a commit-to-content tool, your future self reading the git log in 6 months knows why every change happened. That alone often justifies the habit.

What does not work

  • Auto-generated commit messages from AI without review. AI generates messages from the diff that often miss the why. Review and edit.
  • Treating commit messages as code-review artifacts only. They are also git history, also content source, also future-self documentation. The audience is broader than the next PR reviewer.
  • Skipping the body on non-trivial commits. "The diff explains it" is true only for the moment; in three months neither the diff nor the message will be self-explanatory without the body.
  • Inconsistent prefix usage. Either commit to Conventional Commits or do not — partial adoption defeats the tooling benefits.

How this connects to the larger pipeline

The commit messages feed into:

  1. Dev Cards — uses prefixes for first-pass filter, body content for context
  2. Loudy — drafts the post using the commit body as the why-it-matters context
  3. Public changelogs — auto-generated from feat: and fix: commits, the commit body becomes the changelog entry
  4. Year-end retros — git log filtered by feat: becomes the "things we shipped" timeline

A well-written commit message produces value at all four layers without any additional manual work.

Sibling clusters

FAQ

Should I retroactively rewrite my old commit messages? No. The cost of rewriting git history is high and the benefit is low — the content engine cares about new commits going forward. Start the new habit from your next commit; leave the old ones alone.

Does this work for AI-generated commit messages from Claude Code? Yes, when you review and edit the AI output. Claude Code's commit messages are typically structurally correct (good prefix, accurate subject) but often miss the why because the agent does not always know the user-visible reason for a change. A 10-second edit before the commit lands captures the why.

What if my team has different commit conventions? Honor the team convention. The content engine can be configured to read whatever prefixes your team uses — the value is consistency, not specifically Conventional Commits. The win is that the convention exists and is followed; the specific format matters less.

How long does the discipline take to become automatic? ~2 weeks of deliberate practice. The first few days feel slow because you are pausing before each commit; by week 2 the pause is internalized and the cost approaches zero. The discipline survives long-term because every time you read your own git log a month later, you experience the benefit directly.

Will this slow down my shipping velocity? No measurably. The 5-10 seconds per commit aggregates to ~1-2 minutes per day. The compounding benefit (downstream content automation, future-self documentation, changelog generation) is orders of magnitude higher. Most founders report shipping velocity increases because the cleaner commit messages also make code review and rollback faster.

Building is no longer the bottleneck. Visibility is. buildinpublic.so is narrative infrastructure that runs inside your building workflow — Dev Cards uses your commit messages as the source signal, Loudy drafts the post from the commit body, and the 5-second discipline of writing user-visible commit subjects compounds into a content pipeline.