feat!: Rewrite git-adr in Rust by zircote · Pull Request #54 · zircote/git-adr

zircote · 2026-01-15T19:40:54Z

Summary

Complete rewrite of git-adr from Python to Rust for version 1.0.0.

Key Changes

Zero Runtime Dependencies: Single static binary, no Python required
Performance: Significantly faster startup and execution
Memory Safety: Rust's ownership model ensures safe memory handling
Cross-Platform: Pre-built binaries for macOS, Linux, and Windows

Features Included

Core Commands

init, new, list, show, edit, rm - ADR management
search - Full-text search across ADRs
sync - Push/pull ADR notes with remotes
config - Git config-based settings
link - Associate ADRs with commits
supersede, log, stats, convert, attach, artifacts

ADR Formats

Nygard (default), MADR, Structured MADR
Y-Statement, Alexandrian, Business Case

Optional Features (via `--features`)

ai - AI-powered ADR assistance (langchain-rust)
wiki - GitHub/GitLab wiki sync
export - DOCX export

Migration Path

The git notes data format is fully compatible. Existing ADRs work without changes.

To access the Python version:

git checkout python-final
pip install git-adr==0.3.0

Test Plan

All unit tests passing (cargo test)
Clippy lints passing (cargo clippy -- -D warnings)
Code formatted (cargo fmt -- --check)
CLI help and version working
Optional features compile correctly

Breaking Changes

This is a major version bump (0.3.0 -> 1.0.0) due to:

Complete language rewrite (Python -> Rust)
Some CLI flags may differ slightly (use --help for current options)

This workplan guides the complete rewrite of git-adr from Python to Rust while preserving repository identity, git history, and documentation.

BREAKING CHANGE: Complete removal of Python codebase in preparation for Rust rewrite. The final Python version is preserved at tag 'python-final' for historical reference and can be accessed via: git checkout python-final This commit marks the official transition point from Python to Rust. All Python source files, configuration, dependencies, and tooling have been removed to ensure a clean slate for the Rust implementation.

BREAKING CHANGE: Complete rewrite of git-adr from Python to Rust. - Single static binary with zero runtime dependencies - Significantly faster startup and execution - Memory-safe implementation with strong type guarantees - Cross-compilation support for all major platforms Features: - Core ADR management (init, new, list, show, edit, rm, search, sync) - Configuration management via git config - Link ADRs to commits - Multiple ADR formats (Nygard, MADR, Y-Statement, Alexandrian, Business Case) - Full-text search and indexing Optional features (compiled in via --features): - ai: AI-powered ADR assistance via langchain-rust - wiki: GitHub/GitLab wiki synchronization - export: DOCX document export The git notes data format is fully compatible - existing ADRs work without changes. To access the Python version: git checkout python-final pip install git-adr==0.3.0

Copilot

Pull request overview

This PR represents a complete rewrite of git-adr from Python to Rust for version 1.0.0, aimed at eliminating runtime dependencies and providing performance improvements through a single static binary. The rewrite maintains full compatibility with the existing git notes data format while transitioning the entire codebase to Rust's memory-safe infrastructure.

Changes:

Complete removal of Python implementation (CLI, core libraries, AI services, commands)
Introduction of Rust implementation with new export module (DOCX, HTML, JSON)
Migration from Python's git subprocess wrapper to Rust's native git integration
Removal of all Python dependencies and testing infrastructure

Reviewed changes

Copilot reviewed 95 out of 188 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
`src/git_adr/core/index.py`	Removed Python index management for ADR search and filtering
`src/git_adr/core/git.py`	Removed Python git subprocess wrapper
`src/git_adr/core/gh_client.py`	Removed GitHub CLI integration client
`src/git_adr/core/config.py`	Removed Python configuration management system
`src/git_adr/core/adr.py`	Removed Python ADR model and parsing logic
`src/git_adr/core/__init__.py`	Removed Python core module exports
`src/git_adr/commands/*.py`	Removed all Python CLI command implementations
`src/git_adr/ai/*.py`	Removed AI service integration with LangChain
`src/git_adr/__init__.py`	Removed Python package initialization
`src/export/*.rs`	Added Rust export functionality for DOCX, HTML, JSON formats
`src/core/notes.rs`	Added Rust notes management implementation

