Skip to content
This repository was archived by the owner on May 27, 2026. It is now read-only.

branch-analysis-optimization.md

Latest commit

 

History

History
204 lines (158 loc) · 5.61 KB

branch-analysis-optimization.md

File metadata and controls

204 lines (158 loc) · 5.61 KB
Raw

Branch Analysis Optimization

This document describes the new branch analysis optimization features added to GitFlow Analytics to handle large organizations with many repositories and branches efficiently.

Problem Statement

The original "analyze all branches" approach caused performance issues on large organizations with:

  • 95+ repositories
  • Hundreds of branches per repository
  • Analysis times exceeding practical limits
  • Risk of hanging or running out of memory

Solution: Smart Branch Analysis

Three configurable strategies are now available:

1. Main Only Strategy (main_only)

  • Use case: Rapid testing, simple analysis
  • Performance: Fastest
  • Completeness: Basic (main branch only)
  • Recommended for: Quick analysis, CI/CD pipelines

2. Smart Strategy (smart) - Default

  • Use case: Production analysis
  • Performance: Balanced
  • Completeness: High (captures meaningful development activity)
  • Recommended for: Most use cases

3. All Branches Strategy (all)

  • Use case: Comprehensive research
  • Performance: Slowest
  • Completeness: Maximum
  • Recommended for: Research, detailed historical analysis

Smart Strategy Details

The smart strategy uses intelligent filtering:

Branch Prioritization

  1. Important branches (always included):

    • Main/master branches
    • Release branches (release/*)
    • Hotfix branches (hotfix/*)

  2. Active branches:

    • Branches with commits within the last 90 days (configurable)
    • Limited to top 50 branches per repository (configurable)

  3. Excluded branches:

    • Automation branches (dependabot/*, renovate/*)
    • Temporary branches (*-backup, *-temp)

Performance Controls

  • Branch limit: Maximum branches analyzed per repository
  • Commit limit: Maximum commits analyzed per branch
  • Progress logging: Real-time feedback during analysis

Configuration

Add branch analysis configuration to your YAML config:

analysis:
  branch_analysis:
    # Strategy: "smart", "main_only", or "all"
    strategy: "smart"
    
    # Smart analysis parameters
    max_branches_per_repo: 50
    active_days_threshold: 90
    include_main_branches: true
    
    # Branch patterns (regex)
    always_include_patterns:
      - "^(main|master|develop|dev)$"
      - "^release/.*"
      - "^hotfix/.*"
    
    always_exclude_patterns:
      - "^dependabot/.*"
      - "^renovate/.*"
      - ".*-backup$"
      - ".*-temp$"
    
    # Performance settings
    enable_progress_logging: true
    branch_commit_limit: 1000

Configuration Options

strategy

  • Type: String
  • Options: "smart", "main_only", "all"
  • Default: "smart"
  • Description: Branch analysis strategy

max_branches_per_repo

  • Type: Integer
  • Default: 50
  • Description: Maximum branches to analyze per repository

active_days_threshold

  • Type: Integer
  • Default: 90
  • Description: Days to consider a branch "active"

always_include_patterns

  • Type: List of strings (regex patterns)
  • Default: Main, release, hotfix patterns
  • Description: Branch patterns to always include

always_exclude_patterns

  • Type: List of strings (regex patterns)
  • Default: Automation and temp branch patterns
  • Description: Branch patterns to always exclude

enable_progress_logging

  • Type: Boolean
  • Default: true
  • Description: Show branch analysis progress

branch_commit_limit

  • Type: Integer
  • Default: 1000
  • Description: Maximum commits to analyze per branch

Performance Comparison

Based on testing with a large organization:

Strategy Branches Analyzed Analysis Time Completeness
main_only 1 per repo ~30 seconds ~60%
smart ~20 per repo ~5 minutes ~90%
all 100+ per repo ~30+ minutes ~95%

Migration Guide

Existing Configurations

  • No action required: Configurations without branch_analysis section will use smart defaults
  • Explicit control: Add branch_analysis section for custom behavior

Performance Tuning

  1. Start with defaults: Smart strategy with default settings
  2. Adjust for scale: Reduce max_branches_per_repo for very large organizations
  3. Fine-tune patterns: Customize include/exclude patterns for your naming conventions

Troubleshooting

Analysis Taking Too Long

  1. Switch to main_only strategy for testing
  2. Reduce max_branches_per_repo
  3. Decrease active_days_threshold

Missing Important Branches

  1. Check always_include_patterns
  2. Increase max_branches_per_repo
  3. Reduce active_days_threshold

Too Many Unimportant Branches

  1. Review always_exclude_patterns
  2. Increase active_days_threshold
  3. Decrease max_branches_per_repo

Example Configurations

Large Organization (Conservative)

analysis:
  branch_analysis:
    strategy: "smart"
    max_branches_per_repo: 25
    active_days_threshold: 60
    enable_progress_logging: true

Small Team (Comprehensive)

analysis:
  branch_analysis:
    strategy: "all"
    max_branches_per_repo: 100
    enable_progress_logging: false

CI/CD Pipeline (Fast)

analysis:
  branch_analysis:
    strategy: "main_only"
    enable_progress_logging: false

Implementation Details

The optimization is implemented in GitAnalyzer._get_commits_optimized() with:

  • Strategy pattern for different analysis approaches
  • Branch metadata collection and prioritization
  • Regex-based filtering
  • Progress reporting
  • Graceful error handling

See the source code for complete implementation details.