machu

Posted on Mar 15

Git Archaeology — A Complete Theory of Software Universes

#opensource #productivity #git #career

What if your git history could tell you who really shaped your codebase?

Over 16 chapters, I built a theory of software — starting from a simple question and ending with a cosmology. This is the complete arc, condensed into one read.

I. The Telescope

It started with a frustration: "This team is strong. But I had no words to explain it."

So I built a telescope. Using nothing but git log and git blame, I quantified engineering impact across 7 axes:

Axis	What it measures
Production	Volume of output (time-decayed)
Quality	Self-revision discipline
Survival	How long code lives without being rewritten
Design	Structural influence — files touched by others
Breadth	Reach across the codebase
Debt Cleanup	Cleaning up others' debt
Indispensability	How much of the codebase you "own" via blame

From these, three topologies emerge: Role (Architect / Anchor / Producer), Style (Builder / Balanced / Mass), and State (Active / Growing / Fragile / Former).

The numbers were eerily accurate. Silent heroes surfaced. Hidden risks became visible.

Quantify what you can. Qualitatively supplement what you can't. That order matters.

Deep dive: Chapter 1, Chapter 2

II. Evolution

When I added timelines — quarterly snapshots of scores — stories emerged.

An engineer's Role shifts from Producer to Anchor to Architect. Another's scores plateau — not from stagnation, but from strategic patience. A departure trajectory becomes visible three quarters before anyone notices.

Cold numbers tell the most human stories.

From these timelines, I extracted evolution laws:

Builder is a prerequisite for Architect — you cannot design what you haven't built
Producer is metabolism, not regression — sometimes the best Architects go back to producing
Backend Architects converge; Frontend Architects branch — different gravitational physics
Departed Architects leave "souls" in the code — laying them to rest through Debt Cleanup is sacred work

Deep dive: Chapter 3, Chapter 4, Chapter 5, Chapter 6

III. Cosmology

The deeper I looked, the more codebases looked like universes.

Physics	Software
Big Bang	First commit — initial conditions determine everything
Stars	Engineers
Gravity	Structural influence — great engineers bend the gravity of codebases
Dark Matter	Work invisible in commits: reviews, design discussions, mentoring, culture
Entropy	Code rot — left alone, code always tends toward disorder
Black Holes	Engineers who concentrate dependency instead of distributing structure
Collapse	What happens when a Black Hole Engineer leaves

This isn't metaphor. It's structural correspondence.

Gravity is the central concept. Not all code is equal. An engineer who creates a module boundary that 50 files depend on has generated gravity — a structural force that shapes everything around it.

Dark matter is what the telescope can't see. Culture, mentoring, design discussions, planning — these never appear in commits, but they determine the entire structure of the universe. A telescope must know its own limits.

Entropy is the default. Software always rots. Development is fundamentally a battle against entropy. Every EIS axis maps to either increasing entropy (Production) or fighting it (Quality, Design, Survival).

Collapse is what happens when gravity concentrates instead of distributes. A Black Hole Engineer writes great code — but when they leave, the codebase collapses instantly. A good Architect designs for the universe after they're gone.

Stars are not forever. That's why structure matters.

Deep dive: Chapter 7, Chapter 8, Chapter 9, Chapter 10, Chapter 11, Chapter 12

IV. Civilization

Most codebases die within a few years. Entropy wins. The team changes. Knowledge scatters. Someone says "let's rewrite from scratch."

But a few survive. Linux. Git. PostgreSQL. React. Their creators left, contributors turned over across generations, and the structure persisted. These are not repositories. They are civilizations.

Civilization requires three roles:

Civilization =
  Architect  → creates gravity (structure)
  + Anchor   → maintains order (stability)
  + Producer → expands territory (growth)

Remove any one and the equation breaks:

Missing	Result
No Architect	Growth without structure — entropy wins
No Anchor	Beautiful but fragile — collapses when Architect leaves
No Producer	Structure without growth — fossilization

The most important engineers build systems that don't need them. That's the civilization test: does the structure survive after the Architect leaves?

Deep dive: Chapter 13, Chapter 14

V. AI Creates Stars, Not Gravity

AI is a starburst — generating code at unprecedented rates.

But code without structure is entropy. No matter how many stars form, without gravity, no galaxy is born.

In the age of AI, the scarcest engineering capability shifts:

Era	Scarcest capability
Pre-AI	Writing code (Production)
Post-AI	Generating gravity (Design, Survival)

The engineers who thrive are not those whose primary differentiator is implementation speed. They are the ones who generate gravity — Code Architects who create structure, and Code Custodians who fight entropy.

AI becomes a gravity amplifier. An Architect who once shaped one codebase can now shape ten. The muscle that matters is not the muscle for writing code — it's the muscle for generating gravity.

AI creates stars. But engineers are the ones who shape gravity.

Deep dive: Chapter 15

VI. The Engineers Who Shape Gravity

Software engineering exists between two kinds of time.

Git remembers the past. AI imagines the future.

Between them, engineers shape gravity — creating structure, creating order, keeping the system from collapsing.

Where gravity exists, code is not mere fragments — it becomes structure. When structure emerges, systems persist beyond time. That is not just a repository. It becomes a civilization.

Git remembers the past.
AI imagines the future.

Between them, engineers shape gravity.

And from that gravity,
software civilizations emerge.

Deep dive: Chapter 16 — Final

Does your code universe have gravity?

Point the telescope and see.

❯ brew tap machuz/tap && brew install eis
❯ eis analyze --recursive ~/your-workspace

      ✦       *        ✧

       ╭────────╮
      │    ✦     │
       ╰────┬───╯
   .        │
            │
         ___│___
        /_______\

   ✧     the Git Telescope     ✦