How to use gitui: install, stage hunks and commit from the terminal

Install gitui

The simplest route depends on your system. On macOS you can use Homebrew, and the README also lists packages for Arch Linux, Fedora, openSUSE, Windows (Winget, Scoop, Chocolatey) and several others.

If no package fits, you can build from source with Cargo. The README states the minimum supported Rust/cargo version is 1.88, and building the openssl dependency needs perl 5.12 or newer and a C compiler.

• Requirements for building from source: Rust/cargo 1.88 or newer
• Perl 5.12 or newer and a C compiler (msvc, gcc or clang) for the openssl dependency

Start gitui in a repository

Change into a git repository and run gitui. It opens a terminal interface for that repository. The README says GitUI is keyboard-only, and that its context-based help shows the keys available where you are, so you do not have to memorise every hotkey.

To write diagnostic logs, start it with the logging flag. The README lists where the log file is stored on each system.

• Keyboard-only control; the in-app help lists keys for the current screen
• Run gitui -l to enable logging

Review, stage and revert changes

The main use is reviewing your working changes and choosing what goes into a commit. You can stage or unstage files, and also individual hunks or lines. The README names this as one of the features it prioritises, because doing it on the git shell is awkward.

You can also revert or reset files, hunks and lines. Check the diff before reverting, since the change cannot be recovered from gitui itself.

• Stage and unstage whole files
• Stage individual hunks or lines
• Revert or reset files, hunks and lines
• Inspect and amend changes, including hooks such as pre-commit and commit-msg

Commit, branch, stash and browse history

Once staged, you commit from the same interface. The feature list also covers amending commits, push and fetch to and from remotes, and creating, renaming, deleting and checking out branches.

Stashing supports save, pop, apply, drop and inspect. The log tab lets you browse and search commits and view the diff of a committed change. Submodules are supported, and gpg commit signing works with shortcomings noted in the README.

• Commit and amend
• Push and fetch to or from a remote
• Branch list: create, rename, delete, checkout, remotes
• Stash: save, pop, apply, drop, inspect
• Search the commit log and view committed diffs

Know the limits before you rely on it

The README is direct that gitui does not fully replace the git shell, and the two work well together. Interactive rebase and git-lfs are not yet supported, and sparse checkouts are not supported. Https credential helpers must be configured explicitly.

The project also describes itself as beta, which is useful to know before using it for critical work. For tasks outside its feature list, keep the git shell open next to it.

• No interactive rebase yet (listed on the roadmap to 1.0)
• No git-lfs support
• No sparse repo support
• credential.helper for https must be set explicitly

Customise the colour theme

gitui is meant to work on both light and dark terminal themes automatically. The README says you can also customise the colours to your liking, and points to a separate guide for the theme format.