GitBaby/AGENTS.md

AGENTS.md — gitbaby

What this is

• Single-crate Rust library (no binary, no workspace). Edition 2024.
• Public entrypoint: GitBaby::new(facade: Arc<dyn RepositoryFacade>, pipe: Pipe) in src/lib.rs.
• Consumers must implement RepositoryFacade (src/repo.rs) — three async fns returning a path/paths and a gix::Repository. There is no default impl.

Build / test / verify

• Standard cargo only. No CI, no pre-commit, no scripts, no rust-toolchain pin.
• Edition 2024 requires a recent stable toolchain (rustc ≥ 1.85). Local env verified at rustc 1.97.1.
• Useful commands (no order dependency beyond what's standard):
  • cargo build / cargo check / cargo build --release
  • cargo test (sync + #[tokio::test] integration tests in tests/)
  • cargo test --test <file> to run a single integration test file
  • cargo test <name> to filter by test name substring
  • cargo clippy --all-targets -- -D warnings if strict
  • cargo fmt --check / cargo fmt (default rustfmt; no rustfmt.toml)

Architecture notes

• Error pattern is hand-written. BabyError (src/error.rs, ~50 variants) and CmdError (src/command/error.rs) implement Display + std::error::Error by hand. thiserror is in Cargo.toml but not used via #[derive(thiserror::Error)]. Do not "modernize" by adding the derive — keep the hand-written impls consistent.
• Env in src/command/env.rs is order-preserving (Vec<(String, String)>), not a HashMap. with appends, set replaces in place. This matters for env-var ordering in spawned processes.
• Cmd::Display = prog + config_args + args (config_args are prepended to args at runtime).
• Pipe is Clone; cancel_pipe() sets cancelled=true and sends start_kill() to every running child but does not remove them from cmds.

Module layout convention

• Most feature modules follow src/<feature>/{mod.rs, types.rs, helper.rs, usecase.rs}; mod.rs re-exports the public types from types.rs.
• src/share/ is the outlier: it uses {cmd.rs, env.rs, error.rs, path.rs} instead. Don't "normalize" it.
• src/command/ uses {cmd.rs, context.rs, env.rs, error.rs, pipe.rs} and has its own error.rs separate from src/error.rs.

Test quirks (tests/)

• tests/cmd_run.rs defines a local unwrap_or_recover_or_panic!-style macro for asserting command output — reuse it, don't reinvent.
• tests/env.rs mutates process env. It guards tests with static ENV_LOCK: Mutex<()> and uses keys prefixed GITBABY_TEST_ENV_<suffix> for isolation. std::env::set_var / remove_var are wrapped in local unsafe fns; follow that pattern when adding env-mutating tests.
• tests/pipe.rs async cancel tests call tokio::time::sleep(Duration::from_millis(200)) after cancel_pipe() to let Child::try_wait observe exit — keep that delay when adding new cancel tests.

Gotchas

• No README. No docs beyond the code. Treat Cargo.toml + source as the only source of truth.
• gix = "0.86", tokio = 1.53 (full features), time = 0.3 — all recent; do not bump them speculatively.
• Public API surfaces async (async_trait); sync callers must use a runtime (tests use #[tokio::test]).