gittui

A modern terminal git client built with TypeScript, Solid.js, and OpenTUI. Covers the full git workflow — working tree, branches, commits, stash — plus GitHub PR integration via the gh CLI.

Features

• Files & Diff — Stage/unstage files and individual hunks, commit with message, discard changes, unified and split diff view
• Branches — List local/remote, checkout, create, delete, merge, rebase, filter by local/remote/all
• Commits — Log with detail view, cherry-pick, revert, filter by author/message/path
• Stash — Save, apply, pop, drop, view stash content as diff
• Pull Requests — List PRs, view detail with files/reviews/comments, submit reviews (approve/request changes/comment), merge (squash/merge/rebase), open in browser. Requires gh CLI
• Command palette — : to search and execute any action
• Help overlay — ? to see all keybindings for the current context
• Configurable — TOML config, vim/emacs presets, custom keybindings, 4 built-in themes
• First-run welcome — Guided keybinding overview on first launch

Installation

Homebrew (macOS / Linux)

brew tap rsbmk/gittui https://github.com/rsbmk/gittui
brew install gittui

curl (macOS / Linux)

curl -fsSL https://raw.githubusercontent.com/rsbmk/gittui/main/scripts/install.sh | sh

To install to a custom directory:

GITTUI_INSTALL_DIR=~/.local/bin curl -fsSL https://raw.githubusercontent.com/rsbmk/gittui/main/scripts/install.sh | sh

npm

# Requires Bun runtime to be installed (bin entry points to TypeScript source)
npm install -g @rsbmk1/gittui

Build from Source

Requires Bun v1.3+.

git clone https://github.com/rsbmk/gittui.git
cd gittui
bun install

# Run directly
bun run dev

# Compile a standalone binary
bun run build           # Binary for current platform → ./gittui

Build targets: darwin-arm64, linux-arm64, linux-x64. The compiled binary is self-contained — no Bun or Node.js needed to run it.

Usage

gittui              # Open in current directory
gittui /path/to/repo  # Open in a specific repository
gittui --help       # Show help
gittui --version    # Show version

gittui must be run inside a git repository.

Keybindings

Global

Key	Action
1 - 5	Switch tab (Files, Branches, Commits, Stash, PRs)
j / k	Move down / up
Tab	Switch between sidebar and main panel
Ctrl+b	Toggle sidebar
:	Command palette
?	Help overlay
q	Quit

Files

Key	Action
Space	Stage / unstage file (in sidebar) or stage hunk (in main panel)
a	Stage all files
c	Commit staged changes
d	Discard changes
n / p	Next / previous hunk

Branches

Key	Action
Enter	Checkout branch
n	Create new branch
d / D	Delete / force delete branch
m	Merge selected into current
r	Rebase current onto selected
f	Cycle filter: local / remote / all

Commits

Key	Action
Enter	View commit detail (files + diff)
c	Cherry-pick commit
r	Revert commit
Esc	Close detail view

Stash

Key	Action
Enter	View stash content
s	Save new stash
a	Apply stash
p	Pop stash
d	Drop stash

Pull Requests

Key	Action
Enter	View PR detail
r	Submit review
m	Merge PR
o	Open in browser
v	View file diff
f	Cycle filter: open / closed / all
Esc	Close detail view

All keybindings are customizable — see Configuration.

Configuration

gittui stores its config at ~/.config/gittui/config.toml. A default file is created on first launch.

[general]
theme = "catppuccin-mocha"     # Theme name (built-in or custom)
sidebar_width = 30
sidebar_collapsed = false
default_tab = "files"          # files | branches | commits | stash | prs

[keybindings]
preset = "vim"                 # vim | emacs | custom

[keybindings.custom]
# Override individual actions:
# stage = "s"
# commit = "ctrl+c"

[diff]
view = "unified"               # unified | split
context_lines = 3
word_diff = false
show_line_numbers = true

[github]
auto_fetch_prs = true

Themes

Four built-in themes: catppuccin-mocha (default), default-dark, nord, tokyo-night.

Custom themes are JSON files placed in ~/.config/gittui/themes/<name>.json:

{
  "name": "My Theme",
  "colors": {
    "bg": "#1e1e2e",
    "fg": "#cdd6f4",
    "accent": "#89b4fa",
    "success": "#a6e3a1",
    "warning": "#f9e2af",
    "error": "#f38ba8",
    "muted": "#6c7086",
    "border": "#45475a",
    "selection": "#313244",
    "diff_add_bg": "#1a3a2a",
    "diff_del_bg": "#3a1a1a",
    "diff_add_fg": "#a6e3a1",
    "diff_del_fg": "#f38ba8"
  }
}

Then set theme = "my-theme" in your config.

Requirements

• git — any recent version
• gh (optional) — GitHub CLI for the Pull Requests tab. Install and run gh auth login to authenticate

Development

bun install                # Install dependencies
bun run dev                # Run with hot reload
bun test                   # Run all tests (81 tests)
bun run typecheck          # TypeScript strict mode check

Project Structure

src/
  index.ts              # CLI entry point
  app.tsx               # Root component
  core/                 # Business logic (no UI imports)
    git/                # Git CLI wrappers, parsers, types
    github/             # GitHub CLI wrappers, parsers, types
    config/             # TOML config schema, defaults, loader
  ui/                   # Solid.js + OpenTUI components
    components/         # Reusable: file tree, commit list, PR cards, etc.
    layout/             # App shell: sidebar, status bar, keybindings, global keys
    views/              # One per tab: files, branches, commits, stash, PRs
  state/                # Solid signals + stores
  lib/                  # Utilities: shell, logger, perf, theme
scripts/                # Build + install scripts

Tech Stack

Component	Choice
Runtime	Bun
Language	TypeScript (strict mode)
UI Framework	Solid.js
TUI Renderer	OpenTUI
Git Backend	git CLI via Bun.spawn()
GitHub	gh CLI
Config	TOML (smol-toml)

License

MIT