git-adr

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

Pre-built Binaries

Download from GitHub Releases:

Platform	Download
macOS ARM64 (M1/M2/M3/M4)	git-adr-aarch64-apple-darwin.tar.gz
macOS Intel	git-adr-x86_64-apple-darwin.tar.gz
Linux x86_64	git-adr-x86_64-unknown-linux-gnu.tar.gz
Linux x86_64 (musl)	git-adr-x86_64-unknown-linux-musl.tar.gz
Linux ARM64	git-adr-aarch64-unknown-linux-gnu.tar.gz
Windows x86_64	git-adr-x86_64-pc-windows-msvc.zip

Homebrew (macOS)

brew tap zircote/tap
brew install git-adr

Cargo (Rust)

cargo install git-adr

With Optional Features

# AI-powered features (drafting, suggestions)
cargo install git-adr --features ai

# Wiki synchronization (GitHub/GitLab)
cargo install git-adr --features wiki

# Document export (DOCX format)
cargo install git-adr --features export

# All features
cargo install git-adr --features all

From Source

git clone https://github.com/zircote/git-adr.git
cd git-adr
cargo build --release
# Binary at target/release/git-adr

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 ADR-0001

# Search ADRs
git adr search "database"

# Sync ADRs 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 rm <id>	Remove an 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

Analytics & Export

Command	Description
git adr stats	Quick ADR statistics summary
git adr export	Export ADRs to files (markdown, json, html, docx)
git adr convert <id>	Convert an ADR to different format

Synchronization

Command	Description
git adr sync	Sync ADRs with remote (push & fetch)
git adr sync --push	Push ADR notes to remote only
git adr sync --pull	Fetch ADR notes from remote only

Configuration

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

Configuration Options

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

Key	Description	Default
adr.prefix	ADR ID prefix	ADR-
adr.digits	Number of digits in ADR ID	4
adr.template	Default template format	madr
adr.format	ADR format (nygard, madr, etc.)	nygard

Examples

# Set configuration
git adr config set template madr

# Get configuration
git adr config get template

# List all config
git adr config list

ADR Formats

git-adr supports multiple ADR formats:

Nygard (Default)

The original ADR format by Michael Nygard.

# Use PostgreSQL for primary database

## Status

Accepted

## Context

We need to choose a database...

## Decision

We will use PostgreSQL...

## Consequences

- ACID compliance
- Rich feature set

MADR

Markdown Architectural Decision Records format.