README.md

git-perf Documentation

Welcome to the git-perf documentation! This page serves as your guide to all available documentation.

Getting Started

New to git-perf? Start here:

• Quick Start - Get running in 5 minutes with basic commands
• Installation Guide - Multiple installation methods (shell installer, crates.io, pre-built binaries, from source)
• Integration Tutorial - Complete step-by-step guide for GitHub Actions setup

User Guides

Detailed guides for specific use cases:

• Configuration Guide - Complete .gitperfconfig reference
  • Statistical dispersion methods (stddev vs MAD)
  • Per-measurement configuration overrides
  • Epoch management
  • Unit configuration
• Audit System - Understanding regression detection
  • Statistical analysis methods
  • Threshold configuration
  • Interpreting audit output
  • Managing epochs for expected changes
• Importing Measurements - Import test execution times and benchmark results
  • JUnit XML format (pytest, Jest, cargo-nextest, JUnit, and more)
  • Criterion JSON format (Rust benchmarks)
  • Cross-language examples and best practices

Reference Documentation

Technical reference material:

• CLI Reference - Complete command-line reference for all git-perf commands
  • All subcommands (measure, add, import, audit, report, etc.)
  • Command options and flags
  • Usage examples
• Configuration File Reference - Annotated .gitperfconfig template
  • All available configuration options
  • Example values with explanations
  • Per-measurement overrides
• FAQ - Frequently asked questions
  • General usage
  • Configuration and units
  • Audit and regression detection
  • Data management
  • GitHub Actions integration
  • Troubleshooting

Contributing

Resources for contributors and developers:

• Contributing Guide - How to contribute to git-perf
  • Code of conduct
  • Development workflow
  • Code quality standards
  • Testing requirements
  • Pull request guidelines
  • Commit message format (Conventional Commits)
• Development Setup - Developer and AI agent instructions
  • Quick reference commands
  • Pull request requirements
  • Testing setup
  • Documentation generation
  • Project architecture
• Release Process - How releases are automated
  • release-plz and cargo-dist workflow
  • Release flow diagram
  • Environment setup

Research & Analysis

• CI Runner Variance Experiment - Quantified inter-runner noise on GitHub Actions
  • 100 runner instances across Ubuntu and macOS
  • Aggregation and dispersion method comparison
  • Minimum detectable effect (MDE) analysis
  • Recommended configuration for CI environments

Additional Resources

• Evaluation Tools - Statistical method comparison tools
  • Comparing stddev vs MAD dispersion methods
  • Evaluation scripts and results
• Live Example Report - See git-perf in action
• GitHub Discussions - Ask questions and share ideas
• GitHub Issues - Report bugs or request features

GitHub Actions

Reusable GitHub Actions for CI/CD integration:

• Install Action - Install git-perf in workflows
• Report Action - Generate and publish performance reports
  • Automatic PR comments with results
  • GitHub Pages integration
  • Audit integration
• Cleanup Action - Remove old measurements and reports
  • Configurable retention periods
  • Dry-run support

Documentation Organization

docs/
├── README.md (this file)                  # Documentation index
├── INTEGRATION_TUTORIAL.md                # End-to-end GitHub Actions setup
├── importing-measurements.md              # Test and benchmark import guide
├── manpage.md                             # CLI reference (auto-generated)
├── example_config.toml                    # Configuration template
├── ci-variance-experiment/                # Runner variance analysis
│   ├── README.md                          # Full results and methodology
│   └── *.png                              # Analysis plots
└── plans/                                 # Feature design documents (internal)

How git-perf Works

Want to understand the internals?

• Storage Model - How measurements are stored using git-notes
• Merge Strategy - How concurrent measurements are handled
• Pull Request Workflow - How PR measurements work with first-parent traversal

Need Help?

• FAQ: Check the Frequently Asked Questions for common issues
• Troubleshooting: See Integration Tutorial Troubleshooting for CI/CD issues
• Issues: Open an issue if you can't find an answer
• Discussions: Start a discussion for questions or ideas

---

Documentation Version: Matches git-perf main branch Last Updated: Auto-updated with each documentation change