gitgraph-tui (ggraph)

Terminal git client: a VS Code Git Graph-style commit graph as the big left panel, with lazygit-style Status / Files / Branches / Pull Requests panels stacked on the right. Stage and commit, branch, merge, rebase, reset, revert, cherry-pick, tag and manage stashes — GitKraken-style, in any terminal (Warp, Windows Terminal, …).

+--------------------------------------------+------------------+
| [1] Commits                                | [2] Status       |
|  ●─╮ (HEAD -> develop) Merge PR #303  18h  +------------------+
|  │ ● (origin/tho-233) Place enriched  19h  | [3] Files        |
|  ●─┤ Merge PR #302                    20h  +------------------+
|  │ ● (origin/tho-232) fix(data-…)     21h  | [4] Branches     |
|                                            | [5] Pull Requests|
+--------------------------------------------+------------------+

Features

• Git Graph-style commit graph — HEAD marker, an uncommitted-changes ghost row, and stashes shown inline.
• Stage & commit — per file and per hunk, amend, discard; commit from any panel.
• History & branches — merge, rebase, reset (soft/mixed/hard), revert, cherry-pick; create/delete/rename branches; create/delete/push tags.
• Interactive rebase editor — reorder + pick / reword / edit / squash / fixup / drop.
• Visual conflict resolution — resolve each hunk with ours / theirs / both, then continue.
• Commit & changes detail — two-pane file list + per-file diff, GitKraken-style.
• GitHub Pull Requests via the gh CLI — checkout, diff, review (approve / comment / request changes / merge / close).
• Auto-refresh — changes made in other terminals show up on their own.

Requirements

• Node.js ≥ 20
• git on your PATH
• (optional) GitHub CLI (gh), authenticated, for the Pull Requests panel — everything else works without it.

Install

Install globally from npm:

npm install -g gitgraph-tui
ggraph            # run inside any git repository

Or run it once without installing:

npx gitgraph-tui

Update to the latest version later with npm update -g gitgraph-tui (or npm install -g gitgraph-tui@latest).

The GitHub CLI (gh) is optional — only the Pull Requests panel uses it. Everything else (the graph, staging, commit, branches, merge, rebase, conflict resolution, …) works without gh.

ggraph doctor
gh auth login
gh auth status

Install gh if needed:

winget install GitHub.cli
# or
scoop install gh

macOS:

brew install gh
gh auth login

From source:

npm install
npm run build
npm link        # puts `ggraph` on your PATH

Use

Run ggraph inside any git repository.

| Key | Action | | --- | --- | | 1 2 3 4 5 | focus Commits / Status / Files / Branches / Pull Requests | | Tab | cycle focus | | R | open repository list | | b 0 | cycle branch filter / show all | | ↑ ↓ j k, PgUp PgDn, g G | move / page / jump | | Enter | Commits: open detail · Files: open changes detail · Branches: checkout · PRs: checkout | | Space | (Files) stage / unstage selected file | | a | (Files) stage all / unstage all | | c C | commit / amend — from any panel | | d D | (Files) discard file / discard all | | x | context menu for the selection (commit / branch / stash / in-progress op) | | m | (Branches) merge selected branch into current | | f | (Branches) git fetch --all --prune | | d | (Pull Requests) show PR diff | | o | (Pull Requests) open PR in browser | | v | (Pull Requests) open review view | | + | fullscreen focused panel | | h | toggle HEAD focus mode | | p | pull current branch | | P | push menu (current branch / all tags) | | s S | stash push / stash pop | | Enter v | (Status, in-progress) open the visual conflict resolver | | r | refresh | | ? | help | | Esc | close menu / view / fullscreen / diff / help | | q | quit |

Detail view (two panes): Enter on a commit opens a GitKraken-style detail — a file list on the left and the selected file's diff on the right (header shows subject · author · date · hash · parents). Tab (or ←/→) switches focus between panes; j/k move the file (files pane) or the hunk (diff pane); Esc returns. On narrow terminals the two panes stack vertically.

Enter on the Uncommitted changes row (or on a file in the Files panel) opens the same view for your working tree, with per-hunk staging: s stages the selected hunk, u unstages it, [/] (or v) toggle the unstaged↔staged side, Space stages/unstages the whole file, and c commits the staged index. Staging writes a reconstructed one-hunk patch through git apply --cached (no whole-file all-or-nothing).

