---
description: "What git-span is, what a span is, and why declared-but-unenforced coupling deserves a tool."
---

# Introduction (/docs/overview)

git-span tracks the dependencies in your codebase that nothing enforces. A **span** is a named, declared coupling between file or line ranges — places that must change together even though no schema, type system, or test says so. git-span records that coupling next to your code, in git, and tells you when the anchored code drifts away from it.

## The problem

Every codebase accumulates invisible couplings:

* A serializer and a deserializer that must agree on a wire format.
* A config default and the three call sites that assume it.
* A SQL migration and the ORM model it must match.
* A comment in one file explaining an invariant maintained in another.

None of these are enforced. The compiler doesn't know about them, tests rarely cover the pairing itself, and the knowledge usually lives in one person's head. When someone edits one side without the other, nothing fails — until it does, later, somewhere else.

## What a span does about it

A span makes the coupling explicit without pretending to enforce it:

1. **Declare** it: `git span add` names a group of anchors — whole files or `path#Lstart-Lend` line ranges — that form one subsystem or concern.
2. **Explain** it: `git span why <name> "..."` attaches one or two complete present-tense clauses stating the shared relationship and the nonlocal fact that changes a safe decision. The why is the payload; a span without one is just a list of locations.
3. **Commit** it: span data lives in a `.span/` directory tracked by git, so declarations travel with the code, merge with branches, and appear in history.
4. **Audit** it: `git span drift` reports every anchor whose code has drifted since it was declared — moved, changed, or gone — so a reviewer or CI job can ask "did you mean to break this coupling?"

git-span never blocks an edit and never claims the coupling still holds. It keeps an honest record of what someone once declared and shows you exactly where reality has diverged from it. Deciding whether drift is fine or a bug stays with you.

## Built for agents, usable by anyone

git-span is designed to be operated by coding agents. It ships as plugins for Claude Code and OpenAI Codex whose in-session hooks keep spans honest as an agent works: a touch hook heals positional drift after supported file-affecting tool calls, and a commit advisor holds commits that carry real span debt so the report gets read. Every capability behind those hooks is still a plain, scriptable CLI — the same commands work by hand, and the same `git span drift` exit code is what CI checks at merge time.

> [!NOTE]
> You don't have to use an agent to use git-span. The plugins are a convenience layer over a CLI that's complete on its own — see [Agent integration](/docs/agent-integration) if you're wiring an agent up, or skip straight to [Command reference](/docs/commands) if you're not.

## Where to go next

* [Getting started](/docs/getting-started) — install the CLI, then wire it into Claude Code or Codex.
* [Agent integration](/docs/agent-integration) — what the plugin hooks, skills, and expert subagent actually do.
* [Concepts](/docs/concepts) — spans, anchors, drift, and the why, defined precisely.
* [Command reference](/docs/commands) — every subcommand, grouped by task.
* [CI & git integration](/docs/ci) — make `git span drift` part of review.