Copilot · 2026-01-15T19:42:32Z

+            commit: &adr.commit,
+            title: &adr.frontmatter.title,
+            status: adr.frontmatter.status.to_string(),
+            date: adr.frontmatter.date.map(|d| d.to_rfc3339()),


The to_rfc3339() method is being called on a date, but this method typically exists on DateTime types, not simple dates. If adr.frontmatter.date is a chrono::NaiveDate or similar date-only type, this will not compile. Consider using .format(\"%Y-%m-%d\").to_string() for date serialization or converting to a DateTime first if timestamps are needed.

Suggested change

date: adr.frontmatter.date.map(|d| d.to_rfc3339()),

date: adr

.frontmatter

.date

.map(|d| d.format("%Y-%m-%d").to_string()),

Copilot · 2026-01-15T19:42:32Z

+        // Simple markdown to HTML conversion
+        // TODO: Use a proper markdown parser


The inline markdown-to-HTML conversion is incomplete and will not handle common markdown features like bold, italic, links, code blocks, or nested lists. This could result in broken or poorly formatted HTML output. Consider integrating a proper markdown parser library like pulldown-cmark or documenting this limitation in the user-facing documentation.

Copilot · 2026-01-15T19:42:32Z

+        // TODO: Implement using docx-rs when feature is enabled
+        let _ = adr;
+        let _ = path;
+        Err(Error::ExportError {
+            message: "DOCX export not yet implemented".to_string(),
+        })


The DOCX export functionality is not implemented but is exposed as a supported format in ExportFormat enum. This creates a misleading API where users can specify DOCX format but will always receive an error. Either implement this feature before release, remove DOCX from ExportFormat, or add runtime feature detection to prevent selecting unavailable formats.

Copilot · 2026-01-15T19:42:33Z

+        // TODO: Try to find ID in frontmatter or content
+        // For now, generate from commit short hash
+        let short = self.git.short_hash(commit)?;
+        Ok(format!("{}{}", self.config.prefix, short))


The ID extraction is incomplete and falls back to generating IDs from commit hashes. This breaks compatibility with the Python version which used date-based IDs (format: YYYYMMDD-slug). ADRs migrated from the Python version will not be recognized by their original IDs, breaking the stated "fully compatible" data format claim in the PR description.

zircote · 2026-01-15T19:59:32Z

Code review

Found 3 issues:

XSS vulnerability in HTML export - User-controlled content (title, status, tags) is inserted into HTML without escaping. The Python version fixed this in commit 5fb91a9 using html.escape().

git-adr/src/export/html.rs

Lines 113 to 121 in 67eb960

    
           } else { 
        
               let tags: Vec<String> = adr 
        
                   .frontmatter 
        
                   .tags 
        
                   .iter() 
        
                   .map(|t| format!("<span class=\"tag\">{t}</span>")) 
        
                   .collect(); 
        
               format!("<div class=\"tags\">{}</div>", tags.join("")) 
        
           };

Empty repository handling bug in IndexManager - The get_index_commit() method will fail in fresh repositories with no commits because git rev-list --max-parents=0 HEAD fails before the empty-string check is reached. The fallback self.git.head() code path is unreachable.

git-adr/src/core/index.rs

Lines 181 to 195 in 67eb960

    
               /// Get the commit hash used to store the index. 
        
               fn get_index_commit(&self) -> Result<String, Error> { 
        
                   // Use the first commit in the repository 
        
                   let output = self 
        
                       .git 
        
                       .run_output(&["rev-list", "--max-parents=0", "HEAD"])?; 
        
                   let first_line = output.lines().next().unwrap_or("").trim(); 
        
                   if first_line.is_empty() { 
        
                       // No commits yet, use HEAD 
        
                       self.git.head() 
        
                   } else { 
        
                       Ok(first_line.to_string()) 
        
                   } 
        
               }

