readme-drift 1.0.1

Detect stale README references after code changes — for pre-commit and CI.

readme-drift

Detect stale README references after code changes — for pre-commit and CI.

When you rename a function, change a method signature, remove a class, or rename a key in a config file, readme-drift warns you if those names are still referenced in your README — before the commit lands.

---

How it works

flowchart LR
    A["git diff"] --> B["Changed .py files\nAST diff"]
    A --> C["Changed config files\nKey-path diff"]
    B --> D["Scan README\nbacktick + word-boundary"]
    C --> D
    D --> E{"Match?"}
    E -->|Yes| F["❌ Fail"]
    E -->|No| G["✅ Pass"]

---

Installation

pip install readme-drift

---

Usage

As a pre-commit hook (recommended)

Add to your .pre-commit-config.yaml:

repos:
  - repo: https://github.com/sachn1/readme-drift
    rev: v1.0.1 # use the latest release
    hooks:
      - id: readme-drift

Then install the hook:

pre-commit install

No extra args needed — the hook automatically checks your staged changes (what you've git add-ed). Do not pass --staged yourself; it's already set internally and duplicating it will cause an error.

In CI (GitHub Actions)

- name: Check README staleness
  run: readme-drift --base-ref origin/${{ github.base_ref }}

CI compares committed changes against a base branch. Do not pass --staged here.

As a CLI tool

readme-drift --staged                              # check staged changes
readme-drift --base-ref origin/main               # check against a branch
readme-drift --base-ref origin/main --warn-only   # warn but don't fail

---

Configuration

All CLI flags can be set permanently in pyproject.toml under [tool.readme-drift]. CLI flags always take precedence over the file.

[tool.readme-drift]
# Git ref to diff against. Default: "HEAD"
base-ref = "origin/main"

# Print warnings but never fail the build. Default: false
warn-only = false

# Track private (underscore-prefixed) symbols. Default: false
include-private = false

# Skip files or directories matching these glob patterns.
# Each entry is equivalent to one --exclude flag on the CLI.
# Default: []
exclude = [
    "generated/",
    "tests/",
    "docs/",
]

# Match symbols as plain text (word-boundary) in addition to backtick spans.
# Default: true. Set to false to restrict matching to backtick spans only.
plain-text-search = true

Supported keys

Key	Type	CLI equivalent	Default
base-ref	string	--base-ref	"HEAD"
warn-only	bool	--warn-only=true/false	false
include-private	bool	--include-private=true/false	false
exclude	list of strings	--exclude (repeatable)	[]
plain-text-search	bool	--plain-text-search=true/false	true

pyproject.toml is discovered by walking up from the current directory (or --repo-root if set). If no [tool.readme-drift] section is present, all defaults apply.

---

Developer reference

A fully annotated Jupyter notebook walks through each module in depth — AST parsing, signature extraction, config diffing, the README scanner, and the complete end-to-end pipeline without git. Useful for understanding the internals or experimenting with edge cases.

---

Example output

readme-drift: ❌ README.md may be stale:

  • `Client.connect` signature changed: connect(host, port) → connect(url)
    in src/client.py
    referenced in README.md line 42: …call `Client.connect(host, port)` to connect…

  • `build` was removed
    in package.json
    referenced in README.md line 18: …run `npm run build` to compile…

  → Please update the README or run with --no-verify to skip.

---

What it catches

Python files (.py)

Change	Detected?
Function renamed	✅ old name flagged as removed
Function removed	✅
Method signature changed	✅
Class removed	✅
Private symbol changed (_name)	➖ ignored by design
README updated alongside code	✅ passes silently
No Python files changed	✅ skipped

Config files (.yml, .yaml, .json, .toml)

Change	Detected?
Script key removed ("build" → gone)	✅
Job name removed (build: → gone)	✅
Tool section removed ([tool.black] → gone)	✅
Key renamed at same level	✅ (reported as remove + add)
Value changed, key unchanged	➖ not tracked

What it doesn't catch

• Behavioral changes that don't affect the public API or config surface
• Symbols not mentioned in the README

---

Supported README formats

Any file named readme (case-insensitive) with the extension .md, .markdown, .rst, .txt, or no extension is scanned. All README files in the repository are discovered recursively, including per-package READMEs in monorepos.

The following directories are never searched:

.git · node_modules · venv · .venv · .tox · __pycache__ · .pytest_cache · dist · build · .mypy_cache

---

License

MIT