docs: theming the gutter column background

[alberti42]

Summary

This PR adds a new section to the README, "Theming the gutter column
background", explaining how to make git-gutter's gutter column blend
visually with the line-number column used by modern Emacs themes. It
documents both the recommended approach on Emacs 31.1+ (using the new
margin face) and the fallback approach for Emacs ≤30.x.

Motivation

Many popular themes, including the built-in modus-operandi and
modus-vivendi, give the line-number column a distinct background color.
git-gutter draws its change indicators next to that column, so without
coordination the result is a visually broken gutter: diff-indicator rows
have one background, while unchanged rows bleed through to the default
frame or terminal background.

How this is fixed differs sharply by Emacs version:

• Emacs 31.1+: customize the new margin basic face
  (bug #80693).
  The display engine fills every empty margin cell with this face's
  background automatically — no git-gutter configuration needed. This is
  also cheap on large files.
• Emacs ≤30.x: the margin face does not exist, so the only way to
  fill empty cells is to force git-gutter to write something into them
  via git-gutter:unchanged-sign or git-gutter:separator-sign, then set
  the corresponding face backgrounds. This works but installs an overlay
  on every line of the buffer, which becomes prohibitive on very large
  files.

Both paths share the same root issue — the reserved-but-unwritten margin
cell — but the user-facing recommendation is different, and the older path
should now be presented as a fallback rather than the default advice.

A personal note on why this documentation matters

Tracking down the root cause took me an embarrassingly long time. The
symptom, a visually inconsistent gutter column, looked like a bug in how
git-gutter applies faces to the left margin in terminal frames. I went
down the wrong path: I suspected that TTY rendering was silently dropping
symbolic face backgrounds, wrote a workaround that resolved faces eagerly
before passing them to the display engine, and spent considerable time
debugging Emacs's C display code to confirm or refute the hypothesis.
None of that was needed. The actual cause is a subtle but simple gotcha:
git-gutter:window-width reserves a column for every buffer, but cells
on unchanged rows are never written unless a sign is configured for
them. An unwritten cell falls back to the default frame background,
regardless of any face setting. Hopefully this section saves someone
else those hours.

The investigation also led to upstream bug #80693, which introduces the
margin face that now makes the fix one line on Emacs 31.1+.

What the documentation covers

• Context: why modern themes create the mismatch.
• How git-gutter uses faces on changed lines.
• The Emacs 31.1+ recommendation: customize the margin face; a
  snippet to derive it from line-number automatically.
• A note on performance: why the pre-31.1 workaround should be
  avoided on large files, and how to get a visual gap between the gutter
  and buffer text by widening git-gutter:window-width instead.
• The Emacs ≤30.x fallback: the original gotcha-and-workaround
  content, clearly labeled as version-gated.
• A note for theme designers covering both versions.

History

The original commit covered only the ≤30.x approach. After the margin
face landed upstream in May 2026 it became the recommended path; the PR
has been force-pushed with a single revised commit and this PR description
was correspondingly updated, since the branch has not yet been reviewed.

[alberti42]

Dear Jen-Chieh (@jcs090218),

A brief note on the history of this PR, since the force-push hides it:

• The investigation that led to this documentation also produced, as a by-product, a patch to Emacs' xdisp.c introducing a new margin basic face (bug #80693). The patch landed upstream in May 2026 and ships in Emacs 31.1.
• Once the patch landed, the old documentation in this PR was obsolete. I updated this PR to reflect the two recommended configurations: the simple margin-face approach on Emacs 31.1+, and the original gotcha-and-workaround approach as a clearly-labeled fallback for Emacs ≤30.x.

Yours, Andrea

[alberti42]

I forked this repository to alberti42/fork-git-gutter, where I reviewed and merged the 11 pull requests that were open here, the oldest from 2021, and fixed what they still needed. Many of them add real value, and it was a pity to see them sitting here, each on its own branch, while nobody could use them together. The last release here was 0.93 in September 2024, and no pull request from a contributor has been merged since December 2024. Many people use git-gutter in their daily work; the fork gives them a place to send issues and fixes, so that everyone gets them. The fork has released 0.94.0, and I hope to become a co-maintainer of this repository and bring the work back here.

This is now merged into the fork (alberti42/fork-git-gutter@55cd451, alberti42/fork-git-gutter@ec7d71b) and released in 0.94.0.