Missing config_unset method - The Git struct has config_get() and config_set() but no config_unset() method. The Python version needed config_unset --unset-all for properly clearing multi-valued config keys during init --force. This will block full implementation of the init command.

git-adr/src/core/git.rs

Lines 163 to 187 in 67eb960

    
               /// Get a git config value. 
        
               /// 
        
               /// # Errors 
        
               /// 
        
               /// Returns an error if the config key doesn't exist. 
        
               pub fn config_get(&self, key: &str) -> Result<Option<String>, Error> { 
        
                   let output = self.run(&["config", "--get", key])?; 
        
                   if output.status.success() { 
        
                       Ok(Some( 
        
                           String::from_utf8_lossy(&output.stdout).trim().to_string(), 
        
                       )) 
        
                   } else { 
        
                       Ok(None) 
        
                   } 
        
               } 
        
               /// Set a git config value. 
        
               /// 
        
               /// # Errors 
        
               /// 
        
               /// Returns an error if the config cannot be set. 
        
               pub fn config_set(&self, key: &str, value: &str) -> Result<(), Error> { 
        
                   self.run_silent(&["config", key, value]) 
        
               }

🤖 Generated with Claude Code

_{- If this code review was useful, please react with 👍. Otherwise, react with 👎.}

Security fixes: - Fix XSS vulnerability in HTML export by escaping all user-controlled content (title, status, tags, body) using html_escape function Bug fixes: - Fix empty repository handling in IndexManager.get_index_commit() - Now properly handles repos with no commits by catching the error - Falls back to git's empty tree hash for truly empty repos - Add config_unset() method to Git struct for proper init --force support - Supports --unset-all for multi-valued config keys - Gracefully handles non-existent keys (exit code 5) Build system: - Rewrite Makefile for Rust build system (was Python-centric) - cargo build/test/clippy/fmt commands - Version management from Cargo.toml - Install/uninstall targets for release binary - make ci mirrors GitHub Actions checks

Copilot

Pull request overview

Copilot reviewed 95 out of 189 changed files in this pull request and generated 1 comment.

Copilot · 2026-01-15T20:07:12Z

+        // TODO: Implement using docx-rs when feature is enabled
+        let _ = adr;
+        let _ = path;
+        Err(Error::ExportError {
+            message: "DOCX export not yet implemented".to_string(),
+        })


The TODO comment indicates incomplete implementation. Consider documenting the expected timeline for DOCX export implementation or noting that this is a placeholder for a future feature, to set clear expectations for users who may attempt to use this export format.

- Rewrite SHELL_COMPLETION.md (completion command not yet implemented) - Fix SDLC_INTEGRATION.md CI workflows to use binary download instead of pip - Fix HOOKS_GUIDE.md to remove non-existent options - Update command references with correct flags and options - Archive obsolete Python-era specs (PyInstaller, migration workplan) - Move git-adr-cli spec to completed/ - Update man pages with accurate command syntax - Fix sync command syntax throughout (--push/--pull flags)

- Run cargo fmt to fix formatting issues - Add Unicode-3.0 license to deny.toml (used by icu_* crates) - Ignore unmaintained crate advisories from langchain-rust deps - Fix Windows compatibility in hooks.rs (cfg(unix) for chmod)

Copilot

Pull request overview

Copilot reviewed 89 out of 248 changed files in this pull request and generated no new comments.

- Update RUSTSEC advisory IDs to correct 2025 versions - Add clippy::too_many_lines allow for generate_html_report - Update Makefile ci target to include deny and docs-check for parity with GitHub Actions

- Update rust-version to 1.85 (required for edition2024 dependencies) - Update CI MSRV job to use Rust 1.85 - Fix clippy unnecessary_map_or warnings by using is_none_or - Simplify deny.toml advisory ignores

