githop PoC

githop is a lightweight, local-first Rust desktop client for reviewing a Git worktree and turning line comments into a self-contained Markdown prompt for an AI.

Included

• Native iced UI with an asynchronous system folder picker
• Safe repository discovery when a repository root or one of its child folders is selected
• Read-only gix comparison between two points in one selected local branch
• Selectable branch-history points: branch tip and first-parent commits
• Changed files grouped by immediate parent path, with deterministic ordering, search, and viewed-file filtering
• Unified text diffs with full-width, multi-line drag selection and virtualized rendering
• Saved line comments, edit/delete/jump actions, viewed-file progress, and deterministic AI prompt export
• Explicit preview-only states for binary, oversized, mode-only, symlink, submodule, and unsupported changes
• Empty, loading, confirmation, cancellation, retry, and persistent error states
• Generation checks for stale async results and Canvas events
• Fixed snapshot indication after the app regains focus; use Refresh to capture current repository state

Rename similarity is deliberately not inferred in this first backend. A rename is displayed deterministically as one deleted path and one added path.

Run

cargo run --release

Choose Open repo, then select a Git worktree or a folder inside one. Use Cmd/Ctrl+O to open another worktree, Cmd/Ctrl+R to refresh the fixed snapshot, and Cmd/Ctrl+F to focus the changed-file filter. Choose a local branch in the top bar, then choose the From and To points from that branch's first-parent history. Selecting an earlier commit as From and a later commit as To shows only their cumulative result, without exposing intermediate commit states. Working Tree is not exposed as a comparison point. The initial comparison is the tip's first parent → tip; root and unborn branches start at tip → tip. Click any selectable diff line for one line, or drag vertically from anywhere on the code row to select a range. Selecting a new range replaces the current draft; saved comments remain intact. Escape and Cancel discard only the active draft. Use Shift + wheel for horizontal scrolling.

Changed Files groups each file under one full immediate-parent path, following the compact changeset-list pattern used by dedicated diff clients. For example, sample/ui/src/views/settings/profile/page.rs appears under the single group sample/ui/src/views/settings/profile, not as one row per directory component. Root files remain ungrouped. Added, deleted, and modified states remain visible as file badges without splitting the list into change-type categories. Search rebuilds the visible parent-path groups. Hide viewed removes completed files and reports how many files the active filter and viewed filter hide.

Changing the branch or either comparison point, refreshing, or opening another repository never silently carries line anchors into a new snapshot. A dirty draft blocks the operation, and saved comments or viewed state require confirmation before they are cleared. Refresh preserves the selected branch and both points; opening another repository starts from its current branch's first parent → tip comparison.

Comparison and safety boundary

• From → To is a direct comparison of two selected contents in one local branch. The tip and commit points use their exact trees. No merge-base or merge- parent transformation is applied.
• Selecting an earlier commit and a later commit is equivalent to comparing their two trees directly: changes that appeared and disappeared only in intermediate commits are absent from the final review diff. To include the From commit itself, choose its parent as the From point.
• Commit choices follow only the selected branch's first-parent chain. A merge commit can be selected as one point, but its additional parents are not shown as pseudo-points.
• Selecting the same fixed history point as both From and To produces an empty diff.
• Branch and history discovery is local-only and bounded. Remote-tracking branches are not selectable, and githop never fetches.
• Branch-history comparisons do not mix in the index or worktree.
• Repository refs, index, and worktree are never written.
• Network fetches, credentials, telemetry, Git hooks, and nested-submodule traversal are not used.
• Reviewed repository metadata, source excerpts, and comments are not persisted by githop; Markdown leaves the application only through an explicit user copy action.
• Repository-configured clean/process filters and external diff drivers are disabled.
• Safe built-in Git normalization, such as CRLF handling, is still applied.
• Tracked paths below a worktree symlink are not followed; type changes stay preview-only.
• Git paths retain byte-exact identity; non-UTF-8 bytes are escaped only for display.
• A changing repository is rejected rather than returning a knowingly mixed snapshot; retry after it settles.

The PoC bounds repository processing to 20,000 changed paths, 10,000 rendered files, 4 MiB per source, 64 MiB total source data, 100,000 rendered rows per file, 250,000 rows overall, and 200,000 input lines per text comparison. Content outside these limits is shown as preview-only instead of being loaded into the diff canvas. Discovery retains at most 64 ordinary local branch candidates plus the selected and checked-out contexts, and 128 first-parent commits for the selected branch, with an 8 MiB aggregate commit-metadata budget. Tree-to-tree traversal additionally limits each tree object to 4 MiB, aggregate tree data to 64 MiB, and recursive tree lookups to 20,000.

Submodule worktrees are not opened in this version. A staged gitlink change is shown as preview-only, while changes made only inside a submodule require a future submodule-aware backend.

Typography and licenses

Diffs, repository paths, line anchors, and AI prompt previews use the bundled JetBrains Mono NL 2.304 Regular font. The NL variant keeps source operators literal instead of applying programming ligatures. Prose controls retain the default sans-serif UI font, with the existing platform CJK fallback for Japanese text.

JetBrains Mono is distributed under the SIL Open Font License 1.1 and may be bundled in commercial and non-commercial applications. The unmodified font, its complete license, source version, and checksum are recorded in THIRD_PARTY_NOTICES.md. Application packaging must ship that notice and assets/fonts/jetbrains-mono/OFL.txt with the binary.

Architecture

The application uses Rust responsibility objects and explicit state machines:

• ReviewSession owns the immutable snapshot and saved review transitions.
• DraftEditor owns the idle/new/editing draft lifecycle.
• RepositoryLoad owns folder-pick, confirmation, loading, cancellation, retry, and failure states.
• The backend modules own safe repository discovery, status planning, bounded content loading, and diff projection.
• DiffPaneState owns metrics, scrolling, focus, and drag cancellation state.
• diff_view owns transient Canvas pointer capture and virtualized painting.
• typography owns the embedded code font and its stable iced family handle.
• MarkdownExporter owns deterministic Markdown projection.
• GithopApp remains the iced message and cross-object effect composition root.

Unit-test bodies live in module-adjacent child files such as src/model/tests.rs; production files contain only #[cfg(test)] mod tests;. The repository-root tests/ directory is reserved for future black-box tests of a public library or executable boundary.

See AGENTS.md for dependency direction, invariants, validation gates, and commit granularity.

Validate

git diff --check
cargo fmt --check
cargo test --all-targets --all-features
cargo clippy --all-targets --all-features -- -D warnings
cargo build --release

Deferred

• Persisting and restoring review sessions
• Re-anchoring comments across changed snapshots
• Exact/fuzzy rename presentation
• Submodule worktree inspection
• Split diffs and GitHub synchronization