Skip to content

Performance Guide

Gira is designed to handle large projects efficiently. This guide covers performance characteristics and optimization features.

Performance Benchmarks

Based on comprehensive testing with various project sizes (real benchmark data):

Gira Operations Performance

Operation 500 tickets 1000 tickets 2000 tickets Notes
Board display 0.105s 0.209s 0.404s Loads and displays kanban board
Board display (fast) 0.080s 0.111s 0.183s Optimized board with --fast flag
List all tickets 0.181s 0.354s 0.716s Lists all tickets
List high priority tickets 0.041s 0.068s 0.139s Filter by priority
List blocked tickets 0.024s 0.045s 0.085s Show dependency-blocked tickets
Search for 'test' 0.164s 0.319s 0.639s Full-text fuzzy search
Search for specific ticket 0.006s 0.008s 0.012s Direct ticket search
Show single ticket 0.006s 0.005s 0.005s Display one ticket details
List archived tickets 0.040s 0.042s 0.053s Archive operations
Move ticket status 0.005s 0.004s 0.004s Change ticket status
Create new ticket 0.018s 0.017s 0.017s Create ticket operation
List epics 0.004s 0.004s 0.004s Epic listing
Sync (conflict detection) 0.005s 0.004s 0.005s Conflict resolution

Git Operations Performance

Git Operation 500 tickets 1000 tickets 2000 tickets Notes
Git status 0.013s 0.015s 0.016s Check working tree status
Git add single file 0.012s 0.012s 0.013s Stage single file
Git add many files 0.029s 0.029s 0.031s Stage multiple files
Git commit 0.018s 0.019s 0.021s Create commit
Git commit many files 0.025s 0.023s 0.022s Commit multiple changes
Git log (recent) 0.010s 0.012s 0.011s Show recent commits
Git diff (working tree) 0.013s 0.014s 0.014s Show working tree diff

Scaling Characteristics

Analysis from real benchmarks:

  • Board display: Sub-linear scaling (3.8x time for 4.0x tickets)
  • List all tickets: Linear scaling (4.0x time for 4.0x tickets)
  • Search operations: Sub-linear scaling (3.9x time for 4.0x tickets)
  • Move ticket: Constant time (independent of project size)
  • Git operations: Nearly constant time (minimal impact from project size)

Built-in Optimizations

1. In-Memory Caching

Gira uses smart caching to avoid redundant file system operations:

  • Ticket lists cached for 60 seconds
  • Board data cached for 30 seconds
  • Cache automatically invalidated on ticket modifications

2. Parallel File Loading

For board display with many tickets:

# Use optimized board display for large projects
gira board --fast

The --fast flag enables: - Parallel file loading with thread pool - Batch processing of tickets - Optimized rendering

3. Efficient Data Structures

  • Tickets stored as individual JSON files for fast access
  • Directory-based organization by status
  • No database overhead

Performance Tips

For Large Projects (1000+ tickets)

  1. Use focused queries: 

    # Instead of listing all tickets
gira ticket list

# Filter by status or priority
gira ticket list --status "in progress"
gira ticket list --priority high

  2. Archive completed work: 

    # Archive old done tickets
gira archive create --status done --older-than 30

  3. Use the fast board display: 

    gira board --fast

Directory Structure

Keep your .gira/ directory organized:

.gira/
├── board/
│   ├── todo/        # Active tickets only
│   ├── in_progress/ # Current work
│   ├── review/      # Under review
│   └── done/        # Recently completed
└── archive/         # Old tickets
    └── 2025-07/     # Organized by month

Performance Analysis & Insights

Key Findings

  1. Excellent Performance at Scale: Gira handles 2000+ tickets efficiently with sub-second response times for most operations.

  2. Sub-linear Scaling: Most operations scale better than linearly, meaning doubling tickets doesn't double execution time.

  3. Git Independence: Git operations remain fast regardless of project size, making Gira suitable for large distributed teams.

  4. Fast Operations: Critical operations like ticket moves, shows, and epic listing are consistently under 0.02s.

Performance Recommendations by Project Size

Small Projects (< 500 tickets)

  • Expected Performance: All operations under 0.2s
  • Recommended Setup: Default configuration
  • Key Benefits: Instant response times, no optimization needed

Medium Projects (500-1000 tickets)

  • Expected Performance: Board display ~0.2s, list operations ~0.35s
  • Recommended Optimizations:
  • Use gira board --fast for improved board performance
  • Filter ticket lists by status/priority when possible
  • Key Benefits: Still excellent performance with minor optimizations

Large Projects (1000-2000 tickets)

  • Expected Performance: Board display ~0.4s, search ~0.6s
  • Recommended Optimizations:
  • Always use gira board --fast for board display
  • Use filtered lists instead of gira ticket list
  • Archive completed tickets quarterly
  • Key Benefits: Consistent performance with proper usage patterns

Enterprise Projects (2000+ tickets)

  • Expected Performance: Board display ~0.5s+, full search ~0.8s+
  • Required Optimizations:
  • Implement regular archiving strategy (monthly/quarterly)
  • Use focused queries exclusively
  • Consider project subdivision for very large teams
  • Key Benefits: Maintains usability at enterprise scale

Git Performance Insights

Excellent Git Integration: Git operations show minimal performance impact: - Git status: ~0.015s regardless of project size - Commit operations: ~0.02s for typical changes - Add operations: ~0.03s for bulk changes

Recommendation: Gira's Git integration is highly optimized and suitable for frequent commits.

Testing Performance

Run the comprehensive performance test suite:

# Quick benchmark (3 scales, 1 run each)
python scripts/benchmark.py --quick

# Full benchmark with multiple scales
python scripts/benchmark.py --scales 500 1000 2000 5000

# Export results for analysis
python scripts/benchmark.py --export-json results.json --report performance.md

# Test specific scale with averaging
python scripts/benchmark.py --scales 1000 --runs 5

Legacy Performance Test

For single-scale testing:

# Test with 500 tickets
python tests/performance/test_performance.py --tickets 500

# Test with 1000 tickets  
python tests/performance/test_performance.py --tickets 1000

# Keep test data for manual testing
python tests/performance/test_performance.py --tickets 1000 --keep

Future Optimizations

While current performance is excellent, potential future enhancements include:

  • Search indexing: Pre-built search index for instant results
  • Lazy loading: Load ticket details only when needed
  • Background updates: Refresh cache in background
  • Compression: Compress archived ticket data

Conclusion

Gira maintains excellent performance even with thousands of tickets through:

  1. Smart caching strategies
  2. Efficient file organization
  3. Parallel processing capabilities
  4. Minimal dependencies

For most teams (under 1000 active tickets), the default configuration provides instant response times for all operations.