Copilot

Pull request overview

Copilot reviewed 89 out of 248 changed files in this pull request and generated no new comments.

- Add RUSTSEC-2025-0012 (backoff unmaintained) - Add RUSTSEC-2025-0057 (fxhash unmaintained) - Add RUSTSEC-2025-0134 (rustls-pemfile unmaintained) These are required when building with --all-features which includes the ai feature.

…in permissions Co-authored-by: Copilot Autofix powered by AI <62310815+github-advanced-security[bot]@users.noreply.github.com>

Copilot

Pull request overview

Copilot reviewed 89 out of 248 changed files in this pull request and generated no new comments.

zircote · 2026-01-16T03:13:29Z

@copilot open a new pull request to apply changes based on the comments in this thread

Copilot · 2026-01-16T03:13:40Z

@zircote I've opened a new pull request, #55, to work on those changes. Once the pull request is ready, I'll request review from you.

zircote · 2026-01-16T03:16:43Z

Code review

Found 3 issues:

XSS vulnerability in HTML export - User-controlled content (title, status, tags) is inserted into HTML without escaping. The Python version fixed this in commit 5fb91a9 using html.escape().

git-adr/src/export/html.rs

Lines 113 to 121 in 67eb960

} else {

let tags: Vec<String> = adr

.frontmatter

.tags

.iter()

.map(|t| format!("<span class=\"tag\">{t}</span>"))

.collect();

format!("<div class=\"tags\">{}</div>", tags.join(""))

};

Empty repository handling bug in IndexManager - The get_index_commit() method will fail in fresh repositories with no commits because git rev-list --max-parents=0 HEAD fails before the empty-string check is reached. The fallback self.git.head() code path is unreachable.

git-adr/src/core/index.rs

Lines 181 to 195 in 67eb960

/// Get the commit hash used to store the index.

fn get_index_commit(&self) -> Result<String, Error> {

// Use the first commit in the repository

let output = self

.git

.run_output(&["rev-list", "--max-parents=0", "HEAD"])?;

let first_line = output.lines().next().unwrap_or("").trim();

if first_line.is_empty() {

// No commits yet, use HEAD

self.git.head()

} else {

Ok(first_line.to_string())

}

}

Missing config_unset method - The Git struct has config_get() and config_set() but no config_unset() method. The Python version needed config_unset --unset-all for properly clearing multi-valued config keys during init --force. This will block full implementation of the init command.

git-adr/src/core/git.rs

Lines 163 to 187 in 67eb960

/// Get a git config value.

///

/// # Errors

///

/// Returns an error if the config key doesn't exist.

pub fn config_get(&self, key: &str) -> Result<Option<String>, Error> {

let output = self.run(&["config", "--get", key])?;

if output.status.success() {

Ok(Some(

String::from_utf8_lossy(&output.stdout).trim().to_string(),

))

} else {

Ok(None)

}

}

/// Set a git config value.

///

/// # Errors

///

/// Returns an error if the config cannot be set.

pub fn config_set(&self, key: &str, value: &str) -> Result<(), Error> {

self.run_silent(&["config", key, value])

}

🤖 Generated with Claude Code

If this code review was useful, please react with 👍. Otherwise, react with 👎.

@copilot

Copilot · 2026-01-16T03:16:52Z

@zircote I've opened a new pull request, #56, to work on those changes. Once the pull request is ready, I'll request review from you.

Security fixes: - Fix XSS vulnerability in HTML export by escaping all user-controlled content (title, status, tags, body) using html_escape function Bug fixes: - Fix empty repository handling in IndexManager.get_index_commit() - Now properly handles repos with no commits by catching the error - Falls back to git's empty tree hash for truly empty repos - Add config_unset() method to Git struct for proper init --force support - Supports --unset-all for multi-valued config keys - Gracefully handles non-existent keys (exit code 5) Build system: - Rewrite Makefile for Rust build system (was Python-centric) - cargo build/test/clippy/fmt commands - Version management from Cargo.toml - Install/uninstall targets for release binary - make ci mirrors GitHub Actions checks

