Development Setup

Development Setup

To build and contribute to retch, ensure you have the following prerequisites installed on your system.

Prerequisites

• Rust (latest stable toolchain)
• just (command runner for checking format, running tests, and compiling documentation)
• mandown (required for generating the manual page via just man — cargo install mandown)
• hyperfine (optional, required for local CLI execution speed benchmarking)

Nix / NixOS Setup

If you use Nix, all prerequisites are provided automatically via the flake devShell:

git clone https://github.com/l1a/retch.git
cd retch
nix develop

This drops you into a shell with cargo, rustc, rust-analyzer, just, mandown, hyperfine, and python3 available. Skip to Common Just Recipes once inside.

Local Setup

1. Clone the Repository:

   git clone https://github.com/l1a/retch.git
   cd retch

2. Run one-time repo setup (installs git hooks):

   just setup

   This installs the post-merge hook that automatically uploads local benchmark results to the dashboard whenever you merge into main. Only needs to be run once per clone.
3. Build the Project:

   cargo build --release

Common Just Recipes

Recipe	Description
just dev	Full development cycle: setup → fmt → lint → test → build
just check	Strict fmt + clippy checks (same as CI)
just fmt	Auto-format code with cargo fmt
just lint	Run clippy with -D warnings
just test	Run all tests
just build	Build release binary
just clean	Remove build artifacts
just audit	Run cargo audit for known security advisories
just man	Regenerate docs/retch.1 from docs/retch.1.md via mandown
just install	Build and install the binary + man page system-wide
just install-hooks	Install git hooks (included in just setup)
just publish-check	Verify packaging and dry-run publish for crates.io
just publish	Publish both crates to crates.io (sysinfo first, then CLI)
just pr	Automated Pre-PR gate — see below
just open-pr	Runs just pr, then gh pr create if it passes — the only sanctioned way to open a PR
just merge-pr	Squash-merge, switch to main, reset WIP.md — see below

Opening a Pull Request

Never call gh pr create directly. Always use:

just open-pr

(any args are forwarded to gh pr create). This runs the automated Pre-PR gate (just pr) first and only calls gh pr create if it passes. gh has no hook mechanism of its own, so this Justfile recipe is the one enforcement point that works regardless of which tool — human shell, Claude Code, or any other agent — is driving.

just pr (run on its own before each subsequent push to an open PR, not just once) checks you're on a feature branch (not main), that Cargo.toml's version has been bumped past the last tag, that NOTES.md's "Current State" header matches, regenerates and diffs the man page, verifies Cargo.lock is committed, runs just check and cargo test, then prints a manual checklist (README, NOTES.md release log, wiki, tldr page) that you confirm before it reports the gate passed. See AGENTS.md in the main repo for the full checklist this automates.

After a PR is merged, run:

just merge-pr

This squash-merges via gh, switches to main, pulls (which also fires the post-merge benchmark-upload hook — see Running Benchmarks below), deletes the local feature branch, and resets WIP.md for the next session.

Running Benchmarks

• Run Criterion micro-benchmarks:

  just bench

• Benchmark the CLI execution speed:

  just bench-cli

• Compare retch against other fetchers (e.g. fastfetch, neofetch):

  just bench-compare

• Upload local benchmark results to the gh-pages performance dashboard:

  just bench-upload

  This requires hyperfine and gh (GitHub CLI) to be authenticated. It is also run automatically after merging into main if you have run just setup. On Windows, run from Git Bash; native cmd/PowerShell are not supported for this recipe.