# Gitwig - Project Instructions
## Project Overview
Gitwig is a Rust-based Terminal User Interface (TUI) for Git, aiming to provide a SourceTree-like experience in the terminal.
## Core Mandates
- **Performance:** Must be fast even in large repositories.
- **Reliability:** Git operations must be safe and atomic.
- **Intuitive UI:** Navigation should be familiar to users of SourceTree and other Git GUIs.
## Tech Stack
- **Language:** Rust (Edition 2024)
- **TUI Framework:** `ratatui` (0.30) with the `crossterm_0_29` feature, paired with `crossterm` 0.29 for terminal control and input events.
- **Git Backend:** `git2` (libgit2 bindings), default features off — used for both the per-card status indicator (`inspect_summary`) and the on-demand Detail view (`inspect_detail`). Both paths share a single `collect_summary` helper inside `gitwig-core/src/lib.rs` (the `gitwig-core` crate is re-exported as `repo` from `src/lib.rs`).
- **Configuration:** TOML based. Editable in-app — the UI persists adds/edits/deletes back to the file it loaded from.
## Architectural Patterns
- **State Management:** Clear separation between Git state and UI state.
- **Home Cursor vs. Open Repository:** `App.selected_index` indexes the grouped home rows, which reorder under it. Inside a repository view, identify the repository with `App::active_repo_item()`, open one with `App::open_repo(item)`, and rename one through `App::migrate_repo_path` (see `.agent/INSTRUCTIONS.md` §2).
- **Async Operations:** Long-running Git commands (fetch, clone, large diffs) should not block the UI thread.
- **Component-based UI:** Use modular widgets for different views (History, Working Tree, Branches).
- **Modal Input:** Keystroke meaning is mode-dependent (`Normal`, `Adding`, `Editing`, `ConfirmDelete`, `Help`, `Detail`, `DetailHelp`, `CommitInput`, `BranchCreateInput`, `CommitHistoryPicker`, `TagCreateInput`, `TagOverwriteConfirm`, `BranchDeleteConfirm`, `BranchPushConfirm`, `TagDeleteConfirm`, `TagPushConfirm`, `TagPushAllConfirm`, `StashDeleteConfirm`, `StashApplyConfirm`, `StashCreateInput`, `StashingUI`, `RemotePicker`, `CommitSearchInput`, `BranchMergeConfirm`, `BranchMergeIntoConfirm`, `BranchRebaseConfirm`, `BranchInteractiveRebaseConfirm`, `DiscardChangesConfirm`, `Inspect`, `Settings`, `DebugLogs`, `ImportUrlInput`, `ImportDestInput`, `ImportNameInput`, `BulkAddInput`, `SearchColumnPicker`, `RemoteAddNameInput`, `RemoteAddUrlInput`, `RemoteDeleteConfirm`, `Logs`, `LogsSearchInput`, `BranchCheckoutConfirm`, `TagCheckoutConfirm`, `CommitCheckoutConfirm`, `ForgeCheckoutConfirm`, `RepoSearchInput`, `MergeAbortConfirm`, `MergeContinueConfirm`, `About`, `CherryPickConfirm`, `RevertConfirm`, `FileHistory`, `LabelInput`, `RepoSettings`, `LabelSettings`, `UpdateConfirm`, `WorktreeAddBranchInput`, `WorktreeAddPathInput`, `WorktreeLockReasonInput`, `WorktreeRemoveConfirm`, `Overview`, `SubmoduleAddUrlInput`, `SubmoduleAddPathInput`, `SubmoduleDeleteConfirm`, `Legend`, `RepoJump`, `LabelPicker`, `RepoScanPicker`, `BulkAddScanPicker`, `BranchSearchInput`, `FileSearchInput`, `ForgeCommentPathInput`, `ForgeCommentLineInput`, `ForgeCommentBodyInput`, `CommitFuzzySearch`, `TagSearchInput`, `AddCwdRepoConfirm`, `AddRepoLabelInput`, `BulkAddRepoLabelInput`, `CloneRepoLabelInput`, `GlobalSearch`, `NotGitRepo`, `StatsDashboard` — `pub enum Mode` in `src/app/mod.rs` is authoritative; `Adding` is `#[allow(dead_code)]` and never entered). The status bar always reflects the current mode so the user can recover orientation at a glance.
- **Single-responsibility modules:**
- `src/main.rs` & `src/bin/gtg.rs` (binary entrypoints)
- `src/lib.rs` (shared application entrypoint orchestrating terminal setup and the main loop)
- `src/terminal.rs` (terminal initialization, restore guard, panic hook, CLI checking)
- `src/terminal_session.rs` (embedded terminal panel's PTY session: shell spawn, reader thread, key encoding, child cleanup)
- `src/app/` (application state and orchestration split into `mod.rs`, `actions.rs`, `git.rs`, `workspace.rs`, `navigation.rs`, `term_panel.rs`, and `tests.rs`)
- `src/ui/` (main rendering in `draw.rs` / `ui_detail.rs`, theme in `style.rs`, layout helpers, scrollbar, syntax highlighting)
- `src/tabs/`, `src/popups/`, `src/components/` (componentized UI event handling and drawing logic)
- `src/input.rs` & `src/mouse.rs` (event routing dispatchers)
- `src/keybindings.rs` (data-driven `Action` / `KeybindingsConfig` registry; `src/keys/` is a legacy table kept under `#![allow(dead_code)]`)
- `src/config.rs` (TOML load/save/migration) and `src/state.rs` (usage state in `state.toml`)
- `src/queue.rs`, `src/stats.rs`, `src/git_cmd.rs`, `src/debug_log.rs`, `src/fetch_error.rs` (internal event queue, usage statistics, hardened git subprocesses, debug log, fetch-error classification)
- `gitwig-core` workspace crate (all repository inspection, isolated from UI dependencies)
- **Code Reuse & Readability:** Code duplicate blocks should be refactored into reused helper functions; large/complex functions should be broken down into smaller components (under ~50 lines).
## Development Workflow
- Follow the Roadmap in `.agent/ROADMAP.md`.
- Ensure all new features and code changes are accompanied by test cases.
- Use `cargo fmt` and `cargo clippy` before every commit, and `make test` (`cargo test --workspace`, both crates).
- Keep documentation, READMEs, help overlays, legends, and shortcuts in lockstep with code — see `.agent/INSTRUCTIONS.md` for the rule.
## Agent Resources
Detailed instructions and roadmap for AI agents can be found in the `.agent/` directory,
including reusable workflow skills in `.agent/skills/`. Claude Code mirrors these at
`.claude/skills/`, the only path it auto-discovers — keep both in sync.