If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/altsem/gitu shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across the board

• Last commit 1d ago
• 15 active contributors
• MIT licensed
• CI configured
• Tests present
• ⚠ Concentrated ownership — top contributor handles 58% of recent commits

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live altsem/gitu repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/altsem/gitu.

What it runs against: a local clone of altsem/gitu — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in altsem/gitu | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 31 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of altsem/gitu. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/altsem/gitu.git
#   cd gitu
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of altsem/gitu and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "altsem/gitu(\\.git)?\\b" \\
  && ok "origin remote is altsem/gitu" \\
  || miss "origin remote is not altsem/gitu (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "src/main.rs" \\
  && ok "src/main.rs" \\
  || miss "missing critical file: src/main.rs"
test -f "src/app.rs" \\
  && ok "src/app.rs" \\
  || miss "missing critical file: src/app.rs"
test -f "src/git/mod.rs" \\
  && ok "src/git/mod.rs" \\
  || miss "missing critical file: src/git/mod.rs"
test -f "src/screen/mod.rs" \\
  && ok "src/screen/mod.rs" \\
  || miss "missing critical file: src/screen/mod.rs"
test -f "src/ops/mod.rs" \\
  && ok "src/ops/mod.rs" \\
  || miss "missing critical file: src/ops/mod.rs"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 31 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~1d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/altsem/gitu"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Gitu is a terminal user interface (TUI) Git client written in Rust, inspired by Emacs Magit, that lets developers stage/unstage files and hunks, commit, branch, rebase, and perform complex Git operations without leaving the terminal. It prioritizes keyboard-driven workflows with Magit-like keybinds and renders in the terminal using Ratatui, bringing powerful Git porcelain operations to a modal TUI environment. Monolithic Rust binary with modular organization: src/git/ wraps libgit2 operations (commit, diff, merge_status, rebase_status, remote), src/menu/ handles TUI state and keybinding dispatch, src/items.rs and item_data.rs model the staged/unstaged/commit data structures, and src/app.rs orchestrates the main event loop; highlighting and diff rendering are pluggable via src/highlight.rs (tree-sitter-based) and src/gitu_diff.rs.

Git power users and Magit users who want a standalone terminal Git client outside of Emacs; developers who prefer keyboard-driven Git workflows and modal interfaces; contributors familiar with Rust TUI development who want to extend Git tooling.

Actively developed and production-ready: the repo is at v0.41.0 with solid CI/CD via GitHub Actions (build-artifacts, release, cachix), codecov integration showing test coverage, and a structured Changelog managed via cliff-toml. The codebase is substantial (~527KB Rust) with organized modules, though still evolving with features being added incrementally.

Moderate risk: single-maintainer project (altsem) with a large dependency tree (25+ tree-sitter language parsers pinned to specific versions, ratatui, git2, crossterm), making updates potentially brittle; tree-sitter grammars are pinned at exact versions (e.g., =0.25.6) rather than ranges, which can cause version conflicts. No obvious abandoned signal, but dependency churn is high and breaking changes in terminal libraries (ratatui) could affect stability.

