-
-
Notifications
You must be signed in to change notification settings - Fork 0
Configuration Guide
Robert Allen edited this page Dec 15, 2025
·
1 revision
This document provides a comprehensive reference for all configuration options available in git-adr.
git-adr stores configuration in git config (local or global). All keys are prefixed with adr..
# View all git-adr configuration
git adr config list
# Get a specific value
git adr config get adr.template
# Set a value (local to repo)
git adr config set adr.template madr
# Set a value (global)
git adr config set --global adr.template madrStored in .git/config and applies only to the current repository.
git adr config set adr.template nygardStored in ~/.gitconfig and applies to all repositories.
git adr config set --global adr.editor "code --wait"-
Local (
.git/config) - highest priority -
Global (
~/.gitconfig) - Default values - lowest priority
git config --show-origin adr.template# Remove local setting
git config --unset adr.template
# Remove global setting
git config --global --unset adr.ai.provider| Key | Type | Default | Description |
|---|---|---|---|
adr.namespace |
string | adr |
Notes namespace for ADRs |
adr.artifacts_namespace |
string | adr-artifacts |
Notes namespace for artifacts |
adr.template |
string | madr |
Default ADR template format |
adr.editor |
string | (system) | Editor for ADR editing |
adr.artifact_warn_size |
int | 1048576 |
Warning threshold (bytes) |
adr.artifact_max_size |
int | 10485760 |
Maximum artifact size (bytes) |
adr.sync.auto_push |
bool | false |
Auto-push after changes |
adr.sync.auto_pull |
bool | true |
Auto-pull before reads |
adr.sync.merge_strategy |
string | union |
Conflict resolution strategy |
adr.ai.provider |
string | (none) | AI service provider |
adr.ai.model |
string | (none) | AI model name |
adr.ai.temperature |
float | 0.7 |
AI randomness (0.0-1.0) |
adr.wiki.platform |
string | auto |
Wiki platform |
adr.wiki.auto_sync |
bool | false |
Auto-sync to wiki |
The git notes namespace used to store ADR content.
| Property | Value |
|---|---|
| Type | string |
| Default | adr |
ADRs are stored under refs/notes/<namespace>. Changing this allows multiple independent ADR systems in the same repository.
# Use default (refs/notes/adr)
git adr config set adr.namespace adr
# Use custom namespace for a project
git adr config set adr.namespace project-decisionsNote: Changing the namespace after ADRs exist will make existing ADRs invisible.
The namespace for storing attached files (diagrams, images).
| Property | Value |
|---|---|
| Type | string |
| Default | adr-artifacts |
git adr config set adr.artifacts_namespace adr-artifactsThe default ADR template format.
| Property | Value |
|---|---|
| Type | string |
| Default | madr |
| Valid Values |
madr, nygard, y-statement, alexandrian, business, planguage
|
See ADR Templates for detailed template descriptions.
| Template | Description | Best For |
|---|---|---|
madr |
Full template with options analysis | Complex decisions |
nygard |
Original minimal format | Quick decisions |
y-statement |
Single-sentence format | Brief records |
alexandrian |
Pattern-language inspired | Design patterns |
business |
Extended business justification | Stakeholder approval |
planguage |
Quality-focused measurable | Performance/SLA decisions |
# Use MADR (default)
git adr config set adr.template madr
# Use minimal Nygard format
git adr config set adr.template nygardThe editor command used when editing ADRs.
| Property | Value |
|---|---|
| Type | string |
| Default |
$EDITOR, $VISUAL, or fallback chain |
If not set, git-adr follows the standard editor resolution:
-
$EDITORenvironment variable -
$VISUALenvironment variable git config core.editor- Fallback chain:
vim,vi,nano,notepad(Windows)
# VS Code (wait for editor to close)
git adr config set --global adr.editor "code --wait"
# Sublime Text
git adr config set --global adr.editor "subl -w"
# vim
git adr config set --global adr.editor vim
# nano
git adr config set --global adr.editor nano
# IntelliJ IDEA
git adr config set --global adr.editor "idea --wait"
# Emacs
git adr config set --global adr.editor "emacsclient -t"Tip: For GUI editors, use the --wait or -w flag so git-adr waits for the editor to close.
Size threshold at which git-adr warns before attaching a file.
| Property | Value |
|---|---|
| Type | integer (bytes) |
| Default |
1048576 (1 MB) |
# Set warning at 500 KB
git adr config set adr.artifact_warn_size 512000
# Set warning at 2 MB
git adr config set adr.artifact_warn_size 2097152Maximum allowed file size for artifacts.
| Property | Value |
|---|---|
| Type | integer (bytes) |
| Default |
10485760 (10 MB) |
# Set max to 5 MB
git adr config set adr.artifact_max_size 5242880
# Set max to 50 MB
git adr config set adr.artifact_max_size 52428800Size references:
- 1 MB = 1,048,576 bytes
- 5 MB = 5,242,880 bytes
- 10 MB = 10,485,760 bytes
- 50 MB = 52,428,800 bytes
Automatically push notes after creating or editing ADRs.
| Property | Value |
|---|---|
| Type | boolean |
| Default | false |
# Enable automatic pushing
git adr config set adr.sync.auto_push trueAutomatically pull notes before listing or showing ADRs.
| Property | Value |
|---|---|
| Type | boolean |
| Default | true |
# Disable for offline work
git adr config set adr.sync.auto_pull falseStrategy for resolving conflicts when pulling notes.
| Property | Value |
|---|---|
| Type | string |
| Default | union |
| Valid Values |
union, ours, theirs, cat_sort_uniq
|
| Strategy | Description |
|---|---|
union |
Combines both versions (default) |
ours |
Keeps local version |
theirs |
Keeps remote version |
cat_sort_uniq |
Concatenates, sorts, removes duplicates |
# Prefer local changes
git adr config set adr.sync.merge_strategy ours
# Prefer remote changes
git adr config set adr.sync.merge_strategy theirsThe AI service provider for AI-assisted features.
| Property | Value |
|---|---|
| Type | string |
| Default | (none) |
| Valid Values |
openai, anthropic, google, bedrock, azure, ollama, openrouter
|
| Provider | API Key Variable |
|---|---|
openai |
OPENAI_API_KEY |
anthropic |
ANTHROPIC_API_KEY |
google |
GOOGLE_API_KEY |
bedrock |
AWS credentials |
azure |
AZURE_OPENAI_API_KEY |
ollama |
(none - local) |
openrouter |
OPENROUTER_API_KEY |
# Use OpenAI
git adr config set adr.ai.provider openai
export OPENAI_API_KEY="sk-..."
# Use Anthropic Claude
git adr config set adr.ai.provider anthropic
export ANTHROPIC_API_KEY="sk-ant-..."
# Use local Ollama (no API key needed)
git adr config set adr.ai.provider ollamaSee AI Features for more details.
The specific AI model to use.
| Property | Value |
|---|---|
| Type | string |
| Default | (provider default) |
| Provider | Example Models |
|---|---|
openai |
gpt-4, gpt-4-turbo, gpt-3.5-turbo
|
anthropic |
claude-3-opus-20240229, claude-3-sonnet-20240229
|
google |
gemini-pro, gemini-1.5-pro
|
ollama |
llama2, mistral, codellama
|
git adr config set adr.ai.model gpt-4-turboControls randomness of AI responses.
| Property | Value |
|---|---|
| Type | float |
| Default | 0.7 |
| Range |
0.0 to 1.0
|
| Temperature | Behavior |
|---|---|
0.0 - 0.3
|
Focused, deterministic |
0.7 |
Balanced (default) |
0.9 - 1.0
|
Creative, varied |
# More focused output
git adr config set adr.ai.temperature 0.3
# More creative output
git adr config set adr.ai.temperature 0.9The wiki platform for exporting ADRs.
| Property | Value |
|---|---|
| Type | string |
| Default | auto |
| Valid Values |
github, gitlab, auto
|
git adr config set adr.wiki.platform githubAutomatically sync ADRs to wiki after modifications.
| Property | Value |
|---|---|
| Type | boolean |
| Default | false |
git adr config set adr.wiki.auto_sync trueSee Wiki Integration for setup details.
git adr init
# Defaults work for most casesgit adr config set adr.ai.provider openai
git adr config set adr.ai.model gpt-4-turbo
export OPENAI_API_KEY="sk-..."git adr config set adr.ai.provider anthropic
git adr config set adr.ai.model claude-3-opus-20240229
export ANTHROPIC_API_KEY="sk-ant-..."git adr config set adr.ai.provider ollama
git adr config set adr.ai.model mistral
# Ensure Ollama is running: ollama servegit adr config set adr.sync.auto_pull true
git adr config set adr.sync.auto_push true
git adr config set adr.sync.merge_strategy uniongit adr config set adr.sync.auto_pull false
git adr config set adr.sync.auto_push falsegit adr config set adr.template nygard
git adr config set adr.ai.temperature 0.3git adr config set adr.artifact_warn_size 5242880 # 5 MB
git adr config set adr.artifact_max_size 52428800 # 50 MB# Global preferences
git config --global adr.editor "code --wait"
git config --global adr.ai.provider anthropic
# Project A: Formal decisions
cd /path/to/project-a
git adr config set adr.template business
# Project B: Quick technical decisions
cd /path/to/project-b
git adr config set adr.template nygard- Commands Reference - Complete command documentation
- ADR Templates - Template format details
- AI Features - AI configuration and usage
- Wiki Integration - Wiki sync configuration
Architecture Decisions
...and 24 more