Commits, Diffs, History Inspection, Revision Ranges, and Message Discipline: Configuration, Design Choices, and Tradeoffs

1. History quality is partly Git configuration and mostly team design

Git can provide templates, aliases, display defaults, and diff algorithms. It cannot decide whether a commit is reviewable, whether an issue reference is required, or whether generated code belongs with its source change. Those are engineering policies layered on top of core Git behavior.

2. Commit templates guide authors without becoming commit content automatically

commit.template points Git at a file used to pre-populate the editor for new commit messages. It is a prompt for the human, not a schema enforced by the commit object.

# Example .gitmessage
<imperative subject: what changes>

Why is this change necessary?
What operational/review risk should a future reader know?
Issue/incident reference if team policy requires one:

Repository-local lab configuration

git config --local commit.template "$PWD/.gitmessage"
git config --show-origin --show-scope --get commit.template

On PowerShell, use git config --local commit.template (Join-Path $PWD '.gitmessage'). A local setting avoids changing unrelated repositories. For a team, a bootstrap script can point to a versioned template, but each clone still needs the config applied. A message supplied with -m bypasses interactive template use.

3. Message conventions should encode useful questions

A convention is valuable when it improves search, review, release notes, or automation. Common elements include a concise subject, a blank line, an explanatory body, an issue/incident reference, or structured trailers. Avoid treating “50 characters,” “72 columns,” a specific prefix vocabulary, or an issue-key syntax as universal Git requirements.

4. Aliases are convenience, not a hidden replacement for canonical commands

A useful local or global alias can reduce typing while keeping the underlying command recognizable:

git config --local alias.lg "log --graph --decorate --oneline --all"
git config --local alias.audit "log --date=iso-strict --pretty=format:%h%x09%aI%x09%an%x09%s"

git lg
git audit -10

Teach and document the canonical git log … form first. CI scripts should generally use explicit commands rather than depending on a developer's private alias set.

5. Date and pretty-format defaults affect presentation, not commit identity

format.pretty can change the default pretty format used by log/show-style output. Date presentation can be controlled per command with --date=iso-strict, --date=short, or other documented formats. Prefer explicit formats in automation so one machine's personal display defaults do not alter parsers or reports.

git log -5 --date=iso-strict --pretty=format:'%H %aI %cI %an %s'
git show --no-patch --pretty=fuller HEAD

Use stable placeholders intentionally. For machine pipelines, delimit fields safely and avoid scraping decorative graph output.

6. Diff algorithms change how a comparison is presented

Current Git exposes myers (the default), minimal, patience, and histogram diff algorithms. They can choose different hunk alignments for the same pair of snapshots.

git diff --diff-algorithm=myers HEAD^ HEAD
git diff --diff-algorithm=patience HEAD^ HEAD
git diff --diff-algorithm=histogram HEAD^ HEAD

You can configure diff.algorithm, but do not assume a prettier patch changes the underlying commit or tree. It is a comparison algorithm/presentation choice. This setting also should not be confused with the merge algorithm taught later.

7. Mailmap normalizes display identity without rewriting old commits

Long-lived repositories often contain the same person under old emails, renamed accounts, or inconsistent names. A top-level .mailmap can map historical identities to a canonical display identity.

A. Developer <alex@example.com> <alex@old.example.com>

git log --use-mailmap --format='%aN <%aE> %h %s'
git check-mailmap 'Alex Old '

Mailmap changes how supported commands present identity; it does not mutate old commit objects or their OIDs. Current Git also has log.mailmap behavior, but explicit --use-mailmap makes a report's intent obvious.

8. Commit size: optimize for one reviewable reason, not a magic line count

A commit should usually represent one coherent change that can be explained, reviewed, tested, and—where feasible—reverted independently. “Small” does not mean “one file.” A schema migration and the code required to consume it may belong together; two unrelated typo and behavior fixes in the same file may belong in separate commits.

Partial staging from Chapter 04 is a tool for shaping boundaries, but over-fragmenting every tiny edit can make history harder to follow. The policy target is cohesion.

9. Generated changes need an explicit history policy

If generated source, lockfiles, API clients, or documentation are tracked, decide whether the generator/source change and generated output belong in one commit or in adjacent commits. One commit can make the repository immediately buildable; separate commits can make review of handwritten logic easier. The right choice depends on reproducibility, review tooling, release workflow, and how reliably output can be regenerated.

10. Scope and precedence matter for history presentation

Personal aliases and display preferences are good global candidates. Project-specific commit templates, diff settings, and identity normalization may be local or versioned project files. A global format.pretty or diff.algorithm can surprise screenshots, support instructions, and automation if commands omit explicit options. Use git config --show-origin --show-scope when output differs across machines.

11. Git core versus hosting conventions

Pull-request titles, squash-message templates, issue autolinking, required commit-signing checks, merge queues, and release-note generators are hosting/product capabilities. Core Git supplies commits, messages, refs, diffs, and trailers. Keep the repository history understandable without requiring one provider's web UI to decode it.

12. Worked policy scenario

A team ships a backend weekly, uses an issue tracker, checks in a dependency lockfile, and generates API docs from code.

13. Knowledge check

14. Summary

Good history policy uses Git configuration to guide humans without hiding core semantics: templates suggest message structure, aliases/display settings improve ergonomics, diff algorithms alter comparison presentation, mailmap normalizes identity views, and commit boundaries remain an engineering decision about cohesion and operability.

Authoritative references

• git-commit
• git-config
• git-diff
• gitmailmap
• git-check-mailmap