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 · Installation · 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 the installed git executable for repository inspection and repository mutations
• Uses the installed git executable in both runtime operations and repository test fixtures
• Covers status, branch inspection, recent commit review, checkout, switch, branch creation, clone, fetch, 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 local repository snapshot is being loaded

Installation

gitrex requires Git and a Rust toolchain with Cargo. The recommended installation uses Cargo directly from this repository and installs the executable as gitrex.

macOS

1. Make sure Git is available. macOS can provide it through the Xcode Command Line Tools:

   xcode-select --install

2. Install Rust with rustup if cargo is not already available:

   curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
   source "$HOME/.cargo/env"

3. Install GitRex:

   cargo install --git https://github.com/MarcosAlves90/gitrex --locked gitrex

4. Run it from any Git repository:

   gitrex

Linux

1. Install Git with your distribution package manager and verify that it is available:

   git --version

2. Install Rust with rustup if cargo is not already available:

   curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
   source "$HOME/.cargo/env"

3. Install GitRex:

   cargo install --git https://github.com/MarcosAlves90/gitrex --locked gitrex

4. Run it from any Git repository:

   gitrex

Windows

1. Install Git and Rust with winget if they are not already available:

   winget install --id Git.Git --source winget
   winget install --id Rustlang.Rustup --source winget

   If rustup offers to install the MSVC prerequisites, install them so Rust has the linker and Windows SDK required to build the executable. Reopen PowerShell after installation so the updated PATH is loaded.

2. Install GitRex:

   cargo install --git https://github.com/MarcosAlves90/gitrex --locked gitrex

3. Run it from any Git repository:

   gitrex

gitrex is installed but not found

Cargo installs command-line binaries in ~/.cargo/bin on macOS/Linux and %USERPROFILE%\.cargo\bin on Windows. If cargo install reports that GitRex is already installed but the shell returns command not found, add Cargo's binary directory to PATH.

For zsh on macOS or Linux:

grep -qxF 'export PATH="$HOME/.cargo/bin:$PATH"' ~/.zshrc \
  || echo 'export PATH="$HOME/.cargo/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
rehash

For bash on Linux:

grep -qxF 'export PATH="$HOME/.cargo/bin:$PATH"' ~/.bashrc \
  || echo 'export PATH="$HOME/.cargo/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
hash -r

Verify the installation:

command -v gitrex
gitrex

For PowerShell on Windows:

$cargoBin = Join-Path $HOME '.cargo\bin'
$userPath = [Environment]::GetEnvironmentVariable('Path', 'User')
if (($userPath -split ';') -notcontains $cargoBin) {
    [Environment]::SetEnvironmentVariable('Path', "$cargoBin;$userPath", 'User')
}
$env:Path = "$cargoBin;$env:Path"
Get-Command gitrex
gitrex

The PowerShell command updates the current session immediately and adds Cargo's binary directory to the user PATH for future terminal sessions.

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[Git process adapter]
  F --> G
  G --> H[System Git]
  H --> I[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 keeps repository status visible as an informational panel and provides two navigable views:

• [1] Branches
• [2] Graph

Status remains visible but does not receive keyboard focus because it has no panel-specific actions.

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 focuses branches and 2 focuses the graph; the same numbers are shown in their panel titles
• 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 workspace

Press 2 to open a dedicated graph workspace. The branch/status panels are replaced by the graph and a selected-commit inspector so the available terminal area is used for history analysis.

• j/k or ↑/↓ move one commit at a time
• PageUp/PageDown move by the currently visible graph page
• Home/End or g/G jump to the first or last commit
• ←/→ pan a long selected commit subject manually; the graph never auto-scrolls text
• Enter opens commit actions for the selected commit
• The selected-commit panel shows the full subject, author, date, full hash, and graph scope
• The graph follows the branch or remote ref selected in the Branches view
• Wide terminals place commit details beside the graph; narrower terminals stack details below it
• Date/hash columns disappear progressively on narrow terminals to preserve the graph lanes and commit subject

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 fetch [remote]	Explicitly refreshes and prunes remote-tracking refs
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
• system Git for repository inspection and mutation execution
• system Git for repository test fixtures
• 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.
• Read-only commands and TUI snapshots do not perform network I/O implicitly.
• Run gitrex fetch when you want to refresh remote-tracking refs explicitly.
• Explicit pulls are fast-forward-only and reject diverged histories without moving local HEAD.
• Captured Git commands disable terminal credential prompts and rely on configured credential helpers or agents.