git-adr

Architecture Decision Records (ADR) management for git repositories using git notes.

Overview

git-adr is a command-line tool that integrates Architecture Decision Record management directly into your git workflow. Unlike file-based ADR tools, git-adr stores ADRs in git notes, making them:

Non-intrusive: No files cluttering your repository
Portable: Travel with your git history
Linkable: Associate decisions with specific commits
Searchable: Full-text search across all decisions
Syncable: Push/pull ADRs like regular git content

Installation

Homebrew (macOS)

The recommended installation method for macOS:

brew tap zircote/git-adr
brew install git-adr

This automatically installs shell completions and keeps git-adr updated with brew upgrade.

pip / uv

pip install git-adr

Or with uv:

uv tool install git-adr

With Optional Features

# AI-powered features (drafting, suggestions, Q&A)
pip install "git-adr[ai]"

# Wiki synchronization (GitHub/GitLab)
pip install "git-adr[wiki]"

# Document export (DOCX format)
pip install "git-adr[export]"

# All features
pip install "git-adr[all]"

Shell Completion

Enable tab completion for your shell:

# Automatic installation (detects your shell)
git-adr --install-completion

# Or manually for specific shells
git-adr --show-completion bash >> ~/.bashrc
git-adr --show-completion zsh >> ~/.zshrc
git-adr --show-completion fish > ~/.config/fish/completions/git-adr.fish

Man Pages

Man pages are included in GitHub releases. Download and install:

# Download from release (replace VERSION)
curl -L https://github.com/zircote/git-adr/releases/download/vVERSION/git-adr-man-pages-VERSION.tar.gz | \
  sudo tar -xzf - -C /usr/local/share/man/

# Then use
man git-adr
man git-adr-new

Or build from source:

git clone https://github.com/zircote/git-adr.git
cd git-adr
make install-man  # Requires pandoc

Quick Start

# Initialize ADR tracking in your repository
git adr init

# Create a new ADR (opens editor)
git adr new "Use PostgreSQL for primary database"

# List all ADRs
git adr list

# Show a specific ADR
git adr show 20240115-use-postgresql

# Search ADRs
git adr search "database"

# Sync with remote
git adr sync push

Commands

Core Commands

Command	Description
`git adr init`	Initialize ADR tracking in repository
`git adr new <title>`	Create a new ADR
`git adr list`	List all ADRs with filtering options
`git adr show <id>`	Display an ADR with formatting
`git adr edit <id>`	Edit an existing ADR
`git adr search <query>`	Full-text search across ADRs
`git adr link <adr-id> <commit>`	Associate an ADR with commits
`git adr supersede <old-id> <title>`	Create ADR that supersedes another
`git adr log`	Show git log with ADR annotations

Artifact Management

Command	Description
`git adr attach <adr-id> <file>`	Attach diagram/image to an ADR
`git adr artifacts <adr-id>`	List artifacts attached to an ADR
`git adr artifact-get <sha256>`	Extract an artifact to a file
`git adr artifact-rm <adr-id> <sha256>`	Remove an artifact

Analytics & Reporting

Command	Description
`git adr stats`	Quick ADR statistics summary
`git adr report`	Generate detailed analytics report
`git adr metrics`	Export metrics for dashboards (JSON/Prometheus)

Export & Import

Command	Description
`git adr export`	Export ADRs to files (markdown, json, html, docx)
`git adr import`	Import ADRs from file-based storage
`git adr convert <id>`	Convert an ADR to different format

Synchronization

Command	Description
`git adr sync push`	Push ADR notes to remote
`git adr sync pull`	Pull ADR notes from remote

Configuration

Command	Description
`git adr config --list`	List all configuration
`git adr config <key> <value>`	Set configuration value
`git adr config --get <key>`	Get configuration value

Team Features

Command	Description
`git adr onboard`	Interactive onboarding wizard for new team members

AI Features

Requires pip install "git-adr[ai]"

Configure your AI provider:

# Set provider (openai, anthropic, google, ollama)
git adr config adr.ai.provider openai

# Set API key (environment variable)
export OPENAI_API_KEY="your-key"
# or
export ANTHROPIC_API_KEY="your-key"
export GOOGLE_API_KEY="your-key"

AI Commands

Command	Description
`git adr ai draft`	AI-guided ADR creation with interactive elicitation
`git adr ai suggest <id>`	Get AI suggestions to improve an ADR
`git adr ai summarize`	Generate natural language summary of decisions
`git adr ai ask "<question>"`	Ask questions about ADRs in natural language

Examples

# AI-assisted drafting
git adr ai draft "Choose a message queue"

# Get improvement suggestions
git adr ai suggest 20240115-use-postgresql

# Summarize recent decisions
git adr ai summarize --format slack

# Ask questions
git adr ai ask "Why did we choose PostgreSQL?"

Wiki Synchronization

Requires pip install "git-adr[wiki]"

Sync ADRs with GitHub or GitLab wikis:

# Initialize wiki sync
git adr wiki init --provider github --repo owner/repo

# Sync ADRs to wiki
git adr wiki sync

Configuration Options

Configuration is stored in git config (local or global):

