Case Study: GitSimulator — Production-Grade Git Simulation

Motivation & Pain Points

Git's most powerful commands (rebase, merge, reset, cherry-pick) are also its most dangerous. One wrong move can rewrite history, lose work, or create conflicts that take hours to resolve. GitSimulator addresses the fundamental problem: Git provides no preview of destructive operations before execution.

• Zero Foresight: No way to see exact outcome before running commands like git reset --hard or git rebase
• Surprise Conflicts: Users only discover conflicts mid-operation, after refs have already changed
• Steep Learning Curve: Understanding merge bases, replay ordering, force-push implications, and detached HEAD states is non-trivial
• CI/CD Risk: Automated pipelines cannot validate dangerous Git operations before execution
• Team Onboarding: New developers lack safe environments to experiment with advanced Git features

GitSimulator's Solution: A safe, read-only simulation environment with visual feedback, conflict prediction, safety analysis, and educational explanations—all backed by production-grade infrastructure (135+ tests, CI/CD, plugin architecture).

Recognition

GitSimulator was awarded 3rd Place at GitKon Game Jam 2025, hosted by GitKraken. The competition challenged developers to build games or tools that make Git more playful, turning Git's notorious pain points into engaging mechanics. GitSimulator was recognized for its innovative approach to Git visualization, educational impact through safe command exploration, and focus on preventing costly mistakes in production environments. The project stood out for combining technical rigor (135+ tests, automated CI/CD) with practical utility (conflict prediction, safety analysis) and educational value (interactive TUI, explain mode).

Architecture Overview

Production-Grade System Design

GitSimulator follows a clean, modular architecture with strict separation of concerns and production-ready infrastructure:

┌────────────────── CLI Layer (Typer) ──────────────────┐
│  Commands │ Options │ Parsing │ Rich Formatting      │
└───────────────────────┬───────────────────────────────┘
                        ▼
┌───────────── Simulation Dispatcher ──────────────────┐
│  • Command routing                                   │
│  • Plugin hook execution (pre/override/post)         │
│  • Result validation                                 │
└───────────────────────┬──────────────────────────────┘
                        ▼
        ┌───────────────┼───────────────┐
        ▼               ▼               ▼
   ┌─────────┐    ┌─────────┐    ┌─────────┐
   │ Rebase  │    │  Merge  │    │  Reset  │
   │Simulator│    │Simulator│    │Simulator│
   └─────────┘    └─────────┘    └─────────┘
        └───────────────┼───────────────┘
                        ▼
┌──────────────── Core Services ───────────────────────┐
│  Repository (Dulwich) │ Diff Analyzer │ Conflict    │
│                       │               │ Detector    │
└───────────────────────┬──────────────────────────────┘
                        ▼
┌────────────── Git Repository (.git/) ────────────────┐
│          Read-only access via Dulwich                │
└──────────────────────────────────────────────────────┘

Core Components

1. Repository Layer (core/repository.py): Pure Python Git access via Dulwich—no git binary required. Features short SHA resolution (7+ chars), relative refs (HEAD~2), topological sorting, and lazy loading for performance.
2. Simulation Engines (simulation/): Each implements BaseSimulator[T] protocol with validate() and simulate() methods. Covers rebase, merge, reset, cherry-pick with step-by-step conflict tracking.
3. Conflict Detection (simulation/conflict_detector.py): Three-level heuristics (CERTAIN 90%+, LIKELY 70%+, POSSIBLE 50%+) analyzing diff hunks, line overlaps, and structural changes.
4. Safety Analysis System: Weighted risk scoring (LOW/MEDIUM/HIGH/CRITICAL) considering rewrite depth, force-push requirements, orphaned commits, and conflict density.
5. Plugin Architecture (plugins/): Hook, Simulator, and Formatter plugins discovered via entry points. Enables custom simulators, output formats, and policy enforcement.
6. Interactive TUI (tui/app.py): Textual-powered terminal UI with real-time command preview, keyboard navigation, and headless mode for scripting.
7. Snapshot System (snapshot.py): Save/restore repository states in separate .git/git-sim-snapshots/ directory for safe experimentation.

