Skip to content

Commands Reference

Jump to bottom
Robert Allen edited this page Dec 15, 2025 · 1 revision

Commands Reference

Complete reference for all git-adr commands. For detailed help on any command, run git adr <command> --help.

Quick Reference

Command Description
git adr init Initialize ADR tracking in repository
git adr new <title> Create a new ADR
git adr list List all ADRs
git adr show <id> Display a single ADR
git adr edit <id> Edit an existing ADR
git adr rm <id> Remove an ADR
git adr search <query> Search ADRs by content
git adr link <id> <commit> Link ADR to a commit
git adr supersede <old-id> <title> Create ADR that supersedes another
git adr sync Sync ADRs with remote
git adr stats Quick statistics summary

Core Commands

git adr init

Initialize ADR tracking in the current repository.

git adr init

What it does:

  • Creates the first ADR documenting use of ADRs
  • Configures git to sync notes with remote repositories
  • Sets up refs/notes/adr and related namespaces

Options:

  • --namespace <name> - Custom namespace (default: adr)
  • --template <format> - Default template format (default: madr)

Example:

cd my-project
git adr init

git adr new

Create a new Architecture Decision Record.

git adr new <title>

Options:

  • --template <format> - Override default template (madr, nygard, y-statement, alexandrian, business, planguage)
  • --status <status> - Initial status (default: proposed)
  • --tags <tags> - Comma-separated tags
  • --file <path> - Read content from file instead of opening editor
  • --preview - Show template without creating ADR

Examples:

# Open editor with template
git adr new "Use PostgreSQL for primary database"

# With tags
git adr new "Use PostgreSQL" --tags database,infrastructure

# Use minimal Nygard template
git adr new "Use Feature Flags" --template nygard

# Create from file (for automation)
git adr new "Migrate to Cloud" --file decision.md

# Preview the template
git adr new "Test Decision" --preview

git adr list

List all ADRs with optional filtering.

git adr list [options]

Options:

  • --status <status> - Filter by status (accepted, proposed, deprecated, rejected, superseded)
  • --tags <tags> - Filter by tags (comma-separated)
  • --since <date> - Show ADRs since date (YYYY-MM-DD)
  • --until <date> - Show ADRs until date
  • --format <format> - Output format (table, json, simple)
  • --sort <field> - Sort by field (date, title, status)

Examples:

# List all ADRs
git adr list

# Filter by status
git adr list --status accepted

# Filter by tags
git adr list --tags database

# Date range
git adr list --since 2025-01-01 --until 2025-06-30

# JSON output for scripting
git adr list --format json

git adr show

Display a single ADR with formatting.

git adr show <id>

Options:

  • --format <format> - Output format (rich, markdown, json)
  • --no-color - Disable colored output

Examples:

# Show formatted ADR
git adr show 20250115-use-postgresql

# Raw markdown
git adr show 20250115-use-postgresql --format markdown

# JSON for scripting
git adr show 20250115-use-postgresql --format json

git adr edit

Edit an existing ADR.

git adr edit <id>

Options:

  • --status <status> - Update status directly without opening editor
  • --add-tag <tag> - Add a tag
  • --remove-tag <tag> - Remove a tag
  • --link <commit> - Add commit link
  • --unlink <commit> - Remove commit link

Examples:

# Open in editor
git adr edit 20250115-use-postgresql

# Quick status update
git adr edit 20250115-use-postgresql --status accepted

# Add a tag
git adr edit 20250115-use-postgresql --add-tag infrastructure

git adr rm

Remove an ADR from git notes.

git adr rm <id>

Options:

  • --force - Skip confirmation prompt

Behavior:

  • Shows ADR title and status before confirmation
  • Warns if the ADR has linked commits
  • Warns if the ADR supersedes or is superseded by other ADRs

Examples:

# Interactive removal (shows confirmation)
git adr rm 20250115-draft-decision

# Skip confirmation (for scripting)
git adr rm 20250115-draft-decision --force

git adr search

Full-text search across all ADRs.

git adr search <query>

Options:

  • --status <status> - Limit search to specific status
  • --tags <tags> - Limit search to specific tags
  • --format <format> - Output format (table, json)

Examples:

# Basic search
git adr search "database"

# Search within accepted ADRs
git adr search "performance" --status accepted

# Search with specific tags
git adr search "authentication" --tags security

git adr link

Associate an ADR with a commit.

git adr link <id> <commit>

Examples:

# Link to specific commit
git adr link 20250115-use-postgresql abc1234

# Link to HEAD
git adr link 20250115-use-postgresql HEAD

# Link to commit by message
git adr link 20250115-use-postgresql "$(git log --oneline | head -1 | cut -d' ' -f1)"

git adr log

Show git log with ADR annotations.

git adr log [options]

Options:

  • Standard git log options are supported
  • --oneline - Compact output
  • -n <count> - Limit number of commits

