Chapter 6: Git history: The product's memory
This chapter introduces git history as the product memory that AI can turn into a story of pivots, eras, contributors, and abandoned features.
After this chapter you will be able to
- Git log as product memory. Explain why a codebase's git log can reveal product decisions, pivots, and deleted features that may not appear in the README, changelog, or marketing.
- AI-driven history analysis. Describe the chapter's three AI-assisted history analyses: grouping commits into major eras, profiling the contributors and work mix within an era, and surfacing features the team later abandoned.
- Commit log as product diary. Explain how individual commits accumulate into an unintentional diary of a product’s life. State that each commit records who made a change, when, which files changed, and a message describing why.
- History as honest audit trail. Justify why the shared Git log is more trustworthy than polished project documents: it is a byproduct of everyday collaboration, debugging, rollback, and experimentation rather than a story written for an audience. Explain that local history can be rewritten with git rebase, but rewriting pushed shared or protected history is blocked or leaves visible fingerprints.
- Commit as change receipt. Describe a Git commit as a permanent, uniquely hashed receipt for a code change, and state the four kinds of facts it preserves: who made it, when, what changed, and why.
- Filters and granularities. Distinguish the commit filter, which chooses which commits appear, from granularity, which controls how much detail appears for each selected commit. Explain that the two choices are independent and can be combined.
- Analysis zoom levels. Explain why Git-history analyses must operate at the appropriate zoom level: commit level for contributor activity, file level for concentrated work or deletions, and code level when investigating one specific dead feature. Describe the failure modes of looking too broadly or too narrowly.
- Named product eras. Describe how a long commit history becomes three to five chronological eras, each named for the product bet the team was making rather than for the directories that changed.
- History compression signals. Explain the three compressed history signals supplied to the model: continuous directory attention, directory lifecycles, and large bulk additions or deletions. Describe what each signal contributes to identifying eras and pivots.
- Evidence-backed era boundaries. Describe the required evidence for an era: a name, start and end months, product-focused description, ending turning point, and optional opening and turning-point commit hashes drawn from bulk-addition or bulk-deletion rosters. Explain when a hash remains empty for a gradual beginning or ongoing ending.
- Raw era profiling inputs. Describe why an era profile uses every commit in that era as compact one-line records plus five landmark diffs, rather than a pre-aggregated summary or commit subjects alone.
- Cast and mood profile. Explain that an era profile reports the top four or five contributors by commit share and a narrative about team shape, then identifies three to five era-specific work patterns with percentages and a narrative about what dominated the period.
- Commit-history health metrics. State how git history can be used to assess lead time, bus factor, and tech-debt ratio: trace a feature from first commit to a release tag, count how many people maintain a system, and compare the share of fixes with feature work.
- Bulk-deletion feature detection. Describe how to identify candidate killed features in Git history by finding commits that delete five or more files from one folder, while distinguishing these from ordinary renames and cleanup.
- Diff-based feature reconstruction. Explain why each candidate deletion requires the full git show diff and how an AI should use the removed source code, not file names alone, to describe the retired feature's actual user-facing behavior.
- Graveyard entry construction. Describe the four-part graveyard entry for each major deletion: what it was, what the team believed, why it died, and what the removal signals about product direction, followed by a memorable name, tagline, and epitaph.
What it builds on
- Every codebase builds for someone, even a library (chapter 5) · The four project types—web apps, libraries, CLIs, and data pipelines—and their differing structures.
- Ask for the product in one "It's X, but Y" sentence (chapter 5) · Expressing product intent as a concise strategic statement.
- Competitive positioning: The one bet rivals can't copy (chapter 5) · Interpreting a product's distinctive competitive bet.
Section by section
Introduction
This chapter introduces git history as the product memory that AI can turn into a story of pivots, eras, contributors, and abandoned features.
- Git log as product memory: Explain why a codebase's git log can reveal product decisions, pivots, and deleted features that may not appear in the README, changelog, or marketing.
Why it matters: Git history can expose how and why the current product took shape, rather than only showing its present state. - AI-driven history analysis: Describe the chapter's three AI-assisted history analyses: grouping commits into major eras, profiling the contributors and work mix within an era, and surfacing features the team later abandoned.
Why it matters: These analyses turn thousands of raw commits into a coherent account of a project's direction and evolution.
Key terms: git log, product history, README, pivots, deleted features, eras, top contributors, work mix, killed features, raw git history
6.1 Git log: The record nothing else keeps
This section establishes the Git log as a broadly available, relatively trustworthy audit trail of a product’s real development history.
- Commit log as product diary: Explain how individual commits accumulate into an unintentional diary of a product’s life. State that each commit records who made a change, when, which files changed, and a message describing why.
Why it matters: The commit log can reveal where a team spent effort, what repeatedly broke, and what features disappeared. - Daily Git change path: Describe the path from an edited working directory to shared team history: git add selects changes for the staging area, git commit creates a local repository entry, git push sends commits to a shared remote, and git pull brings teammates’ commits to the local machine.
Why it matters: Knowing how routine Git actions produce commits explains why nearly every repository has usable history. - History as honest audit trail: Justify why the shared Git log is more trustworthy than polished project documents: it is a byproduct of everyday collaboration, debugging, rollback, and experimentation rather than a story written for an audience. Explain that local history can be rewritten with git rebase, but rewriting pushed shared or protected history is blocked or leaves visible fingerprints.
Why it matters: A raw trail of daily work can challenge a README, changelog, or slide deck that was rewritten after the fact. - Universal repository history: State that every Git repository has commit history regardless of whether it is a web app, library, CLI, or data pipeline, because all are built commit by commit and commits carry the same basic fields.
Why it matters: Git history provides one investigation layer that works even when codebases have completely different file structures.
Key terms: Git log, commit, snapshot, project diary, commit message, working directory, staging area, local repository, shared remote, git add
6.2 Three zoom levels: Pick the wrong one and the read fails
This section explains how to choose and combine Git-history zoom levels, filters, and one reusable commit dataset to survey a repository before investigating specific product decisions.
- Commit as change receipt: Describe a Git commit as a permanent, uniquely hashed receipt for a code change, and state the four kinds of facts it preserves: who made it, when, what changed, and why.
Why it matters: Commits preserve the decision trail behind a product long after announcements and changelogs have lost it. - Filters and granularities: Distinguish the commit filter, which chooses which commits appear, from granularity, which controls how much detail appears for each selected commit. Explain that the two choices are independent and can be combined.
Why it matters: Separating selection from detail lets you ask a focused historical question without losing control over the evidence you inspect. - Analysis zoom levels: Explain why Git-history analyses must operate at the appropriate zoom level: commit level for contributor activity, file level for concentrated work or deletions, and code level when investigating one specific dead feature. Describe the failure modes of looking too broadly or too narrowly.
Why it matters: The wrong altitude either hides the product pivots or buries them beneath routine refactors. - Reusable commit dataset: Describe turning machine-readable git log output into one dictionary per commit so the same collected history can be filtered, grouped, and counted for multiple analyses instead of requiring a fresh query each time.
Why it matters: A reusable dataset makes history investigation repeatable: different questions become different slices of the same evidence. - Archaeological reading sequence: Trace the two-level history-reading process: first survey the repository to identify major eras, then excavate one era to examine its contributors, work, and abandoned features.
Why it matters: Surveying before excavating gives detailed findings their product-history context.
Key terms: commit, unique hash, git show, filter, granularity, --diff-filter=A, --diff-filter=D, machine-readable format, commit level, file level
6.3 Aggregate commits by directory and month into eras
This section shows how to compress git activity into evidence-backed, named product eras that reveal a codebase's strategic pivots and current trajectory.
- Named product eras: Describe how a long commit history becomes three to five chronological eras, each named for the product bet the team was making rather than for the directories that changed.
Why it matters: Named eras turn an overwhelming commit log into a product story a new team member can remember and investigate. - History compression signals: Explain the three compressed history signals supplied to the model: continuous directory attention, directory lifecycles, and large bulk additions or deletions. Describe what each signal contributes to identifying eras and pivots.
Why it matters: These summaries make a history too large for a prompt small enough to analyze while retaining the evidence needed for a credible narrative. - Evidence-backed era boundaries: Describe the required evidence for an era: a name, start and end months, product-focused description, ending turning point, and optional opening and turning-point commit hashes drawn from bulk-addition or bulk-deletion rosters. Explain when a hash remains empty for a gradual beginning or ongoing ending.
Why it matters: Grounding transitions in dated activity and specific commits keeps the AI from inventing a persuasive but unsupported history. - Strategic narrative interpretation: Explain that the model should read the evidence as a causal product narrative: state why the team changed direction, lead with user or product meaning, and connect each new era to the bet the preceding era did not fulfill.
Why it matters: A causal narrative helps a newcomer understand why today's architecture exists instead of merely memorizing its directory structure. - Post-timeline health questions: Describe the three follow-up questions an era timeline enables: shipping cadence from version tags, velocity trend from commit volume across eras, and pivot payoff from activity before and after the latest bet. Explain that a plateau can indicate maturity rather than decline.
Why it matters: These comparisons turn history into practical expectations about release rhythm, project momentum, and whether the current direction is taking hold.
Key terms: eras, product bet, turning point, timeline, heatmap summary, continuous attention, active date range, peak month, directory lifecycle, pivot points
6.4 Profile each era's top contributors and work mix
This section shows how to use compact raw commit data and landmark diffs to profile each historical era’s contributors, work patterns, team evolution, and maintenance signals.
- Raw era profiling inputs: Describe why an era profile uses every commit in that era as compact one-line records plus five landmark diffs, rather than a pre-aggregated summary or commit subjects alone.
Why it matters: This keeps surprising patterns visible while grounding the AI’s conclusions in actual code changes. - Cast and mood profile: Explain that an era profile reports the top four or five contributors by commit share and a narrative about team shape, then identifies three to five era-specific work patterns with percentages and a narrative about what dominated the period.
Why it matters: The profile turns a large commit log into an evidence-based picture of who drove the product and what they were building or maintaining. - Era-specific work categories: Justify letting the model invent work buckets specific to each era, naming them first in plain product terms and then connecting them to code evidence from the landmark diffs.
Why it matters: Work that matters in one phase, such as initial setup or subscription billing, can be absent or meaningless in another phase. - Historical team and product signals: Describe how comparing era profiles can reveal leadership handoffs, shifts from founder-led to distributed or flat teams, and product phases such as prototyping, maintaining a fading bet, pivoting, and iteration.
Why it matters: Git history can reveal changes in responsibility and product direction before they appear in official announcements or an org chart. - Commit-history health metrics: State how git history can be used to assess lead time, bus factor, and tech-debt ratio: trace a feature from first commit to a release tag, count how many people maintain a system, and compare the share of fixes with feature work.
Why it matters: These measures help predict delivery speed, identify single-person risks, and spot maintenance crowding out new product work.
Key terms: commit stream, month | author | scope | subject, landmark diffs, opening, early peak, mid peak, cast, mood, contributors, commit share
6.5 Read the graveyard of killed features
This section shows how to mine bulk-deletion commits with AI to reconstruct killed product bets and infer the strategic direction they reveal.
- Bulk-deletion feature detection: Describe how to identify candidate killed features in Git history by finding commits that delete five or more files from one folder, while distinguishing these from ordinary renames and cleanup.
Why it matters: Large deletions can reveal product decisions that current code and marketing pages no longer show. - Diff-based feature reconstruction: Explain why each candidate deletion requires the full git show diff and how an AI should use the removed source code, not file names alone, to describe the retired feature's actual user-facing behavior.
Why it matters: A folder name can make an unfinished stub look like a finished product, whereas deleted code reveals what users could actually do. - Graveyard entry construction: Describe the four-part graveyard entry for each major deletion: what it was, what the team believed, why it died, and what the removal signals about product direction, followed by a memorable name, tagline, and epitaph.
Why it matters: This format turns a code deletion into a dated, understandable record of a strategic bet the team abandoned. - Deletion health assessment: Explain how reversion rate, a successor feature, and deletion discipline indicate whether a feature removal was a sound strategic cut, a harmful breakage, or evidence of a team hoarding dead code.
Why it matters: These checks prevent treating every deletion as a wise decision just because the code is gone.
Key terms: killed feature, bulk-deletion commit, graveyard, git show, full diff, deleted code, product terms, graveyard entry, What it was, What they believed
6.6 Summary
This summary presents Git history as an unspun product record and recaps how to query it at the right scale to infer project eras, team lifecycle, and abandoned strategy.
Where this is used later
- Summary (chapter 7) · Grouping historical changes into eras to make product evolution visible
- Mine the migration folder for the roadmap (chapter 7) · Migration history is likewise used to reconstruct how product and technical direction changed over time.
- Four sources hold the architecture (chapter 9) · The later architecture investigation benefits from recognizing that the current structure may reflect major removals and replacements.
- Trace one request across the whole system (chapter 9) · Tracing the current system benefits from knowing which present components replaced older capabilities.
Concepts explained in this chapter
- diffA diff is a representation of the changes between two versions of files or other structured content.
- bus factorBus factor is the number of contributors whose loss would make a system or area of work unmaintainable.
- commit summaryA commit subject is the short summary line describing the change recorded by a version-control commit.
- dependency update eventA dependency update is a change that moves a software project to a different version of an external package or component.
- era profileAn era profile is a structured summary of the contributors and dominant work patterns within a defined period of a project's development.
- lead timeLead time is the elapsed time between the initial creation of a software change and its delivery to production.
- tech-debt ratioA tech-debt ratio is a measure of the share of engineering work devoted to addressing technical debt or maintenance rather than new features.
- feature deletionFeature deletion is the removal of a previously implemented product capability from a software system.
- graveyard entryA graveyard entry is a dated record describing a software feature that was built and later removed, including its purpose, rationale, and product meaning.
- monolithic architectureA monolith is a software system whose major application functionality is developed and deployed as one tightly integrated unit.
- plugin systemA plugin system is an extensibility architecture that loads separately developed components into an application through defined hooks, models, and permissions.
- reversion rateReversion rate is the frequency with which a change is undone through revert or corrective commits after its introduction.
- bulk additionA bulk addition is a commit change that introduces many files or other repository artifacts at once.
- commit volumeCommit volume is the number of commits recorded for a project or period of its development history.
- directory lifecycleA directory lifecycle is the span from a directory's first recorded activity to its last recorded activity in a codebase's history.
- eraAn era is a defined historical period characterized by a distinct strategy, product identity, or pattern of activity.
- git loggit log is a Git command that displays the commit history of a repository and can format or filter its output.
- git showgit show is a Git command that displays the metadata and content changes associated with one or more objects, commonly commits.
- granularityGranularity is the level of detail at which an item or collection of items is examined.
- promptA prompt is an instruction or input supplied to an AI model to elicit a particular response.
- fix-rateFix-rate is the proportion of recorded software changes classified as fixes or bug repairs.
- repositoryA repository is a structured collection of a software project's files and directories managed as a unit.
These guides are generated from the text of Manning books by Manning's knowledge graph and link to the sections they draw on. The full books are available on liveBook and at manning.com.
