⠀⠀⠀⣴⣀⣤⣦⣤⣤⣀⡀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀
⠀⢠⣴⠿⠛⣿⣿⠋⠻⣿⣟⠻⠿⠿⢿⣿⣿⣶⣶⡦⣤⣀⡀⠀
⢰⣿⣧⣴⣦⢿⣿⣷⡦⠘⣿⠀⠀⠀⠀⣹⠉⣿⣿⣿⣶⣬⣷⠀
⠘⠟⢻⣿⠋⠀⢿⣿⣷⣼⣿⣷⣤⣤⣴⣿⣿⣿⣿⣿⣿⣿⢿⠃
⠀⠀⢠⣿⣶⣶⣿⣿⣿⣿⠟⠉⠉⠙⠻⠟⡿⢻⢿⢻⡏⠏⠀⠀
⠀⣾⣿⣿⣿⣿⣿⣿⣿⣧⣤⣀⡀⠀⠀⠀⠁⠈⠘⠈⠀⠀⠀⠀
⠀⠈⠉⠳⣾⣿⣿⣿⣿⣿⣿⣿⣿⣦⣶⣄⢠⢰⣴⢠⠀⣄⠀⠀
⠀⠀⠀⠀⠈⠙⠿⣿⣝⣿⣿⣿⣿⣿⣿⣿⣿⣾⣿⣿⣷⡟⠀⠀
⠀⠀⠀⠀⠀⠀⠀⠈⠙⠛⠛⠛⠛⠛⠛⠛⠛⠻⠿⠟⠋⠀⠀⠀

gitrex

A terminal-first git manager written in Rust.
Interactive terminals open the TUI by default. Non-interactive runs stay on the CLI path.

Overview · Architecture · TUI · Commands · Development

Overview

gitrex packages the common git workflows into one terminal tool:

• Defaults to the TUI when both stdin and stdout are terminals
• Falls back to CLI output for scripts, pipes, and automation
• Uses an embedded libgit2 backend, so it does not depend on the git binary
• Covers status, branch inspection, recent commit review, checkout, switch, branch creation, clone, pull, and push
• Includes a branch-focused TUI with local/remote panels, branch search, branch deletion confirmation, branch-specific graph navigation, and commit actions
• Shows a loading splash while the repository snapshot is being synchronized

Architecture

flowchart TD
  A[User starts gitrex] --> B{Interactive terminal?}
  B -- yes --> C[TUI router]
  B -- no --> D[CLI commands]
  C --> E[App state + controller]
  D --> F[Command output]
  E --> G[libgit2 backend]
  F --> G
  G --> H[Repository]

Loading

sequenceDiagram
  participant U as User
  participant R as Router
  participant T as TUI
  participant C as CLI
  participant G as GitClient

  U->>R: run gitrex
  R->>R: detect interactive terminal
  alt interactive without subcommand
    R->>T: open TUI
    T->>G: refresh / branch / log operations
  else subcommand given
    R->>C: execute command
    C->>G: read or mutate repository
  end

Loading

TUI

The TUI is built around three top-level views:

• Status
• Branches
• Graph

flowchart LR
  H[Header] --> S[Status]
  H --> B[Branches]
  H --> G[Graph]
  B --> L[Local branches]
  B --> R[Remote branches]
  G --> C[Commit actions]
  B --> X[Delete confirmation]
  H -. help (h) .-> O[Help overlay]
  O --> M[Message]

Loading

Navigation

• 1/2/3 switch between status, branches, and graph
• j/k or arrow keys move within the active panel
• h opens the help screen
• Esc or h closes the help screen
• r refreshes the repository state

Branches view

• Tab and Shift+Tab switch between local and remote branch panels
• / opens branch search and filters both local and remote refs
• Enter opens the branch action picker for the active panel
• In the local branch panel, branch actions include checkout, switch, pull, push, and creating a branch from the selected source
• In the local branch panel, branch actions also include deleting the selected local branch after confirmation
• In the remote branch panel, branch actions include creating a local branch, checking out detached HEAD, or deleting the selected remote branch after confirmation

Graph view

• j/k or arrow keys move between commits
• Enter opens commit actions for the selected commit
• The graph follows the selected branch in the Branches view
• The selected commit subject scrolls when it does not fit

Help screen

The help screen is scrollable:

• j/k or ↑/↓ scroll the shortcuts panel
• A scrollbar shows position and range
• The bottom Message panel stays fixed and shows the close hint

Commands

Command	Description
gitrex	Opens the TUI in interactive terminals
gitrex status	Prints the current branch, upstream, divergence, and working tree state
gitrex branch	Lists remote branches grouped by remote and local branches with sync status
gitrex log --limit <n>	Shows recent commits from the current branch history, defaulting to 20
gitrex checkout <target>	Checks out an existing branch or ref
gitrex switch <target>	Switches to a branch
gitrex create-branch <name> --from <target>	Creates a new branch, optionally from another ref
gitrex clone <repository> [directory]	Clones a repository to an optional destination
gitrex pull [remote] [branch]	Pulls updates from a remote and branch
gitrex push [remote] [branch]	Pushes commits to a remote and branch
gitrex tui	Forces the TUI explicitly

Example Output

branch: main
upstream: origin/main
working tree: clean

remote branches:
  origin
    main
    feature/login
  upstream
    main
local branches:
* main [synced: origin/main, upstream/main]
  feature/login [local-only]
  release [local-only]

Quick Start

Build

cargo build --release

Run the TUI

cargo run

To force the TUI explicitly:

cargo run -- tui

Run a CLI command

cargo run -- status
cargo run -- branch
cargo run -- log --limit 20

Development

Build

cargo build

Test

cargo test

Project context

• Repository rules live in CONTEXT.md
• Format guidance lives in CONTEXT-FORMAT.md

Tech Stack

• Rust 2021
• clap for CLI parsing
• crossterm for terminal control
• git2 with vendored libgit2 for repository access
• chrono for date formatting
• ratatui for the TUI
• anyhow and thiserror for error handling

Notes

• The CLI path prints a help hint when no subcommand is provided outside an interactive terminal.
• The TUI is the primary interactive experience.
• The TUI refreshes remote refs before reading status, branches, and history so the snapshot stays consistent.