git-machete: Instructions file for Codex

Conventions for AI coding agents

Tooling

• Run autoformatters and linters via tox. Never invoke flake8, isort, mypy, vulture, pylint (etc.) directly - go through their respective tox -e <env> invocation so dependency versions stay pinned.
• Exception: do NOT run tox -e flake8 or tox -e vulture (or those binaries directly). They hang indefinitely inside Cursor's terminal for an unidentified reason - rely on CI to catch any violations.
• Run tests with tox -e py [-- <pytest flags like -k>...]. Do NOT run pytest, python -m pytest, or any tox-built venv's pytest binary directly. Tox's passenv shielding is what keeps test runs deterministic
  • bypassing it lets dev-shell env vars (e.g. GIT_MACHETE_DIFF_OPTS) leak into the test process and produce failures that don't reproduce in CI.
• Use tox -e py (the full suite, several minutes) sparingly - by default scope it to the most likely affected tests via -k, -m, or explicit file/class/method selectors, e.g. tox -e py -- tests/test_cli.py tests/test_anno.py -k mutex. Only fall back to the full suite when the change is wide in scope (parser refactors, shared fixtures, base classes, ...) or when a scoped run already passes and you want a final pre-push sanity check.
• On macOS, skip the zsh subset of completion E2E tests (flaky on Mac): tox -e test-completions -- -k "not zsh". CI runs the full set on Linux.

Git

• Don't git commit or git push unless explicitly asked.

Tests

• Skip tests that require a minimum Git version with @pytest.mark.skipif(get_git_version() < (X, Y), reason="..."), not with an if get_git_version() < (X, Y): return early-return at the top of the test body. The decorator surfaces the skip in pytest's report (and in the JUnit XML CI uploads); the early-return silently masquerades as a pass.
• Prefer assert_success(cmd_and_args, expected_output) over a bare launch_command(cmd_and_args) whenever a command is run for its effect. A bare launch_command throws the command's entire output on the floor, so any regression in what it prints (a reworded message, a wrong/missing branch name, a stray extra line, a wrong singular/plural) goes completely unnoticed - the call still "passes". assert_success pins the whole output down, so it doubles as the regression test for that output. Reserve a bare launch_command for the cases where asserting the full output is genuinely troublesome (non-deterministic output such as commit hashes or --verbose/git-subprocess noise leaking into the captured text), and even then prefer asserting whatever deterministic prefix/suffix you can.
• Assert on the full command output rather than substring presence. Use assert_success(cmd_and_args, expected_output) (or, for ANSI/colored runs where --color=always produces escape codes, raw_output = launch_command(...); assert raw_output == expected_ansi) so the whole rendering is pinned down at once. Avoid assert "<phrase>" in output / assert "<phrase>" not in output for command-output checks - a substring match silently tolerates stray extra lines, misordered sections, the same phrase landing on the wrong row, or new (unintended) labels appearing elsewhere, all of which a full-output equality assertion would catch on the first run. Exception: substring checks are legitimate when the asserted invariant is genuinely scoped to one fragment of the output (e.g. "this warning text appears somewhere") and the rest of the output is either non-deterministic or already covered by another test.