Key	Description	Default
`adr.namespace`	Notes namespace	`adr`
`adr.template`	Default template format	`madr`
`adr.editor`	Editor command override	`$EDITOR`
`adr.ai.provider`	AI provider (openai, anthropic, google, ollama)	-
`adr.ai.model`	AI model name	Provider default
`adr.ai.temperature`	AI temperature (0.0-1.0)	`0.7`

Examples

# Set local config
git adr config adr.template madr

# Set global config
git adr config --global adr.editor "code --wait"

# List all config
git adr config --list

ADR Format (MADR)

ADRs follow the MADR format:

---
id: 20240115-use-postgresql
title: Use PostgreSQL for primary database
date: 2024-01-15
status: accepted
tags: [database, infrastructure]
---

## Context and Problem Statement

We need to choose a database for our application...

## Decision Drivers

* Performance requirements
* Team expertise
* Operational complexity

## Considered Options

* PostgreSQL
* MySQL
* MongoDB

## Decision Outcome

Chosen option: "PostgreSQL", because...

### Consequences

#### Good
- ACID compliance
- Rich feature set

#### Bad
- Requires more operational expertise

Git Notes Architecture

git-adr uses git notes to store ADRs, which provides:

No file pollution: ADRs live in git's notes refs, not in your working tree
Full git integration: Push, pull, merge like regular git content
Commit association: Link decisions to the commits that implement them
History preservation: ADR history is preserved in git

Notes are stored under:

refs/notes/adr - ADR content
refs/notes/adr-index - Search index
refs/notes/adr-artifacts - Binary attachments

Development

Setup

# Clone the repository
git clone https://github.com/zircote/git-adr.git
cd git-adr

# Install dependencies with uv
uv sync --all-extras

# Run tests
uv run pytest

# Run with coverage
uv run pytest --cov=src/git_adr --cov-report=term-missing

Code Quality

# Format code
uv run ruff format .

# Lint and fix
uv run ruff check . --fix

# Type check
uv run mypy src

# Security scan
uv run bandit -r src/

# Dependency audit
uv run pip-audit

Project Structure

src/git_adr/
├── __init__.py          # Package exports
├── cli.py               # Main CLI entry point
├── core/                # Core functionality
│   ├── adr.py           # ADR data models
│   ├── config.py        # Configuration management
│   ├── git.py           # Git operations wrapper
│   ├── notes.py         # Git notes management
│   ├── index.py         # Search index
│   └── templates.py     # ADR templates
├── commands/            # CLI command implementations
│   ├── basic.py         # Core commands (new, list, show, etc.)
│   ├── ai_cmds.py       # AI-powered commands
│   ├── wiki.py          # Wiki sync commands
│   └── export.py        # Export/import commands
├── ai/                  # AI service integration
│   └── service.py       # LLM provider abstraction
├── wiki/                # Wiki providers
│   └── service.py       # GitHub/GitLab wiki sync
└── formats/             # Format converters
    └── docx.py          # DOCX export

Contributing

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Make your changes
Run tests and linting (uv run pytest && uv run ruff check .)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

License

MIT License - see LICENSE for details.

Claude Code Skill

A comprehensive Claude Code skill is included for AI-assisted ADR management:

# Install the skill (from git-adr repository)
cp -r skills/git-adr ~/.claude/skills/

# Or extract from package
tar -xzf skills/git-adr.skill -C ~/.claude/skills/

The skill enables Claude to:

Execute commands: Run any git-adr command directly
Generate content: Create ADRs in any of the 6 supported formats
Teach best practices: Guide users on effective ADR writing
Match project style: Automatically detect and use your configured template

Skill structure:

skills/git-adr/
├── SKILL.md                    # Core instructions (258 lines)
└── references/
    ├── commands.md             # Full command reference
    ├── configuration.md        # All adr.* config options
    ├── best-practices.md       # ADR writing guidance
    ├── workflows.md            # Common workflow patterns
    └── formats/
        ├── madr.md             # MADR 4.0 template
        ├── nygard.md           # Original minimal format
        ├── y-statement.md      # Single-sentence format
        ├── alexandrian.md      # Pattern-language format
        ├── business-case.md    # Business justification
        └── planguage.md        # Quantified requirements

Acknowledgments

MADR - Markdown ADR format
ADR Tools - Original ADR tooling inspiration

Name		Name	Last commit message	Last commit date
Latest commit History 67 Commits
.github		.github
docs		docs
script		script
skills		skills
src/git_adr		src/git_adr
tests		tests
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
pyproject.toml		pyproject.toml
uv.lock		uv.lock

Folders and files

Latest commit

History

Repository files navigation

git-adr

Overview

Installation

Homebrew (macOS)

pip / uv

With Optional Features

Shell Completion

Man Pages

Quick Start

Commands

Core Commands

Artifact Management

Analytics & Reporting

Export & Import

Synchronization

Configuration

Team Features

AI Features

AI Commands

Examples

Wiki Synchronization

Configuration Options

Examples

ADR Format (MADR)

Git Notes Architecture

Development

Setup

Code Quality

Project Structure

Contributing

License

Claude Code Skill

Acknowledgments

About

Topics

Resources

License

Code of conduct

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases 15

Packages 0

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

Packages