zircote added 3 commits January 15, 2026 14:15

docs: add Python to Rust migration workplan

6b37aa4

This workplan guides the complete rewrite of git-adr from Python to Rust while preserving repository identity, git history, and documentation.

Copilot AI review requested due to automatic review settings January 15, 2026 19:40

github-advanced-security AI found potential problems Jan 15, 2026

View reviewed changes

Copilot AI reviewed Jan 15, 2026

View reviewed changes

zircote added 2 commits January 15, 2026 15:05

chore: add share/ to .gitignore (generated artifacts)

e11a817

Copilot AI review requested due to automatic review settings January 15, 2026 20:06

Copilot AI reviewed Jan 15, 2026

View reviewed changes

zircote added 2 commits January 15, 2026 18:40

fix: address CI failures

b5451eb

- Run cargo fmt to fix formatting issues - Add Unicode-3.0 license to deny.toml (used by icu_* crates) - Ignore unmaintained crate advisories from langchain-rust deps - Fix Windows compatibility in hooks.rs (cfg(unix) for chmod)

Copilot AI review requested due to automatic review settings January 15, 2026 23:51

Copilot AI reviewed Jan 15, 2026

View reviewed changes

zircote added 2 commits January 15, 2026 21:52

fix: resolve CI failures

443552c

- Update RUSTSEC advisory IDs to correct 2025 versions - Add clippy::too_many_lines allow for generate_html_report - Update Makefile ci target to include deny and docs-check for parity with GitHub Actions

fix: bump MSRV to 1.85 and fix clippy lints

be3c0f5

- Update rust-version to 1.85 (required for edition2024 dependencies) - Update CI MSRV job to use Rust 1.85 - Fix clippy unnecessary_map_or warnings by using is_none_or - Simplify deny.toml advisory ignores

Copilot AI review requested due to automatic review settings January 16, 2026 03:00

Copilot AI reviewed Jan 16, 2026

View reviewed changes

github-advanced-security AI found potential problems Jan 16, 2026

View reviewed changes

Comment thread .github/workflows/ci.yml Fixed

zircote and others added 2 commits January 15, 2026 22:05

Potential fix for code scanning alert no. 11: Workflow does not conta…

85f7cde

…in permissions Co-authored-by: Copilot Autofix powered by AI <62310815+github-advanced-security[bot]@users.noreply.github.com>

Copilot AI review requested due to automatic review settings January 16, 2026 03:12

Copilot AI reviewed Jan 16, 2026

View reviewed changes

Copilot AI mentioned this pull request Jan 16, 2026

fix: address security and compatibility issues from PR #54 review #55

Closed

Copilot AI mentioned this pull request Jan 16, 2026

Acknowledge completed code review fixes in PR #54 #56

Closed

docs(changelog): add CI fix entries for MSRV bump and workflow fixes

74395ae

zircote merged commit 7b04864 into main Jan 16, 2026
27 checks passed

zircote deleted the rust-rewrite branch January 16, 2026 03:26

github-actions Bot mentioned this pull request Mar 2, 2026

[Branch Cleanup] Weekly Report — 2026-03-02 zircote/.github#40

Closed

		// Simple markdown to HTML conversion
		// TODO: Use a proper markdown parser

Conversation

zircote commented Jan 15, 2026

Summary

Key Changes

Features Included

Core Commands

ADR Formats

Optional Features (via --features)

Migration Path

Test Plan

Breaking Changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Jan 15, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 15, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 15, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 15, 2026

Choose a reason for hiding this comment

Uh oh!

zircote commented Jan 15, 2026

Code review

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI Jan 15, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

zircote commented Jan 16, 2026

Uh oh!

Copilot AI commented Jan 16, 2026

Uh oh!

zircote commented Jan 16, 2026

Code review

Uh oh!

Copilot AI commented Jan 16, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Optional Features (via `--features`)