graft

README

graft

A read-first, graph-first terminal Git navigator inspired by Git Graph.

Features

• Full-terminal git log --graph view with preserved graph connector lines, colored long-lived branch identities, refs, subjects, relative time, and author.
• Composable graph filters for message, branch, tag, author, and path.
• Fuzzy branch/tag completion in filter mode.
• Vim-style graph search with /, n, and N.
• Keyboard and mouse commit navigation.
• Enter/click a commit to expand changed files inline.
• Enter/click a file to expand a high-performance inline side-by-side diff below it.
• Shift-J / Shift-K, Shift-Down / Shift-Up, PgUp / PgDn, or mouse wheel over the diff scrolls the inline diff.
• o opens the selected file diff in a full-screen internal diff view.
• f in full-screen diff toggles between changed hunks and full-file context.
• Full-file diff mode shows a horizontal change minimap with viewport position and add/delete/modify markers.
• W in full-screen diff toggles whitespace-error highlighting.
• Shift-J / Shift-K in full-screen diff jumps between change occurrences.
• Esc returns from full-screen diff to the graph.
• c on two commits compares A..B and shows changed files/diffs for that range.

Requirements

• Go 1.22+
• git
• delta for side-by-side diffs

If delta is missing, graft falls back to a unified git diff.

Install

Install the latest public release with:

go install github.com/BananaBites/graft@latest

Make sure Go's bin directory is on your PATH:

export PATH="$HOME/go/bin:$PATH"

go install puts the binary at $(go env GOPATH)/bin/graft, usually ~/go/bin/graft.

For a specific release/tag:

go install github.com/BananaBites/graft@v0.1.0

Update to the latest tagged release:

graft --update-to-latest-release

Update to the latest main branch version:

graft --update-to-latest-version

Usage

Run graft inside a Git repository:

graft

Or start in a specific repository/path:

graft /path/to/repo

Other command-line options:

graft --version
graft --update-to-latest-release
graft --update-to-latest-version
graft --completion bash

# delta theme/syntax-theme helpers
graft --show-delta-themes
graft --list-delta-syntax-themes
graft --delta-theme colibri
graft --delta-syntax-theme GitHub --delta-light

Update commands require Go and Git. They print the installed version and the exact target before installing.

Delta themes and persistent config

Diff rendering is powered by delta, so graft can pass through delta themes and syntax themes:

graft --delta-theme colibri              # delta feature/theme
graft --delta-syntax-theme GitHub        # syntax highlighting theme
graft --delta-syntax-theme GitHub --delta-light
graft --delta-dark

--delta-theme <name> auto-detects built-in syntax themes such as GitHub; for clarity you can use --delta-syntax-theme <name> explicitly.

To persist the current theming options, add --save-config:

graft --delta-syntax-theme GitHub --delta-light --save-config

This writes a small config file and exits. The path is printed, for example:

wrote config: /home/alice/.config/graft/config
delete this file to reset, or edit it manually

The config location follows Go's os.UserConfigDir():

• Linux: $XDG_CONFIG_HOME/graft/config or ~/.config/graft/config
• macOS: ~/Library/Application Support/graft/config
• Windows: %AppData%\graft\config

Command-line theme options override saved config values.

Note on Go pseudo-versions

If you install from main, Go may report a version like:

v0.1.3-0.20260625130521-36b652797525

This does not mean there is a v0.1.3 tag. It is a Go pseudo-version for an untagged commit after v0.1.2. It sorts after v0.1.2 and before a future real v0.1.3 tag. Once v0.1.3 is tagged, that real release is newer than any preceding v0.1.3-0... pseudo-version.

Shell completion

Optional shell completion can be installed after graft is available on your PATH.

# bash
mkdir -p ~/.local/share/bash-completion/completions
graft --completion bash > ~/.local/share/bash-completion/completions/graft

# zsh
mkdir -p ~/.zfunc
graft --completion zsh > ~/.zfunc/_graft
printf '\nfpath=(~/.zfunc $fpath)\nautoload -Uz compinit && compinit\n' >> ~/.zshrc

# fish
mkdir -p ~/.config/fish/completions
graft --completion fish > ~/.config/fish/completions/graft.fish

Restart your shell afterwards. You can also just print a completion script with:

graft --completion bash
graft --completion zsh
graft --completion fish

Run from source

go mod tidy
go run .

Filtering

Press : to enter filter mode. Filters are composable; each accepted filter narrows the graph further.

:fix bug          # default: commit message grep
:msg fix bug
:branch main     # fuzzy-completes branches with Tab
:tag v1.0        # fuzzy-completes tags with Tab
:author hannes
:path main.go
:pop             # remove last filter
:clear           # clear all filters

F toggles branch/tag filters between:

• history: show commits reachable from the branch/tag
• decor: match branch/tag names in rendered decorations

Press / for a lightweight search within the currently visible graph, then n / N for next/previous match.

Full-screen diff

Press o on a selected file to open the full-screen diff.

• f toggles between hunk-only and full-file context.
• In full-file mode, a map line below the diff shows change locations across the file:
  • green = additions
  • red = deletions
  • yellow = modifications or mixed changes
  • solid bar = current viewport, colored when it overlaps a change
• Shift-J / Shift-K jumps between change occurrences.
• W toggles delta whitespace-error highlighting, useful for spotting trailing whitespace and other whitespace-only changes.

Comparing commits

1. Move to the first commit and press c to mark compare A.
2. Move to the second commit and press c to mark compare B.
3. The inline file list shows changes for A..B.
4. Open a file with Enter, or press o for full-screen diff.

Keys

Key	Action
↑/↓, k/j	Navigate commits/files; scroll full-screen diff
g / G	Jump to top / bottom in graph and full-screen diff
/	Search visible graph text; n/N jump next/previous
:	Add graph filter: branch main, tag v1, msg fix, author name, path file
Tab	Complete branch/tag while entering a filter
F	Toggle branch/tag filters between history mode and decoration-match mode
Enter, Space, click	Expand commit or file
Shift-J / Shift-K, Shift-Down / Shift-Up, PgUp / PgDn	Scroll inline diff
o	Open selected file diff full-screen
f	Toggle full-screen diff between hunks and full file
W	Toggle whitespace-error highlighting in full-screen diff
Shift-J / Shift-K, Shift-Down / Shift-Up	Jump between changes in full-screen diff
Esc	Back out / return from full diff
c	Mark compare commit A, then B
x	Clear compare
r	Reload graph
:clear	Clear graph filters
:pop	Remove last graph filter
q, Ctrl-C	Quit