Technical Documentation: gitui-org/gitui

ℹ️ Provenance: Multi-Tier Ingestion · CodeWiki Reference

Overview (`README.md`) Copy Section

GitUI provides you with the comfort of a git GUI but right in your terminal

Table of Contents Copy Chapter

1. Features
2. Motivation
3. Benchmarks
4. Roadmap
5. Limitations
6. Installation
7. Build
8. FAQs
9. Diagnostics
10. Color Theme
11. Key Bindings
12. Sponsoring
13. Inspiration
14. Contributing
15. Contributors

1. Features ^{[Top ▲](#table-of-contents)} Copy Chapter

• Fast and intuitive keyboard only control
• Context based help (no need to memorize tons of hot-keys)
• Inspect, commit, and amend changes (incl. hooks: pre-commit,commit-msg,post-commit,prepare-commit-msg)
• Stage, unstage, revert and reset files, hunks and lines
• Stashing (save, pop, apply, drop, and inspect)
• Push / Fetch to / from remote
• Branch List (create, rename, delete, checkout, remotes)
• Browse / Search commit log, diff committed changes
• Responsive terminal UI
• Async git API for fluid control
• Submodule support
• gpg commit signing with shortcomings (see #97))

2. Motivation ^{[Top ▲](#table-of-contents)} Copy Chapter

I do most of my git work in a terminal but I frequently found myself using git GUIs for some use-cases like: index, commit, diff, stash, blame and log.

Unfortunately popular git GUIs all fail on giant repositories or become unresponsive and unusable.

GitUI provides you with the user experience and comfort of a git GUI but right in your terminal while being portable, fast, free and opensource.

3. Benchmarks ^{[Top ▲](#table-of-contents)} Copy Chapter

For a RustBerlin meetup presentation (slides) I compared lazygit,tig and gitui by parsing the entire Linux git repository (which contains over 900k commits):

4. Road(map) to 1.0 ^{[Top ▲](#table-of-contents)} Copy Chapter

These are the high level goals before calling out 1.0:

• visualize branching structure in log tab (#81)
• interactive rebase (#32)

• no git-lfs support (see #2812)

5. Known Limitations ^{[Top ▲](#table-of-contents)} Copy Chapter

• no sparse repo support (see #1226)
• credential.helper for https needs to be explicitly configured (see #800)

Currently, this tool does not fully substitute the git shell, however both tools work well in tandem.

The priorities for gitui are on features that are making me mad when done on the git shell, like stashing, staging lines or hunks. Eventually, I will be able to work on making gitui a one stop solution - but for that I need help - this is just a spare time project for now.

All support is welcomed! Sponsors as well! ❤️

6. Installation ^{[Top ▲](#table-of-contents)} Copy Chapter

GitUI is in beta and may contain bugs and missing features. However, for personal use it is reasonably stable and is being used while developing itself.

Various Package Managers Copy Section

Install Instructions

[Arch Linux](https://archlinux.org/packages/extra/x86_64/gitui/)

sudo pacman -S gitui

Fedora

sudo dnf install gitui

Gentoo

Available in dm9pZCAq overlay

sudo eselect repository enable dm9pZCAq
sudo emerge --sync dm9pZCAq
sudo emerge dev-vcs/gitui::dm9pZCAq

[openSUSE](https://software.opensuse.org/package/gitui)

sudo zypper install gitui

Homebrew (macOS)

brew install gitui

[MacPorts (macOS)](https://ports.macports.org/port/gitui/details/)

port install gitui

[Winget](https://github.com/microsoft/winget-pkgs/tree/master/manifests/s/StephanDilly/gitui) (Windows)

winget install gitui

[Scoop](https://github.com/ScoopInstaller/Main/blob/master/bucket/gitui.json) (Windows)

scoop install gitui

[Chocolatey](https://chocolatey.org/packages/gitui) (Windows)

choco install gitui

[Mise](https://github.com/jdx/mise)

mise use -g gitui@latest

[Nix](https://search.nixos.org/packages?channel=unstable&show=gitui&from=0&size=50&sort=relevance&query=gitui) (Nix/NixOS)

Nixpkg

nix-env -iA nixpkgs.gitui

NixOS

nix-env -iA nixos.gitui

[Termux](https://github.com/termux/termux-packages/tree/master/packages/gitui) (Android)

pkg install gitui

[Anaconda](https://anaconda.org/conda-forge/gitui)

conda install -c conda-forge gitui

Release Binaries Copy Section

Available for download in releases

Binaries available for:

Linux

• gitui-linux-x86_64.tar.gz (linux musl statically linked)
• gitui-linux-aarch64.tar.gz (linux on 64 bit arm)
• gitui-linux-arm.tar.gz
• gitui-linux-armv7.tar.gz

All contain a single binary file

macOS

• gitui-mac.tar.gz (arm64)
• gitui-mac-x86.tar.gz (intel x86)

Windows

• gitui-win.tar.gz (single 64bit binary)
• gitui-win.msi (64bit Installer package)

Nightly Builds Copy Section

see NIGHTLIES.md

7. Build ^{[Top ▲](#table-of-contents)} Copy Chapter

Requirements Copy Section

• Minimum supported rust/cargo version: 1.88

  • See Install Rust

• To build openssl dependency (see https://docs.rs/openssl/latest/openssl/)

  • perl >= 5.12 (strawberry perl works for windows https://strawberryperl.com/)
  • a c compiler (msvc, gcc or clang, cargo will find it)

• To run the complete test suite python is required (and it must be invocable as python)

Cargo Install Copy Section

The simplest way to start playing around with gitui is to have cargo build and install it with cargo install gitui --locked. If you are not familiar with rust and cargo: Getting Started with Rust

Cargo Features Copy Section

trace-libgit

enable libgit2 tracing

works if libgit2 built with -DENABLE_TRACE=ON

this feature enabled by default, to disable: cargo install --no-default-features

8. FAQs ^{[Top ▲](#table-of-contents)} Copy Chapter

see FAQs page

9. Diagnostics ^{[Top ▲](#table-of-contents)} Copy Chapter

To run with logging enabled run gitui -l.

This will log to:

• macOS: $HOME/Library/Caches/gitui/gitui.log
• Linux using XDG: $XDG_CACHE_HOME/gitui/gitui.log
• Linux: $HOME/.cache/gitui/gitui.log
• Windows: %LOCALAPPDATA%/gitui/gitui.log

10. Color Theme ^{[Top ▲](#table-of-contents)} Copy Chapter

gitui should automatically work on both light and dark terminal themes.

However, you can customize everything to your liking: See Themes.

11. Key Bindings ^{[Top ▲](#table-of-contents)} Copy Chapter

The key bindings can be customized: See Key Config on how to set them to vim-like bindings.

12. Sponsoring ^{[Top ▲](#table-of-contents)} Copy Chapter

13. Inspiration ^{[Top ▲](#table-of-contents)} Copy Chapter

• lazygit
• tig
• GitUp
  • It would be nice to come up with a way to have the map view available in a terminal tool
• git-brunch

14. Contributing ^{[Top ▲](#table-of-contents)} Copy Chapter

See CONTRIBUTING.md.

15. Contributors ^{[Top ▲](#table-of-contents)} Copy Chapter

Thanks goes to all the contributors that help make GitUI amazing! ❤️

Wanna become a co-maintainer? We are looking for you!

Overview (`asyncgit/README.md`) Copy Section

asyncgit

allow using git2 in an asynchronous context

This crate is designed as part of the gitui project.

asyncgit provides the primary interface to interact with git repositories. It is split into the main module and a sync part. The latter provides convenience wrapper for typical usage patterns against git repositories.

The primary goal however is to allow putting certain (potentially) long running git2 calls onto a thread pool.crossbeam-channel is then used to wait for a notification confirming the result.

In gitui this allows the main-thread and therefore the ui to stay responsive.

Overview (`filetreelist/README.md`) Copy Section

filetreelist

This crate is designed as part of the gitui project.

filetreelist provides a very common functionality of gitui: lists of files visualized as a tree. It allows efficient iteration of only the visual (non collapsed) elements and change the tree state correctly given well defined inputs like Up/Down/Collapse.

It is the main driver behind the file tree feature:

Overview (`git2-hooks/README.md`) Copy Section

git2-hooks

adds git hook functionality on top of git2-rs

todo Copy Chapter

• unittest coverage symlinks from .git/hooks/<hook> -> X
• unittest coverage ~ expansion inside core.hooksPath

Overview (`git2-testing/README.md`) Copy Section

git2-testing

convenience functions on top of git2-rs for convenient unittest repository generation

Overview (`invalidstring/README.md`) Copy Section

invalidstring

just for testing invalid string data

This crate is part of the gitui project. We need this to be a separate crate so that asyncgit can remain forbidding unsafe.

Overview (`scopetime/README.md`) Copy Section

scopetime

log runtime of arbitrary scope

This crate is part of the gitui project and can be used to annotate arbitrary scopes to trace their execution times via log:

in your crate:

[dependencies]
scopetime = "0.1"

in your code:

fn foo(){
    scope_time!("foo");

    // ... do something u wanna measure
}

the resulting log looks something like this:

19:45:00 [TRACE] (7) scopetime: [scopetime/src/lib.rs:34] scopetime: 2 ms [my_crate::foo] @my_crate/src/bar.rs:5

--- METRICS ---

• Files Extracted: 7
• Estimated Token Budget: ~3184 tokens
• Canonical Reference: https://codewiki.google/github.com/gitui-org/gitui