{"id":48582485,"url":"https://github.com/zircote/git-adr","last_synced_at":"2026-04-08T17:34:01.963Z","repository":{"id":328921824,"uuid":"1116571561","full_name":"zircote/git-adr","owner":"zircote","description":"🏛️ Architecture Decision Records in git notes - no files, no merge conflicts, linked to commits. AI-powered drafting, wiki sync, 6 templates.","archived":false,"fork":false,"pushed_at":"2026-03-30T11:36:30.000Z","size":1645,"stargazers_count":4,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-30T13:26:42.872Z","etag":null,"topics":["adr","ai","architecture-decision-records","cli","devops","documentation","git","git-notes","python","software-architecture"],"latest_commit_sha":null,"homepage":null,"language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/zircote.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":"CITATION.cff","codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":"zircote"}},"created_at":"2025-12-15T04:31:25.000Z","updated_at":"2026-03-30T11:36:28.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/zircote/git-adr","commit_stats":null,"previous_names":["zircote/git-adr"],"tags_count":16,"template":false,"template_full_name":null,"purl":"pkg:github/zircote/git-adr","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zircote%2Fgit-adr","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zircote%2Fgit-adr/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zircote%2Fgit-adr/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zircote%2Fgit-adr/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zircote","download_url":"https://codeload.github.com/zircote/git-adr/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zircote%2Fgit-adr/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31567056,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-08T14:31:17.711Z","status":"ssl_error","status_checked_at":"2026-04-08T14:31:17.202Z","response_time":54,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["adr","ai","architecture-decision-records","cli","devops","documentation","git","git-notes","python","software-architecture"],"created_at":"2026-04-08T17:34:01.133Z","updated_at":"2026-04-08T17:34:01.942Z","avatar_url":"https://github.com/zircote.png","language":"Rust","readme":"# git-adr\n\nArchitecture Decision Records (ADR) management for git repositories using git notes.\n\n[![CI](https://github.com/zircote/git-adr/actions/workflows/ci.yml/badge.svg)](https://github.com/zircote/git-adr/actions/workflows/ci.yml)\n[![Crates.io](https://img.shields.io/crates/v/git-adr.svg)](https://crates.io/crates/git-adr)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\n## Overview\n\n`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:\n\n- **Non-intrusive**: No files cluttering your repository\n- **Portable**: Travel with your git history\n- **Linkable**: Associate decisions with specific commits\n- **Searchable**: Full-text search across all decisions\n- **Syncable**: Push/pull ADRs like regular git content\n\n## Installation\n\n### Pre-built Binaries\n\nDownload from [GitHub Releases](https://github.com/zircote/git-adr/releases):\n\n| Platform | Download |\n|----------|----------|\n| macOS ARM64 (M1/M2/M3/M4) | `git-adr-aarch64-apple-darwin.tar.gz` |\n| macOS Intel | `git-adr-x86_64-apple-darwin.tar.gz` |\n| Linux x86_64 | `git-adr-x86_64-unknown-linux-gnu.tar.gz` |\n| Linux x86_64 (musl) | `git-adr-x86_64-unknown-linux-musl.tar.gz` |\n| Linux ARM64 | `git-adr-aarch64-unknown-linux-gnu.tar.gz` |\n| Windows x86_64 | `git-adr-x86_64-pc-windows-msvc.zip` |\n\n### Homebrew (macOS)\n\n```bash\nbrew tap zircote/tap\nbrew install git-adr\n```\n\n### Cargo (Rust)\n\n```bash\ncargo install git-adr\n```\n\n### With Optional Features\n\n```bash\n# AI-powered features (drafting, suggestions)\ncargo install git-adr --features ai\n\n# Wiki synchronization (GitHub/GitLab)\ncargo install git-adr --features wiki\n\n# Document export (DOCX format)\ncargo install git-adr --features export\n\n# All features\ncargo install git-adr --features all\n```\n\n### From Source\n\n```bash\ngit clone https://github.com/zircote/git-adr.git\ncd git-adr\ncargo build --release\n# Binary at target/release/git-adr\n```\n\n## Quick Start\n\n```bash\n# Initialize ADR tracking in your repository\ngit adr init\n\n# Create a new ADR (opens editor)\ngit adr new \"Use PostgreSQL for primary database\"\n\n# List all ADRs\ngit adr list\n\n# Show a specific ADR\ngit adr show ADR-0001\n\n# Search ADRs\ngit adr search \"database\"\n\n# Sync ADRs with remote\ngit adr sync --push\n```\n\n## Commands\n\n### Core Commands\n\n| Command | Description |\n|---------|-------------|\n| `git adr init` | Initialize ADR tracking in repository |\n| `git adr new \u003ctitle\u003e` | Create a new ADR |\n| `git adr list` | List all ADRs with filtering options |\n| `git adr show \u003cid\u003e` | Display an ADR with formatting |\n| `git adr edit \u003cid\u003e` | Edit an existing ADR |\n| `git adr rm \u003cid\u003e` | Remove an ADR |\n| `git adr search \u003cquery\u003e` | Full-text search across ADRs |\n| `git adr link \u003cadr-id\u003e \u003ccommit\u003e` | Associate an ADR with commits |\n| `git adr supersede \u003cold-id\u003e \u003ctitle\u003e` | Create ADR that supersedes another |\n| `git adr log` | Show git log with ADR annotations |\n\n### Artifact Management\n\n| Command | Description |\n|---------|-------------|\n| `git adr attach \u003cadr-id\u003e \u003cfile\u003e` | Attach diagram/image to an ADR |\n| `git adr artifacts \u003cadr-id\u003e` | List artifacts attached to an ADR |\n\n### Analytics \u0026 Export\n\n| Command | Description |\n|---------|-------------|\n| `git adr stats` | Quick ADR statistics summary |\n| `git adr export` | Export ADRs to files (markdown, json, html, docx) |\n| `git adr convert \u003cid\u003e` | Convert an ADR to different format |\n\n### Synchronization\n\n| Command | Description |\n|---------|-------------|\n| `git adr sync` | Sync ADRs with remote (push \u0026 fetch) |\n| `git adr sync --push` | Push ADR notes to remote only |\n| `git adr sync --pull` | Fetch ADR notes from remote only |\n\n### Configuration\n\n| Command | Description |\n|---------|-------------|\n| `git adr config list` | List all configuration |\n| `git adr config set \u003ckey\u003e \u003cvalue\u003e` | Set configuration value |\n| `git adr config get \u003ckey\u003e` | Get configuration value |\n\n## Configuration Options\n\nConfiguration is stored in git config (local or global):\n\n| Key | Description | Default |\n|-----|-------------|---------|\n| `adr.prefix` | ADR ID prefix | `ADR-` |\n| `adr.digits` | Number of digits in ADR ID | `4` |\n| `adr.template` | Default template format | `madr` |\n| `adr.format` | ADR format (nygard, madr, etc.) | `nygard` |\n\n### Examples\n\n```bash\n# Set configuration\ngit adr config set template madr\n\n# Get configuration\ngit adr config get template\n\n# List all config\ngit adr config list\n```\n\n## ADR Formats\n\ngit-adr supports multiple ADR formats:\n\n### Nygard (Default)\n\nThe original ADR format by Michael Nygard.\n\n```markdown\n# Use PostgreSQL for primary database\n\n## Status\n\nAccepted\n\n## Context\n\nWe need to choose a database...\n\n## Decision\n\nWe will use PostgreSQL...\n\n## Consequences\n\n- ACID compliance\n- Rich feature set\n```\n\n### MADR\n\nMarkdown Architectural Decision Records format.\n\n```markdown\n# Use PostgreSQL for primary database\n\n## Status\n\nAccepted\n\n## Context and Problem Statement\n\nWe need to choose a database...\n\n## Decision Drivers\n\n* Performance requirements\n* Team expertise\n\n## Considered Options\n\n* PostgreSQL\n* MySQL\n* MongoDB\n\n## Decision Outcome\n\nChosen option: \"PostgreSQL\", because...\n```\n\n### Other Formats\n\n- **Y-Statement**: Concise one-sentence decision format\n- **Alexandrian**: Pattern-based format with forces\n- **Business Case**: MBA-style with cost-benefit analysis\n\n## Git Notes Architecture\n\n`git-adr` uses git notes to store ADRs, which provides:\n\n- **No file pollution**: ADRs live in git's notes refs, not in your working tree\n- **Full git integration**: Push, pull, merge like regular git content\n- **Commit association**: Link decisions to the commits that implement them\n- **History preservation**: ADR history is preserved in git\n\nNotes are stored under:\n- `refs/notes/adr` - ADR content\n- `refs/notes/adr-index` - Search index\n- `refs/notes/adr-artifacts` - Binary attachments\n\n## AI Features (Planned)\n\n\u003e Requires installation with `--features ai`\n\u003e\n\u003e **Note:** AI features are not yet implemented in the Rust version. They are planned for a future release.\n\n## Wiki Synchronization (Planned)\n\n\u003e Requires installation with `--features wiki`\n\u003e\n\u003e **Note:** Wiki synchronization is not yet implemented in the Rust version. It is planned for a future release.\n\n## Development\n\n### Setup\n\n```bash\ngit clone https://github.com/zircote/git-adr.git\ncd git-adr\n\n# Build\ncargo build\n\n# Run tests\ncargo test\n\n# Run with all features\ncargo test --all-features\n\n# Check lints\ncargo clippy --all-targets --all-features\n\n# Format\ncargo fmt\n```\n\n### Project Structure\n\n```\nsrc/\n├── lib.rs           # Library entry point\n├── main.rs          # Binary entry point\n├── cli/             # CLI command implementations\n│   ├── mod.rs       # CLI definition\n│   ├── init.rs      # Initialize command\n│   ├── new.rs       # New ADR command\n│   └── ...          # Other commands\n├── core/            # Core business logic\n│   ├── adr.rs       # ADR data model\n│   ├── git.rs       # Git operations\n│   ├── notes.rs     # Git notes management\n│   ├── config.rs    # Configuration\n│   ├── index.rs     # Search index\n│   └── templates.rs # ADR templates\n├── ai/              # AI features (optional)\n├── wiki/            # Wiki sync (optional)\n└── export/          # Export formats (optional)\n```\n\n## Migration from v0.x (Python)\n\nVersion 1.0 is a complete rewrite in Rust. The data format (git notes) is fully compatible, so your existing ADRs will work without changes. Some CLI flags may have changed - use `git adr --help` for current options.\n\nTo access the Python version:\n\n```bash\n# Checkout the Python version\ngit checkout python-final\n\n# Or install the last Python release\npip install git-adr==0.3.0\n```\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Make your changes\n4. Run tests and linting (`cargo test \u0026\u0026 cargo clippy`)\n5. Commit your changes (`git commit -m 'Add amazing feature'`)\n6. Push to the branch (`git push origin feature/amazing-feature`)\n7. Open a Pull Request\n\n## Citing This Project\n\nIf you use `git-adr` in your research or documentation, you can cite it using GitHub's \"Cite this repository\" button, or with the following BibTeX entry:\n\n```bibtex\n@software{allen_git_adr,\n  author       = {Allen, Robert},\n  title        = {git-adr},\n  version      = {1.0.0},\n  date         = {2026-01-15},\n  url          = {https://github.com/zircote/git-adr},\n  license      = {MIT}\n}\n```\n\n## Acknowledgments\n\nThis project builds on the work of the ADR community:\n\n\u003e ADR organization. *MADR - Markdown Architectural Decision Records*. https://github.com/adr/madr\n\n\u003e Nat Pryce. *adr-tools*. https://github.com/npryce/adr-tools\n\n## License\n\nMIT License - see [LICENSE](LICENSE) for details.\n","funding_links":["https://github.com/sponsors/zircote"],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzircote%2Fgit-adr","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzircote%2Fgit-adr","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzircote%2Fgit-adr/lists"}