CLI options

gitoui [OPTIONS]

gitoui reads everything it needs from the current working directory and the config file. The flags here are the rare cases where you want to override defaults for one specific run.

Flag	Default	Effect
-n, --max-count <NUMBER>	500	How many commits are visible in the first frame at startup. The background loader walks the full history in parallel regardless of -n and keeps appending until every reachable commit is loaded. Cap this only to influence the initial paint.
-r, --graph-renderer <TYPE>	auto	Force a graph renderer, one of auto, ascii, kitty, iterm, kitty-unicode, sixel. auto detects at startup. ascii renders with Unicode box-drawing characters.
-o, --order <TYPE>	chrono	Commit ordering algorithm. chrono (date-based) or topo (git log --topo-order).
-g, --graph-width <TYPE>	auto	Graph image cell width. auto / single / double.
-s, --graph-style <TYPE>	smooth	Graph edge style. rounded / angular / smooth.
-i, --initial-selection <TYPE>	latest	Cursor position on open. latest, head, or top.
--update		Force an update check + prompt now, then exit. Bypasses the once-a-day silent check and the “never ask” preference.
--no-update-check		Skip the once-a-day automatic update check at startup.
-C, --clear-cache		Delete the on-disk commit cache for the current repo, then exit. Next launch re-walks git log from scratch. Useful when the cache appears stale or to reclaim disk space.
--why		Why gitoui? Prints the short answer (with a little animation in a terminal), then exits.
-h, --help		Print help and exit.
-V, --version		Print version and exit.

Examples

Huge repo

Cap the foreground load to keep startup snappy. The full history walks in a background thread regardless of -n, ships commits back in batches, and keeps going until every reachable commit has been appended. Your cursor, scroll position, and search state stay put across appends:

gitoui -n 200

-n only controls how much is visible in the very first frame; the background streamer pays no attention to it and always loads the whole history. There is no manual “load more” gesture.

Reset the cache

If the on-disk commit cache for this repo looks stale or corrupt, or you just want to reclaim disk space, wipe it and exit. The next normal launch re-walks git log from scratch:

gitoui -C

Force a graph renderer

When auto picks the wrong renderer on a custom terminal:

gitoui --graph-renderer sixel
gitoui --graph-renderer kitty
gitoui --graph-renderer iterm
gitoui --graph-renderer ascii   # Unicode box-drawing, no images

Open on HEAD

Cursor lands on HEAD instead of the newest commit:

gitoui -i head

Topo order

Walk history topologically (parents before children) instead of by date:

gitoui --order topo

Environment

Variable	Effect
GITOUI_CONFIG_FILE	Override the config file path (skips the XDG lookup).
XDG_CONFIG_HOME	Base directory for the config + themes + token.
NO_COLOR	Honored by the --help output and by the no-repo error splash.

Tip

CLI flags override the corresponding [core.option] config keys for a single run. To persist a choice, set it in ~/.config/gitoui/config.toml see the config schema.