Testing Infrastructure (135+ Tests)

• Unit Tests: Isolated component testing (repository, conflict detector, each simulator)
• Integration Tests: End-to-end command flows with real Git repository fixtures
• Property Tests: Invariant checking (graphs are DAGs, simulations idempotent, no repo mutations)
• Fixture-Based: Multiple repo states (linear history, branched, merge commits, octopus merges, detached HEAD)
• Coverage: 95%+ via pytest with HTML reports

CI/CD Pipeline (GitHub Actions)

Automated workflow on every push and pull request:

1. Code Quality: Ruff linting and formatting checks
2. Type Safety: MyPy strict mode type checking
3. Cross-Platform Testing: pytest across Python 3.11/3.12/3.13 on Linux/macOS/Windows
4. Coverage Enforcement: Require 90%+ test coverage
5. Automated Releases: PyPI publishing on version tags with automated changelog generation

Simulation Pipeline

# High-level pseudocode
plan = parse_command(input)
repo = Repository.open(cwd)
base_state = Snapshot.capture(repo)
commit_graph_before = Graph.build(repo)
engine = select_engine(plan.operation)
analysis = engine.prepare(repo, plan)
conflicts = ConflictDetector.predict(repo, analysis)
new_graph = engine.simulate(commit_graph_before, analysis, conflicts)
safety = SafetyAnalyzer.score(plan, analysis, conflicts, commit_graph_before, new_graph)
return SimulationResult(
  operation=plan.operation,
  before=commit_graph_before,
  after=new_graph,
  conflicts=conflicts,
  safety=safety,
  reversible=Snapshot.can_restore(base_state, new_graph)
)

The pipeline never mutates refs. simulate() returns a CommitGraph clone with projected IDs (virtual hashes derived from parent+tree diff signature) for commits that would be rewritten.

Advanced Conflict Detection Engine

GitSimulator’s conflict detection uses sophisticated heuristics to predict merge/rebase conflicts before execution, with three certainty levels:

Detection Levels

• CERTAIN (90%+ accuracy): Same file with overlapping line ranges; both sides modify identical lines; binary file conflicts; delete vs modify scenarios
• LIKELY (70%+ accuracy): Changes within 3 lines of each other; same function/class modifications; high-churn areas; mode changes combined with content edits
• POSSIBLE (50%+ accuracy): Same file modified in different sections; semantic conflicts (import changes, dependency updates)

Detection Algorithm

for each file changed in OURS:
    if file changed in THEIRS:
        parse diff hunks (line ranges + content)
        for each hunk_ours:
            for each hunk_theirs:
                if hunks_overlap(hunk_ours, hunk_theirs):
                    → CERTAIN conflict (line ranges intersect)
                elif hunks_nearby(hunk_ours, hunk_theirs, threshold=3):
                    → LIKELY conflict (within 3 lines)
                else:
                    → POSSIBLE conflict (same file, different sections)
                    
Apply false positive reduction:
  - Normalize whitespace (tabs/spaces, trailing)
  - Collapse contiguous hunks
  - Filter comment-only diffs
  - Detect rename patterns

Edge Cases Handled

• Binary Files: Marked CERTAIN with advisory for manual inspection
• Renames + Modifications: Path changes on both sides detected via similarity heuristics
• Mode Changes: Executable bit/symlink toggles flagged when combined with content edits
• Octopus Merges: Multi-parent ambiguity triggers structural warnings

Safety Scoring Model

Safety levels aggregate weighted factors (w_i) into a normalized 0–100 risk score:

risk = Σ (w_factor * factor_value)
level =
  risk < 25  -> LOW
  risk < 50  -> MEDIUM
  risk < 75  -> HIGH
  else       -> CRITICAL

