Skip to content

FAQ

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

Frequently Asked Questions

Common questions about git-adr and Architecture Decision Records.

General Questions

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)

How is git-adr different from file-based ADR tools?

Traditional ADR tools (like adr-tools) store decisions as files in your repository. git-adr stores them in git notes, which provides several advantages:

Feature File-based git-adr
Repository clutter Files visible in tree No files in working tree
Merge conflicts Possible on sequential numbering Rare (content-based IDs)
Commit association Manual Built-in linking
Search Grep on files Native search command
Portable Part of repo Part of git history

Do ADRs work with all git hosting platforms?

Yes. git notes are a standard git feature supported by:

  • GitHub
  • GitLab
  • Bitbucket
  • Azure DevOps
  • Self-hosted git servers

The wiki sync feature specifically supports GitHub and GitLab wikis.

Installation & Setup

What Python version do I need?

Python 3.11 or higher is required. Check your version:

python --version

How do I install git-adr?

# Basic installation
pip install git-adr

# With AI features
pip install "git-adr[ai]"

# With wiki sync
pip install "git-adr[wiki]"

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

For macOS, Homebrew is recommended:

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

Why do I need to run git adr init?

git adr init configures your repository for ADR tracking:

  1. Creates the initial ADR documenting use of ADRs
  2. Configures git to sync notes with remote
  3. Sets up rebase-safe note handling

Without init, notes won't sync to/from remote automatically.

Can I use git-adr in a repository that already has file-based ADRs?

Yes! Use the import command:

git adr import ./docs/architecture/decisions/

This imports existing ADRs into git notes. The original files remain unchanged.

Daily Usage

How do I create an ADR?

git adr new "Use PostgreSQL for primary database"

This opens your editor with a template. Fill in the sections and save.

How do I list all ADRs?

# List all
git adr list

# Filter by status
git adr list --status accepted

# Filter by tags
git adr list --tags database

How do I edit an existing ADR?

git adr edit <adr-id>

Example:

git adr edit 20250115-use-postgresql

How do I change an ADR's status?

Either edit the ADR and change the status field:

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

Or use the status flag:

git adr edit 20250115-use-postgresql --status accepted

How do I supersede a decision?

When replacing a decision with a new one:

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

This automatically:

  • Creates a new ADR
  • Marks the old ADR as superseded
  • Links the two ADRs

How do I delete an ADR?

git adr rm <adr-id>

# Skip confirmation
git adr rm <adr-id> --force

Note: This removes the ADR from git notes. Recovery is possible via git reflog but requires git expertise.

Team Collaboration

How do I share ADRs with my team?

# Push your ADRs
git adr sync push

# Pull team's ADRs
git adr sync pull

# Both at once
git adr sync

Why aren't my ADRs showing up on the remote?

Git notes are not pushed by default. Either:

  1. Use git adr sync: git adr sync push

  2. Check init was run: git adr init configures automatic sync

  3. Manual configuration:

    git config --add remote.origin.fetch '+refs/notes/*:refs/notes/*'
git config --add remote.origin.push 'refs/notes/*'

How do I resolve conflicts when syncing?

git-adr uses union merge by default, which combines conflicting changes. If you need different behavior:

# Prefer local changes
git adr sync pull --merge-strategy ours

# Prefer remote changes
git adr sync pull --merge-strategy theirs

Can team members use different editors?

Yes. Each user configures their own editor:

git adr config set --global adr.editor "code --wait"

This is stored in the user's global git config, not the repository.

Templates & Formats

What template should I use?

Template Best For
MADR (default) Most decisions - structured option analysis
Nygard Quick, simple decisions
Y-Statement Rapid documentation
Business Decisions needing stakeholder approval
Planguage Performance/quality targets
Alexandrian Design patterns

See ADR Templates for detailed comparisons.

How do I change the default template?

# Repository-wide
git adr config set adr.template nygard

# Single ADR override
git adr new "My Decision" --template business

Can I create custom templates?

Yes. Place template files in:

  • .git-adr/templates/your-format.md (repository)
  • ~/.config/git-adr/templates/your-format.md (user)

See ADR Templates#custom-templates for details.

AI Features

Do I need AI features?

No. AI features are optional and enhance the experience but aren't required. git-adr works fully without them.

Which AI provider should I use?

Provider Best For
OpenAI Highest quality, widely supported
Anthropic Strong alternative, good for technical content
Ollama Local/private, no API costs
Google Good integration if already using GCP

How do I keep my ADRs private when using AI?

Use Ollama for local processing:

git adr config set adr.ai.provider ollama
git adr config set adr.ai.model mistral
ollama serve  # Start local server

No data leaves your machine.

The AI draft is wrong. What do I do?

AI drafts are starting points, not final documents. Always:

  1. Review the generated content
  2. Edit for accuracy
  3. Add specific details the AI doesn't know
  4. Remove any hallucinated content

Troubleshooting

"Command not found: git-adr"

The installation may not be in your PATH. Try:

# Check if installed
pip show git-adr

# Use full path
python -m git_adr --help

# Add to PATH (if using pip --user)
export PATH="$HOME/.local/bin:$PATH"

"No ADRs found"

Either:

  1. No ADRs have been created: git adr init
  2. Notes haven't been synced: git adr sync pull
  3. Using wrong namespace: git adr config get adr.namespace

"Editor not launching"

Set your editor explicitly:

git adr config set --global adr.editor vim

# For GUI editors, use --wait flag
git adr config set --global adr.editor "code --wait"

"Push/pull failed"

Check:

  1. Remote is configured: git remote -v
  2. You have push access to the remote
  3. Notes refs are configured: git config --get-all remote.origin.fetch

"ADRs lost after rebase"

If notes were lost, check reflog:

git notes --ref=adr log

To prevent future loss, ensure git adr init was run, which configures:

  • notes.rewriteRef
  • notes.rewrite.rebase

Best Practices

When should I write an ADR?

Write an ADR when the decision is:

  • Significant - Affects architecture or design
  • Structural - Changes how components interact
  • Hard to reverse - Would take significant effort to undo

Don't write ADRs for:

  • Code style choices (use linters)
  • Library version bumps
  • Bug fixes
  • Trivial implementation details

How long should an ADR be?

Typically 1-2 pages. If longer, consider:

  • Splitting into multiple decisions
  • Linking to separate design documents
  • Using a more concise template

Should I update old ADRs?

Generally no. ADRs are point-in-time records. Instead:

  • Decision changed? Create a superseding ADR
  • Decision no longer relevant? Mark as deprecated
  • Minor typo? Fix it, but don't change substance

How often should I sync?

Recommended sync points:

  • After creating/accepting an ADR
  • Before team meetings
  • Before and after releases
  • When starting work after a break

Migration & Import

Can I migrate from adr-tools?

Yes. adr-tools stores ADRs as numbered markdown files:

git adr import ./doc/adr/ --pattern "*.md"

What formats can be imported?

Any markdown file with standard ADR structure. The import command attempts to parse:

  • Title from heading
  • Status from status section
  • Date from filename or content
  • Other sections as-is

Can I export back to files?

Yes:

git adr export --output ./docs/adrs --format markdown

See Also

Architecture Decisions

...and 24 more

Clone this wiki locally