Examples:

# Show annotated log
git adr log

# Last 10 commits
git adr log -n 10

# Compact format
git adr log --oneline

git adr supersede

Create an ADR that supersedes an existing one.

git adr supersede <old-id> <new-title>

Options:

  • --template <format> - Template for new ADR

What it does:

  1. Creates a new ADR with reference to the old one
  2. Updates the old ADR's status to "superseded"
  3. Adds bidirectional links between the ADRs

Example:

git adr supersede 20250115-use-mysql "Migrate to PostgreSQL"

Attachment Commands

git adr attach

Attach a file (diagram, image, document) to an ADR.

git adr attach <id> <file>

Options:

  • --description <text> - Description for the attachment
  • --force - Skip size warning

Supported formats: Images (PNG, JPG, SVG), PDFs, Markdown files, and other documents.

Example:

git adr attach 20250115-use-postgresql architecture-diagram.png --description "System architecture overview"

git adr artifacts

List artifacts attached to an ADR.

git adr artifacts <id>

Example:

git adr artifacts 20250115-use-postgresql

git adr artifact-get

Extract an artifact to a file.

git adr artifact-get <id> <sha256> --output <path>

Example:

git adr artifact-get 20250115-use-postgresql abc123def456 --output diagram.png

git adr artifact-rm

Remove an artifact from an ADR.

git adr artifact-rm <id> <sha256>

Options:

  • --force - Skip confirmation

Synchronization Commands

git adr sync

Sync ADRs with remote repository.

git adr sync [push|pull]

Subcommands:

  • push - Push ADR notes to remote
  • pull - Pull ADR notes from remote
  • (no subcommand) - Both push and pull

Options:

  • --remote <name> - Remote name (default: origin)
  • --merge-strategy <strategy> - Merge strategy for conflicts (union, ours, theirs)

Examples:

# Full sync
git adr sync

# Push only
git adr sync push

# Pull with specific strategy
git adr sync pull --merge-strategy theirs

Analytics Commands

git adr stats

Show quick ADR statistics.

git adr stats

Output includes:

  • Total number of ADRs
  • Count by status
  • Count by tags
  • Recent activity

git adr report

Generate a detailed analytics report.

git adr report [options]

Options:

  • --format <format> - Output format (markdown, html, json)
  • --output <path> - Write to file

Example:

git adr report --format html --output adr-report.html

git adr metrics

Export metrics for dashboards.

git adr metrics [options]

Options:

  • --format <format> - Output format (json, prometheus)

Export/Import Commands

git adr export

Export ADRs to files.

git adr export [options]

Options:

  • --output <path> - Output directory (default: ./adrs)
  • --format <format> - File format (markdown, json, html, docx)
  • --status <status> - Only export specific status

Examples:

# Export all as markdown
git adr export --output ./docs/adrs

# Export as DOCX (requires export extra)
git adr export --format docx --output ./exports

git adr import

Import ADRs from file-based storage.

git adr import <path>

Options:

  • --pattern <glob> - File pattern (default: *.md)
  • --skip-existing - Skip ADRs that already exist

Examples:

# Import from directory
git adr import ./legacy-adrs/

# Import with pattern
git adr import ./docs --pattern "adr-*.md"

git adr convert

Convert an ADR to a different format.

git adr convert <id> --to <format>

Example:

git adr convert 20250115-use-postgresql --to nygard

Configuration Commands

git adr config

Manage git-adr configuration.

git adr config <command> [options]

Subcommands:

  • list - List all configuration
  • get <key> - Get a specific value
  • set <key> <value> - Set a configuration value

Options:

  • --global - Use global configuration (~/.gitconfig)

Examples:

# List all settings
git adr config list

# Get a value
git adr config get adr.template

# Set a value
git adr config set adr.template madr

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

See Configuration Guide for all available options.

Team Commands

git adr onboard

Interactive onboarding wizard for new team members.

git adr onboard

What it does:

  • Shows overview of ADR system
  • Lists key accepted decisions
  • Explains team conventions
  • Offers guided tour of important ADRs

Common Workflows

Starting a New Project

git adr init
git adr new "Use git-adr for architecture decisions"
git adr sync push

Team Collaboration

# Get latest ADRs
git adr sync pull

# Create new decision
git adr new "Adopt microservices architecture"

# Share with team
git adr sync push

Linking Decisions to Implementation

# After committing your implementation
git adr link 20250115-use-postgresql abc1234

# View related commits
git adr show 20250115-use-postgresql

Superseding a Decision

# When a decision is replaced
git adr supersede 20250101-use-mysql "Migrate to PostgreSQL"

Onboarding New Team Members

# Interactive walkthrough
git adr onboard

# Or browse decisions
git adr list --status accepted

See Also

Architecture Decisions

...and 24 more

Clone this wiki locally