• History Rewrite Depth: Number of commits with new virtual hashes.
• Force Push Requirement: Any non-fast-forward ref update on a remote-tracked branch.
• Detached Commits Risk: Commits becoming unreachable unless re-tagged.
• Conflict Density: Conflicts / commits replayed ratio.
• Working Tree Discard: (Reset modes) Count + total size of lost tracked changes.

Performance & Optimization

• Lazy Graph Building: Only load commits needed for visualization (not entire history)
• Diff Caching: Memoize expensive diff operations within simulation session
• Short SHA Indexing: Early abort on first unique match (7+ chars)
• Parallel-Safe Design: Pure functional core with no shared mutable state
• Memory Efficiency: Stream commits instead of loading all into memory
• Cross-Platform: Tested on Linux, macOS, Windows across Python 3.11/3.12/3.13

Production Metrics

• Test Coverage: 95%+ across 135+ comprehensive tests
• CI Success Rate: 99%+ (tracked via GitHub Actions badge)
• PyPI Distribution: v1.0.1 published November 2025
• Supported Platforms: Linux, macOS, Windows × Python 3.11/3.12/3.13
• Dependencies: Minimal (Dulwich, Rich, Typer, Textual)
• Package Size: Lightweight CLI with no Git binary dependency

Developer Experience & Modern CLI

Unified Command Interface

Three equivalent commands reduce memorization overhead:

gitsim rebase main
git-sim rebase main        # Dash-style (git alias friendly)
gitsimulator rebase main   # Full package name

# Unified dispatcher for natural syntax:
gitsim sim "rebase main --autosquash"

Rich Terminal Output

• Summary Tables: Source/target branches, merge base, commit counts, conflict predictions
• Safety Panels: Color-coded danger levels (🟢 LOW, 🟡 MEDIUM, 🟠 HIGH, 🔴 CRITICAL)
• ASCII Commit Graphs: Side-by-side before/after visualization with branch topology
• Conflict Tables: Severity, file paths, line ranges in structured format
• Recovery Instructions: Step-by-step undo commands (git reflog, git reset)

Interactive TUI Mode

Textual-powered interface with:

• Real-time command preview as you type
• Keyboard navigation of commit graphs (arrow keys, vim bindings)
• Conflict hotspot highlighting
• Headless mode for CI/scripting: gitsim tui --headless

Educational Mode

gitsim explain <command> provides interactive learning:

• 📖 Plain-English explanations of Git internals
• 🔍 Step-by-step algorithm breakdowns
• ⚠️ Risk assessment and common pitfalls
• 💡 Best practices and safety tips
• 🔄 Alternative approaches (merge vs rebase, reset modes)

Key Struggles & Solutions

• Diff Normalization: Early false positives due to indentation-only changes → added semantic filtering.
• Virtual Hash Representation: Need stable identifiers without computing real SHA-1 → deterministic short hash from parent hash + file path + line change fingerprint.
• Conflict Density Overcount: Multi-line hunk treated as multiple conflicts → collapsed contiguous ranges.
• Safety Calibration: CRITICAL overstated for benign interactive rebases → tuned force-push weight downward.

Real-World Use Cases

1. Pre-Flight Rebase Audit

Before running git rebase main on a 50-commit feature branch:

gitsim rebase main

# Output shows:
# - 50 commits will be rewritten (new SHAs)
# - 3 CERTAIN conflicts in config.py, auth.py
# - HIGH safety level (force-push required)
# - Recovery: git reflog + git reset --hard ORIG_HEAD

2. CI/CD Merge Safety Gate

GitHub Actions workflow:

- name: Validate merge safety
  run: |
    gitsim merge ${{ github.head_ref }} --json > result.json
    SAFETY=$(jq -r '.safety.level' result.json)
    if [[ "$SAFETY" == "CRITICAL" ]]; then
      echo "::error::Merge too risky - manual review required"
      exit 1
    fi

3. Team Onboarding & Education

