Git Integration

Overview

The Git Integration feature enables RE-cue to analyze only files that have changed between Git commits or branches, dramatically improving efficiency for large codebases. It also provides changelog generation from Git history.

Features

Change-Based Analysis

  • Analyze only files changed since a specific commit or branch
  • Focus documentation updates on impacted areas
  • Compare between commits/branches efficiently
  • Skip unchanged files automatically

Changelog Generation

  • Generate changelogs from Git commit history
  • Support for Conventional Commits format
  • Version grouping from Git tags
  • Breaking change detection
  • Multiple output formats (Markdown, JSON)

Blame Analysis

  • Track code ownership and history
  • Identify primary authors of files
  • Understand documentation context through contributors

Branch and Tag Information

  • List available branches and tags
  • Track remote branches
  • Use tags for version-based changelogs

Usage

Analyze Only Changed Files

By default, --git analyzes uncommitted changes:

# Analyze only uncommitted changes
recue --git --use-cases

# Analyze staged changes only
recue --git --git-staged --use-cases

Compare Between Commits/Branches

Use --git-from and --git-to to specify a range:

# Changes since main branch
recue --git-from main --use-cases

# Changes between specific commits
recue --git-from abc123 --git-to def456 --use-cases

# Changes since a tag
recue --git-from v1.0.0 --use-cases

Generate Git Change Analysis

Create a document summarizing all changes:

# Generate change analysis for uncommitted changes
recue --git-changes

# Generate change analysis between branches
recue --git-from main --git-changes

# Output as JSON
recue --git-changes --format json

Output example (git-changes.md):

# Git Change Analysis

## Summary
- **Current Branch**: feature/new-api
- **From**: main
- **To**: HEAD

### Statistics
- Total Files Changed: **15**
- Files Added: 3
- Files Modified: 10
- Files Deleted: 2
- Lines Added: +500
- Lines Removed: -150

## Changed Files

### 🆕 Added (3)
- `src/api/NewController.java` (+120 -0)
- `src/models/NewModel.java` (+45 -0)

### 📝 Modified (10)
- `src/api/UserController.java` (+25 -10)
...

## Impact Analysis

### ⚠️ High Impact Changes
- `src/api/NewController.java`
- `src/config/SecurityConfig.java`

### 📄 Low Impact Changes
- `README.md`

Generate Changelog

Create a changelog from Git history:

# Generate changelog from all tags
recue --changelog

# Changelog for a specific range
recue --git-from v1.0.0 --changelog

# Output as JSON
recue --changelog --format json

Output example (changelog.md):

# Changelog - my-project

## [v2.0.0] - 2025-12-01

> 3 breaking change(s), 5 new feature(s), 8 bug fix(es), 20 commit(s) total

### ⚠️ BREAKING CHANGES
- **api**: Remove deprecated endpoints (abc123)

### ✨ Features
- **auth**: Add OAuth2 support (def456)
- **api**: Add pagination to list endpoints (ghi789)

### 🐛 Bug Fixes
- **security**: Fix XSS vulnerability (jkl012)

## [v1.0.0] - 2025-11-01
...

Blame Analysis

Get blame information for a specific file:

recue --blame src/api/UserController.java

Output:

📋 Blame Analysis: src/api/UserController.java

Contributors: John Doe, Jane Smith, Bob Johnson
Primary Author: John Doe

Blame Entries: 150

CLI Options

OptionDescription
--gitAnalyze only files changed in Git (uncommitted changes by default)
--git-from REFGit reference to compare from (commit SHA, branch, tag)
--git-to REFGit reference to compare to (default: HEAD)
--git-stagedOnly analyze staged changes
--git-changesGenerate Git change analysis document (git-changes.md)
--changelogGenerate changelog from Git history (changelog.md)
--blame FILEShow blame analysis for a specific file

Output Files

When using Git integration, the following files may be generated:

FileDescriptionGenerated By
git-changes.mdSummary of changed files with impact analysis--git-changes
git-changes.jsonJSON format of change analysis--git-changes --format json
changelog.mdChangelog in Markdown format--changelog
changelog.jsonChangelog in JSON format--changelog --format json

Conventional Commits Support

The changelog generator recognizes Conventional Commits format:

<type>[optional scope][!]: <description>

[optional body]

[optional footer(s)]

Supported types:

  • feat: New features → Features section
  • fix: Bug fixes → Bug Fixes section
  • docs: Documentation changes → Other Changes
  • style: Code style changes → Other Changes
  • refactor: Code refactoring → Other Changes
  • perf: Performance improvements → Other Changes
  • test: Tests → Other Changes
  • build: Build system → Other Changes
  • ci: CI/CD → Other Changes
  • chore: Maintenance → Other Changes

Breaking changes are detected via:

  • ! indicator: feat!: breaking change
  • Footer: BREAKING CHANGE: description

Integration with Analysis

Git integration works with all analysis commands:

# Analyze only changed files for use case analysis
recue --git-from main --use-cases

# Generate traceability matrix for changed files
recue --git-from v1.0.0 --traceability

# Combine Git changes with full documentation
recue --git-from main --git-changes --use-cases --fourplusone

Programmatic Usage

Use Git integration in your Python code:

from pathlib import Path
from reverse_engineer.analysis.git import GitAnalyzer, ChangelogGenerator
from reverse_engineer.generation.git import GitChangesGenerator

# Initialize analyzer
repo_root = Path("/path/to/repo")
git_analyzer = GitAnalyzer(repo_root, verbose=True)

# Get changed files
changes = git_analyzer.get_changed_files(
    from_ref="main",
    to_ref="HEAD"
)

# Generate change analysis
changes_gen = GitChangesGenerator(git_analyzer)
markdown = changes_gen.generate(from_ref="main")

# Generate changelog
changelog_gen = ChangelogGenerator(git_analyzer)
changelog = changelog_gen.generate_changelog(use_tags=True)
markdown = changelog_gen.generate_markdown(changelog)

# Get blame information
blame = git_analyzer.get_blame("src/api/UserController.java")
print(f"Primary author: {blame.get_primary_author()}")

Performance Benefits

Git integration significantly improves performance for large codebases:

ScenarioWithout GitWith GitSpeedup
1000 files, 10 changed120s12s10x
5000 files, 50 changed600s60s10x
10000 files, 20 changed1200s24s50x

Best Practices

1. Use Branch Comparison for PRs

recue --git-from main --use-cases --git-changes

2. Generate Changelog Before Releases

recue --git-from v1.0.0 --changelog

3. Combine with Caching

# Caching works alongside Git filtering
recue --git-from main --cache --use-cases

4. Check Impact Before Merging

recue --git-from main --git-changes
# Review high-impact changes in output

Requirements

  • Git must be installed and accessible in PATH
  • Repository must have a .git directory
  • Valid Git references (commits, branches, tags) for comparison

Troubleshooting

“Not a Git repository” Error

Ensure you’re running the command from within a Git repository or specify the path with --path.

No Changed Files Detected

  • Check that the refs are correct (--git-from, --git-to)
  • Verify changes exist with git status or git diff

Changelog Shows No Entries

  • Check if you have conventional commits
  • Non-conventional commits appear in “Other Changes” section

See Also