Skip to content

Getting Started

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

Getting Started with git-adr

This guide walks you through installing git-adr, creating your first ADR, and understanding the basics of Architecture Decision Records.

Installation

Prerequisites

  • Python 3.11 or higher
  • Git installed and available in your PATH

Option 1: Homebrew (macOS - Recommended)

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

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

Option 2: pip

pip install git-adr

Option 3: uv (Fast Python Package Manager)

uv tool install git-adr

Install 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]"

Verify Installation

git-adr --version
# or
git adr --version

Initialize ADR Tracking

Navigate to your git repository and initialize ADR tracking:

cd your-project
git adr init

This command:

  1. Creates the first ADR documenting your decision to use ADRs
  2. Configures git to sync notes with remote repositories
  3. Sets up the required notes namespaces

You can verify the setup with:

git adr list

You should see one ADR: "Use Architecture Decision Records".

Create Your First ADR

Create an ADR using the new command:

git adr new "Use PostgreSQL for primary database"

This opens your default editor with a template. Fill in the sections:

---
id: 20250115-use-postgresql
title: Use PostgreSQL for primary database
date: 2025-01-15
status: proposed
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

Save and close the editor. Your ADR is now stored in git notes.

View Your ADRs

List All ADRs

git adr list

Output:

ID                              Status    Date        Title
20250115-use-postgresql         proposed  2025-01-15  Use PostgreSQL for primary database
00000000-use-adrs               accepted  2025-01-15  Use Architecture Decision Records

Filter by Status

git adr list --status accepted
git adr list --status proposed
git adr list --status deprecated

Filter by Tags

git adr list --tags database
git adr list --tags infrastructure,database

Show a Specific ADR

git adr show 20250115-use-postgresql

Search ADRs

Search across all ADR content:

git adr search "database"
git adr search "PostgreSQL"

Edit an ADR

Edit an existing ADR:

git adr edit 20250115-use-postgresql

This opens the ADR in your editor. After saving, the changes are stored in git notes.

Change ADR Status

To accept a proposed ADR:

git adr edit 20250115-use-postgresql
# Change status: proposed -> status: accepted

Link ADRs to Commits

After implementing a decision, link the ADR to the implementing commit:

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

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

View commits with ADR annotations:

git adr log

Sync with Remote

Push your ADRs to share with your team:

git adr sync push

Pull ADRs created by others:

git adr sync pull

Or sync both ways:

git adr sync

Supersede a Decision

When decisions change, create a superseding ADR:

git adr supersede 20250115-use-postgresql "Migrate to CockroachDB for global distribution"

This automatically:

  1. Creates a new ADR with a reference to the old one
  2. Updates the old ADR's status to "superseded"
  3. Links the two ADRs together

Understanding ADRs

What is an Architecture Decision Record?

An ADR is a short document that captures a significant decision made during a project, along with the context and consequences of that decision.

Each ADR answers three fundamental questions:

  1. What was the situation? (Context)
  2. What did we decide? (Decision)
  3. What happens because of this decision? (Consequences)

Why Document Decisions?

Onboarding New Team Members

When a new developer joins, they can read ADRs to understand why things are built the way they are. Instead of "That's just how we do things here," you can point to ADR-007 where the team documented the trade-offs.

Understanding Historical Context

Software is full of decisions that seem strange in hindsight. ADRs preserve the why behind decisions, transforming "Who wrote this garbage?" into "Oh, this was a deliberate trade-off."

Preventing Decision Repetition

When someone proposes an idea that was already discussed, you can reference the existing ADR rather than relitigating the decision from scratch.

When to Write an ADR

Write an ADR when the decision is significant, structural, or hard to reverse:

  • Technology choices (databases, frameworks, languages)
  • Architecture patterns (monolith vs microservices, REST vs GraphQL)
  • Design decisions (authentication strategy, caching approach)
  • Trade-off decisions (build vs buy, performance vs simplicity)

Skip ADRs for:

  • Trivial choices (variable naming, code formatting)
  • Easily reversible decisions (which npm package to use)
  • Temporary solutions you plan to replace soon

ADR Lifecycle

Proposed --> Accepted --> Superseded
         \-> Rejected

Accepted --> Deprecated (no replacement)
  • Proposed - Under discussion, not yet approved
  • Accepted - Team has agreed, this is the official approach
  • Rejected - Proposed but not accepted (kept for history)
  • Deprecated - No longer relevant or recommended
  • Superseded - Replaced by a newer decision

Next Steps

Architecture Decisions

...and 24 more

Clone this wiki locally