Working tree: in the Files panel, Space stages or unstages the selected file, a toggles staging for everything, and d / D discard a file or the whole working tree. c (commit the staged index) and C (amend, prefilled with the last message) work from any panel; if nothing is staged, c tells you what to do instead of failing. All destructive actions ask for confirmation.

Status & hints: the bottom line always shows the keys that work in the currently focused panel (it changes as you move focus with 1-5/Tab). Action feedback appears there as a short toast — cyan for success, red for errors — and disappears by itself after a few seconds.

History & branch actions (x context menu): like right-clicking in GitKraken, x opens a menu whose contents depend on what is selected:

• on a commit — reset HEAD here (soft / mixed / hard), revert, cherry-pick, tag, create a branch there, start an interactive rebase from it, or push its tag.
• on a branch — merge into current, rebase current onto it, rename, or delete (offers a force delete when the branch isn't merged).
• on a stash row — apply, pop, or drop.
• on the Status panel while a merge / rebase / cherry-pick is in progress — continue, abort, or skip.

Interactive rebase (x → i on a commit; base = that commit): a full-screen editor lists the commits base..HEAD newest-first. Set an action per commit with p pick, r reword, e edit, s squash, f fixup, d drop; reorder with K / J; Enter runs it, Esc cancels. When git stops for a reword you get a message prompt (Enter saves, Esc keeps the original); for an edit it drops to the main view so you can stage changes, then continue with x → continue on the Status panel. Conflicts open the visual resolver automatically.

Visual conflict resolution: when a merge / rebase / cherry-pick stops on conflicts, press Enter (or v) on the Status panel — during a rebase it opens on its own. Per hunk choose o ours, t theirs, or b both (O / T take a whole file); move with j / k, switch files with Tab / [ / ]. w writes the resolved file and stages it; once everything is resolved, c continues (or a aborts). You can still resolve by hand in the Files panel instead — staging a file with Space marks it resolved.

Push tags: P opens a push menu (current branch or all tags); x on a tagged commit can push that tag directly.

Flags: --ascii (plain ASCII glyphs), --print N (dump N graph rows to stdout, no TUI), --no-watch (disable auto-refresh).

Pull Requests: the PR panel uses the GitHub CLI (gh) when it is installed and authenticated. Without gh, the rest of the TUI still works and the PR panel shows setup guidance. Run ggraph doctor to verify Git and GitHub CLI setup.

HEAD focus mode: enabled by default. The graph jumps to HEAD after checkout/refresh, highlights the current branch lane, and dims commits outside the checked-out branch history. Press h to toggle it.

Repo and branch focus: ggraph discovers Git repositories near the current workspace, including nested repos up to a small depth. Use R to open the repository list, b to cycle local branch filters, and 0 to return to Show All.

Safe Git actions: pull, stash push/pop and every destructive history action (hard reset, discard, revert, cherry-pick, branch delete, rebase/merge abort, …) ask for y/N confirmation before running.

In PR review view, use Tab or 1-4 for Summary / Files / Commits / Checks. Actions are a approve, c comment, R request changes, m merge, and x close. Review and merge actions ask for confirmation or a comment before running gh.

Auto-refresh: every 2s the app polls a cheap repo fingerprint (HEAD, status, refs, stashes) and reloads the view only when something changed — commits, edits, stashes or checkouts made in other terminals show up by themselves, like in VS Code Git Graph.

Graph markers (Git Graph-style)

• ◉ — the commit HEAD points to.
• ○ Uncommitted changes (N files) — gray ghost row above the graph when the working tree is dirty, linked to HEAD by a dashed gray lane (┆). Enter opens the two-pane changes detail (file list + diff + per-hunk staging).
• ◆ (stash@{N}) — each stash shown right above the commit it was created on. Enter shows the stash diff.

Development

Requires Node.js ≥ 20 and git.

git clone https://github.com/daanjiri/gitgraph-tui.git
cd gitgraph-tui
npm install

npm run dev          # run from source (tsx), inside any git repo
npm test             # vitest unit tests (parsers, layout, ops, hints, hunks, …)
npm run type-check   # tsc --noEmit
npm run it           # real-git integration: rebase, conflicts, per-hunk staging
npm run build        # bundle to dist/cli.js (tsup)
npm link             # optional: put your local `ggraph` on your PATH

Contributions welcome — open an issue or PR at https://github.com/daanjiri/gitgraph-tui. npm run type-check && npm test should pass before you push (they also run automatically on npm publish).

License

MIT