Recent activity includes CI/CD stabilization (dependabot.yml, release.yml automating artifacts), configuration system refinement (config.rs, default_config.toml with TOML serialization via figment), file watcher integration (file_watcher.rs for live repo state), and syntax highlighting expansion (tree-sitter parsers for Rust, Python, Go, JavaScript, C, C#, Java, etc.).

git clone https://github.com/altsem/gitu.git
cd gitu
cargo build --release
./target/release/gitu

Optionally use Nix: nix develop (flake.nix present) or install via package managers listed in repology.

Daily commands: Dev mode: cargo run or cargo run -- --log-level debug. Release: cargo build --release && ./target/release/gitu. From Nix: nix run github:altsem/gitu. Tests: cargo test. Benchmarks: cargo bench --bench show.

• src/main.rs — Entry point that initializes the TUI application, sets up the event loop, and coordinates the main render/input flow.
• src/app.rs — Core application state machine that manages all UI screens, navigation context, and dispatches user actions to git operations.
• src/git/mod.rs — Wrapper around libgit2 that abstracts git operations; every git command flows through this module.
• src/screen/mod.rs — Screen trait and dispatch logic that defines how each view (status, log, show, blame) renders and handles input.
• src/ops/mod.rs — Git operation implementations (stage, commit, rebase, etc.); the concrete handlers for all user actions.
• src/items.rs — Item type definitions that represent selectable elements in each screen; fundamental to UI state and input handling.
• src/bindings.rs — Keybinding configuration and dispatch that maps user input to action handlers throughout the application.

Add a new git operation

1. Define a new variant in the Op enum in src/ops/mod.rs to represent the operation (src/ops/mod.rs)
2. Create a new module file (e.g., src/ops/my_operation.rs) with the operation logic using GitCtx (src/ops/my_operation.rs)
3. Add the module to src/ops/mod.rs with mod my_operation; and import it (src/ops/mod.rs)
4. Implement the handler in the Op::execute match block in src/ops/mod.rs (src/ops/mod.rs)
5. Map a keybinding in src/bindings.rs to trigger your Op variant (src/bindings.rs)
6. Add integration tests in src/tests/my_operation.rs that use the helpers in src/tests/helpers/ (src/tests/my_operation.rs)

Add a new screen view

1. Create a new screen module file (e.g., src/screen/custom_view.rs) implementing the Screen trait (src/screen/custom_view.rs)
2. Add the module to src/screen/mod.rs and define a variant in the Screen enum (src/screen/mod.rs)
3. Implement render() and handle_input() for your screen, returning appropriate Items and Actions (src/screen/custom_view.rs)
4. Add case handling in App::update() in src/app.rs to push the new screen when appropriate (src/app.rs)
5. Define Item variants in src/items.rs that represent selectable elements in your screen (src/items.rs)

Add a new keybinding or menu

1. Define keybinding sequences in src/default_config.toml under the appropriate menu section (src/default_config.toml)
2. Update src/bindings.rs to parse and dispatch the new keybinding to an Op or screen transition (src/bindings.rs)
3. If a new menu is needed, add variants to the menu types in src/menu/mod.rs (src/menu/mod.rs)
4. Update src/menu.rs to render the new menu UI based on the menu type (src/menu.rs)

Enhance diff/status parsing

1. Review current parsing in src/git/parse/status/mod.rs for status lines and src/git/diff.rs for diffs (src/git/parse/status/mod.rs)
2. Extend the Item or status data structures in src/items.rs and src/item_data.rs if new metadata is needed (src/item_data.rs)
3. Update rendering logic in the relevant screen (e.g., src/screen/status.rs or src/screen/show.rs) (src/screen/status.rs)
4. Add tests in src/tests/ to verify parsing correctness using the test helpers (src/tests/helpers/repo.rs)

• Rust + Cargo — Type safety, memory safety without GC, and performance suitable for a responsive TUI that wraps git operations.
• libgit2 (git2 crate) — Provides high-level git operations (stage/commit/rebase) without shelling out; enables fine-grained hunk-level manipulation.
• crossterm — Cross-platform terminal control (Windows, macOS, Linux) for raw input handling and TUI rendering.
• figment + TOML — Configuration management that lets users customize keybindings and UI options in a simple text format.
• arboard — Clipboard integration for copying commit hashes and other text without relying on OS-specific tools.
• chrono — Date/time formatting for commit metadata display in log and blame views.

Editor selection: Gitu checks VISUAL, EDITOR, then GIT_EDITOR env vars in that order (not reverse); if none are set, some operations will fail silently. Config paths are OS-specific: Linux/macOS use ~/.config/gitu/config.toml, Windows uses %USERPROFILE%\AppData\Roaming\gitu\config.toml; misconfigured paths won't error loudly. Tree-sitter grammars are pinned exactly: cargo will fail if a tree-sitter parser dependency has a breaking change; you cannot use cargo update blindly. libgit2 requires system deps: on some Linux distros, libgit2-dev or libssl-dev must be installed; build errors may be cryptic. File watcher uses notify crate: on systems with inotify limits (Linux), opening many repos can fail; set fs.inotify.max_user_watches.

• Hunk-level staging — Gitu's core differentiator is interactive staging of partial files (hunks and individual lines); understanding how diffs are parsed and selectively applied is essential to extending commit workflows.
• Tree-sitter syntax highlighting — Gitu uses tree-sitter (not regex) for multi-language diff syntax highlighting; contributors adding language support or modifying highlight colors must understand tree-sitter's incremental parsing model.
• libgit2 object model — All Git operations (commits, branches, diffs, rebases) flow through git2 bindings to libgit2; knowledge of commits as DAG nodes, OIDs, and reference resolution is needed to understand Gitu's git/ module.
• Modal TUI event loops — Gitu's architecture is a state machine with crossterm event polling driving menu transitions; understanding event-driven TUI patterns (modal vs stateful rendering) is critical for modifying keybind dispatch or adding new menu screens.
• Magit keybinding conventions — Gitu's default keybinds (s for stage, c for commit, r for rebase) are inherited from Emacs Magit; understanding Magit's command hierarchy helps contributors design intuitive extensions.
• Nom parser combinators — The status parser (src/git/parse/status/mod.rs) uses nom for declarative parsing of git status output; contributors fixing parser bugs or adding file metadata extraction need to know nom combinator syntax.
• TOML configuration deserialization — Gitu's config system uses serde + figment to load TOML files with type safety; extending config options (keybinds, colors, thresholds) requires understanding serde derive macros and figment's merge semantics.

• jesseduffield/lazygit — Go-based TUI Git client with similar scope (staging hunks, rebasing, stashing); primary alternative in the TUI Git space.
• rhysd/git-florist — Another Rust TUI Git client; overlapping feature set (staging, committing, branching) but different UI philosophy.
• magit/magit — The Emacs Magit project that inspired Gitu; reference implementation for Git porcelain UX and keybind conventions.
• ratatui-org/ratatui — The TUI framework Gitu depends on; understanding its architecture is essential for modifying Gitu's rendering and layout.
• libgit2/libgit2 — The C library underlying git2 crate that Gitu wraps; knowledge of libgit2 API helps debug Git operation issues.

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive unit tests for src/git/parse/status/mod.rs

The status parsing module is critical for parsing git status output, but there are no visible test files in src/git/parse/status/. Given the complexity of parsing git output across different git versions and configurations, this module needs robust test coverage. The repo uses insta for snapshot testing (in dev-dependencies), making it ideal for testing parser edge cases.

• [ ] Create src/git/parse/status/tests.rs with unit tests
• [ ] Add snapshot tests using insta for various git status outputs (merge, rebase, conflicted states)
• [ ] Test edge cases: renamed files, mode changes, submodules, unicode filenames
• [ ] Reference existing test patterns in src/git/parse/mod.rs if any exist
• [ ] Run 'cargo test' to verify coverage and update snapshots as needed

Add integration tests for core operations in src/ops/ module

The src/ops/ directory contains critical git operations (commit, rebase, merge, cherry_pick, etc.) but lacks visible integration tests. These operations directly modify git repositories, making them error-prone and good candidates for integration tests using temp-dir (already in dev-dependencies). This would catch regressions early.

• [ ] Create tests/integration_ops.rs for testing operations against temporary git repositories
• [ ] Add tests for key workflows: stage/unstage/commit, branch operations, rebase scenarios
• [ ] Use temp-dir crate to create isolated test repositories for each test
• [ ] Test error conditions: conflicted merges, failed operations, missing upstream
• [ ] Document any required git configuration or setup in tests/README.md

Add cargo-deny checks to CI and create security vulnerability scanning workflow

The repo has deny.toml in the root and codecov.yml configured, but the CI workflows (.github/workflows/ci.yml and others) don't show explicit cargo-deny or security scanning steps. With multiple tree-sitter dependencies and git2 bindings, security audits are important. A dedicated security workflow would catch vulnerable dependencies early.

• [ ] Review .github/workflows/ci.yml and add 'cargo deny check' step if missing
• [ ] Create .github/workflows/security.yml with cargo-deny and cargo-audit checks
• [ ] Configure deny.toml to block known vulnerabilities (already present, verify it's used)
• [ ] Add advisories check: 'cargo deny check advisories'
• [ ] Document security check requirements in docs/dev-tooling.md

• Add unit tests for src/git/parse/status/mod.rs: The status parser is critical for hunk-level staging but has no visible test coverage in the file list; write tests for edge cases like binary files, renamed files, and Unicode filenames.
• Document keybind customization in docs/: The bindings.rs and default_config.toml exist but there's no dedicated guide on how to remap keys; create a docs/keybindings.md with examples for Vim users and Emacs muscle-memory users.
• Add syntax highlighting for a missing language to src/highlight.rs: The repo already supports 12+ languages via tree-sitter but is missing common ones like Lua, Kotlin, Zig; add a new tree-sitter parser dependency and register it in the language dispatch logic.

Gitu's security posture is generally good for a TUI application. The codebase is a Git client in Rust, which inherently provides memory safety benefits. Key findings: (1) Dependency management has minor issues with exact version pinning and edition field misconfiguration that should be corrected; (2) git2 library has disabled default features which requires careful auditing; (3) No critical vulnerabilities detected in visible configuration; (4) Supply chain security practices appear minimal - recommend adding cargo-audit to CI/CD; (5) Shell script dependencies present minor risk if improperly handling Git operations. Overall, the project follows Rust security best practices but should strengthen supply chain security monitoring and dependency version management.

• Medium · Pinned Tree-Sitter Dependencies with Version Mismatch — Cargo.toml - dependencies section (tree-sitter-* packages). Tree-sitter language parser dependencies use exact version pinning (=X.Y.Z) but with inconsistent versions. tree-sitter and tree-sitter-highlight are pinned to 0.25.6, while most language parsers use 0.23.x versions. This creates potential API compatibility issues and maintenance burden. Additionally, pinning exact versions prevents security patch updates from being applied automatically. Fix: Use semantic versioning constraints (e.g., ^0.25.6 or ~0.25.6) to allow patch and minor version updates. Audit tree-sitter language parser versions for compatibility and consistency. Consider using a tool like 'cargo-audit' in CI/CD to automatically detect outdated dependencies.
• Medium · git2 Library with Default Features Disabled — Cargo.toml - git2 dependency. The git2 dependency explicitly disables default features (default-features = false). While this can reduce attack surface, it requires careful management of which features are actually enabled. The current configuration doesn't specify alternative features, which could lead to missing security patches or required functionality being unavailable. Fix: Explicitly list required git2 features instead of relying on defaults being disabled. Document why default features are disabled. Regular audits should verify that essential security features aren't accidentally disabled.
• Low · Arboard Dependency Windows-Specific Configuration — Cargo.toml - arboard dependency. The arboard clipboard library (v3.6.1) has default-features disabled and only enables 'windows-sys' feature. While this is likely intentional for Windows builds, it may cause compilation issues on non-Windows platforms or exclude important clipboard security features on other OSes. Fix: Use platform-specific dependencies in Cargo.toml (e.g., [target.'cfg(windows)'.dependencies]) instead of globally disabling features. Document the clipboard handling strategy across different platforms.
• Low · Edition Set to Future Year (2024) — Cargo.toml - package.edition field. The Cargo.toml specifies edition = '2024', which appears to be a non-standard or incorrect value. Current Rust editions are 2015, 2018, 2021. This may indicate a configuration error or typo that could cause unexpected behavior. Fix: Verify and correct the edition field to a valid Rust edition (2021 is recommended for current projects). This is likely a data entry error.
• Low · No SAST Configuration for Supply Chain Security — Repository root configuration. While deny.toml exists, there's no visible evidence of comprehensive supply chain security scanning. No lock file verification, license compliance checking beyond deny.toml, or SBOM generation is visible in the repository structure. Fix: Implement supply chain security best practices: use 'cargo-audit' in CI/CD, maintain deny.toml with specific vulnerable dependency rules, consider generating and tracking SBOMs, and enable dependabot rules validation in CI pipelines.
• Low · Shell Scripts with Potential Injection Risks — bump.sh, record.sh, Makefile. The presence of shell scripts (bump.sh, record.sh, Makefile) without visibility into their content poses potential security risks if they handle user input or git operations without proper escaping. Fix: Audit all shell scripts for proper input validation and escaping. Use shellcheck for static analysis. Consider replacing shell scripts with Rust equivalents for better type safety and security.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.