New developers learn Git internals safely:

gitsim explain rebase     # How rebase works internally
gitsim explain merge      # Three-way merge algorithm
gitsim explain reset      # SOFT vs MIXED vs HARD modes

# Then experiment with snapshots:
gitsim snapshot create before-rebase
gitsim rebase main
# If confused, restore:
gitsim snapshot restore before-rebase

4. Complex Cherry-Pick Planning

Picking 10 commits from feature-a onto hotfix:

gitsim cherry-pick abc123 def456 789xyz ... --onto hotfix

# Shows:
# - Step-by-step conflict prediction for each commit
# - New commit order and SHAs
# - Cumulative conflict areas

5. Dangerous Reset Scenarios

Visualize impact before discarding work:

gitsim reset HEAD~5 --hard

# CRITICAL warning:
# - 5 commits will become orphaned
# - 12 files in working tree will be lost
# - Staged changes discarded (3 files)
# - Recovery possible via reflog for 30 days

Roadmap & Evolution

✅ Completed (v1.0.1)

• Interactive TUI with Textual framework
• Plugin system (Hook, Simulator, Formatter plugins)
• 135+ comprehensive test suite with 95%+ coverage
• Automated CI/CD pipeline (linting, type checking, multi-platform testing)
• PyPI distribution with automated releases
• Educational explain mode for all major commands
• Snapshot/restore system for safe experimentation

🛠️ In Progress

• AST-based conflict refinement for language-specific detection (Python, JavaScript, TypeScript)
• Stash simulation support
• Internationalization (i18n) for explain mode

📋 Planned (v1.1+)

• Batch mode for CI matrix analysis (test multiple branch combinations)
• Custom policy scoring plugins for organization-specific rules
• Integration with Git hosting APIs (GitHub, GitLab, Bitbucket)
• Web-based visualization export (HTML reports)
• Performance profiling mode for large repositories (10K+ commits)

Lessons Learned & Engineering Insights

Heuristics First, Precision Later

Fast approximations unlock value early. We shipped conflict detection with 70%+ accuracy instead of waiting for 95% precision via AST parsing. Users adopted it immediately, and we can layer in deeper analysis later. Key insight: "Good enough" solutions that ship beat perfect solutions that don't.

Explainability Drives Adoption

Users trust safety scores more when rationale is explicit. The explain mode showing why a rebase is HIGH risk (e.g., "3 commits rewritten + force-push required to origin/main") builds confidence. Lesson: Transparency > black-box algorithms.

Testing Infrastructure Pays Dividends

135+ tests caught edge cases during plugin development that would have been production bugs:

• Octopus merges (multiple parents) breaking graph traversal
• Detached HEAD states causing ref resolution failures
• Ambiguous short SHAs (e.g., abc matching both abc1234 and abc5678)
• Windows path handling differences (backslash vs forward slash)

Investment: Writing comprehensive tests takes time upfront but prevents exponential debugging costs later.

Pure Python = Portability Win

Using Dulwich instead of shelling out to git binary eliminated platform-specific bugs:

• No Windows CMD.exe escaping issues
• No Git version compatibility matrix to maintain
• Works in SSH-only environments (no Git installation required)
• Consistent behavior across platforms (no git config differences)

Trade-off: Dulwich has slightly different rename detection than Git, but consistency across platforms outweighs this.

CI/CD Automation Saves Time

Automated PyPI releases on version tags eliminated manual publishing errors:

• Forgot to update version in pyproject.toml → CI enforces tag-version match
• Incomplete changelog → CI generates from commit messages
• Broken builds shipped to PyPI → CI tests before publishing

ROI: 2 days setup time has saved ~4 hours per release (8 releases so far = 32 hours saved).

Read-Only Design Builds Trust

Guaranteeing zero repository mutations (via Dulwich read-only API) was critical for user adoption. Developers are rightfully cautious about tools that touch .git/. Philosophy: Constraints (read-only) can be features (safety guarantee).