FAQ

Why gitoui?

The honest answer: the obvious name, gitui, was already taken. And since I’m French, and we obviously love baguettes, I went with the next best thing: stitch a oui to the end of git. Voilà, gitoui. A small bilingual joke that doubles as a tagline, the project says yes to a fuller TUI workflow.

How do I pronounce gitoui?

/ʒi.tu.i/, like the French word gitoui would be if you stitched “git” and “oui” together. The “oui” half is the French word for “yes”, the project says yes to a fuller TUI workflow.

If IPA doesn’t help: roughly zhee-too-ee.

Can gitoui replace lazygit / gitui?

Different focus. lazygit and gitui are full git operations toolkits, every command surface is interactive. gitoui starts from “I want to read history and review changes” and adds the operations that fit naturally on top of that: stage, commit, rebase, resolve conflicts, review PRs.

Use gitoui if your daily flow is read-heavy with frequent reviews + some editing. Use lazygit/gitui if you want to drive every git command through the TUI.

Why is Alt+letter not firing on my system?

gitoui pushes the Kitty keyboard protocol’s DISAMBIGUATE_ESCAPE_CODES flag at startup, that makes Alt+letter arrive as a single KeyEvent on supporting terminals (Kitty, Ghostty, WezTerm, foot, Konsole 22.04+, …). Older terminals treat Alt as a meta-prefix and send Esc followed by the letter; usually crossterm combines them, but if the bytes drift apart you end up firing Cancel (Esc) before the letter arrives.

If your terminal doesn’t speak the protocol, switch to Ctrl+... for your custom bindings, see Custom keybindings.

My Help page still shows the default after rebinding a key

Help is computed from your live config at render time. If the displayed key is wrong:

1. Check your config validated, gitoui prints a styled diagnostic at startup if there’s an error.
2. Make sure you’re on the right config file (GITOUI_CONFIG_FILE env variable might be overriding the default location).
3. Some glyphs in the Help page are intentionally symbolic, Esc, ↑↓, Enter, Tab, Space, #. These don’t follow rebinds (only the action’s behaviour moves, not the label).

Where do my settings live?

Path	What
~/.config/gitoui/config.toml	Main config.
~/.config/gitoui/themes/<name>.toml	Custom theme files.
~/.config/gitoui/github_token.toml	OAuth token (mode 0600).
~/.cache/gitoui/avatars/	Avatar PNG cache.
~/.cache/gitoui/<repo-hash>/commits.bin	Commit history cache. Speeds up subsequent launches by avoiding a full git log walk. Invalidated automatically when HEAD moves or sort order changes. Clear manually with gitoui -C.
~/.config/gitoui/logs/	Daily-rotating debug log files.

Set GITOUI_CONFIG_FILE to point at a different file. The themes folder and cache always live next to the config.

Can I disable the image protocol?

gitoui --graph-renderer ascii uses Unicode box-drawing characters for the commit graph and skips avatar rendering. The result looks like a slightly fancier git log --graph and works in any terminal.

My terminal scrambles the graph after I exit

gitoui pops the Kitty keyboard protocol on exit, but inline image placements (Kitty / iTerm2) sometimes linger if you exit via a crash or SIGKILL. Press Ctrl+L in your shell to clear the screen, that flushes the stale placements.

Does gitoui send any data to a server?

There is no telemetry, no analytics and no crash reporting. These are the network requests it makes:

• Update check (on by default). At most once every 24 hours, and only when started in an interactive terminal, gitoui sends GET https://crates.io/api/v1/crates/gitoui to read the latest version. Nothing else is sent. If a newer version exists and you installed with the curl script, it also checks with a HEAD request that the matching archive is published on GitHub Releases. Nothing is installed without your answer at the prompt, and Homebrew installs are never prompted. Turn it off with --no-update-check or check_updates = false under [core.option] (answering N at the prompt sets it for you). gitoui --update checks on demand.
• GitHub, only after you sign in. Sign-in uses GitHub’s device flow. Once signed in, gitoui calls api.github.com for the repository’s GitHub remote: when you open the Pull Requests or Issues views, and to show author avatars in the commit list, blame, file history and commit details (it asks GitHub which account authored a commit, then downloads that avatar). Avatars are cached on disk. Set github_avatars = false under [core.option] to stop avatar requests; the ASCII renderer never loads them.
• git itself. Fetch, pull and push run the git CLI against your remotes. gitoui also runs git fetch --all in the background after a commit, stash, push or tag made from the UI, and fetches a pull request’s commit from GitHub when you open one that isn’t available locally.
• install.sh (not the binary). After a real install or update, the script sends one GET to an install counter that only stores a running total. Set GITOUI_NO_TRACK=1 to skip it.

Is gitoui stable enough to use on real repos?

It’s daily-driven on the gitoui repo itself and on a few sandboxes. Pre-v1.0 means the config schema and some keybinds may still shift, your .toml config might need touches when you upgrade. The on-disk git operations are all plain git CLI calls, no libgit2, so worst-case gitoui never corrupts state; it just produces an error you’d see from git directly.

What’s the license?

MIT. See LICENSE.