How to browse the history of a huge repository

Open gitty in the repository and press 2 for the History tab. The layout draws first and the commit rows stream in after it, so you can start reading before the whole history has loaded.

What you need: gitty installed and a large repository.

What draws first

gitty’s benchmark notes state the order: the UI draws its layout first and streams rows in afterwards. The README lists the first frame, with the layout drawn, at 14 ms. On a blobless clone of the Linux kernel, which has 1,484,291 commits, the first 500 history rows take 23 ms in the benchmark. Those were measured on Apple Silicon with a release build and a warm cache, so treat them as a sense of scale and not a promise for your machine.

The commit graph, which History shows by default, changes this on one kind of repository. With the graph on, the list is in git’s topological order, from git rev-list --topo-order. On a large repository without a commit-graph file, the first rows wait for git to sort the whole history, about a third of a second per 100,000 commits by the README’s figure. With a commit-graph file, which auto-tune writes, they show at once. L hides the graph and lists commits by date.

The notes also record that the first run after other disk activity is slower: with a cold page cache, reading the kernel’s 945 refs takes about 0.8 to 1.0 seconds. If the first open of a very large repository feels slower than the next one, the benchmark notes name a cold page cache as one cause.

What stays quick once rows are in

The README’s performance table also gives the cost of the work you do after the first screen. A full history walk of the kernel takes 225 to 258 ms against a budget of under 400 ms. A 220 by 60 frame showing history and a highlighted diff takes 0.5 ms, against a budget of under 16 ms. For a selected commit, the median time to build its file list is 0.12 ms and to produce a file diff is 0.19 ms. The benchmark notes also say the diff is drawn before highlighting finishes, and the colors arrive from a two-thread highlight pool, so a large diff shows up first and gets its colors a moment later.

Steps

Run gitty inside the repository.
Press 2 to open the History tab.
Move with j and k, or the arrow keys. Ctrl-d and Ctrl-u move half a page, Ctrl-f and Ctrl-b a whole page, and g and G jump to the first and last row.
Press r to change scope. The list switches between the current branch plus its upstream and every ref.
Select a commit. The panes beside the list show its files and a syntax-highlighted diff.
Press s to switch the diff between unified and split. Added and deleted files always use the full width.

Tab moves between panes, and ? shows every key. On a wide terminal, gitty turns split view on by itself at the width set by split_threshold, which defaults to 200, so s is only needed when you want the other layout.

What you should see: a commit list with refs, a commit graph, and ahead and behind marks, and for the selected commit a file list and a diff. The marks show what is ahead of or behind the upstream, and on a branch that has never been pushed, ↑ marks what pushing it would publish.

Tune the view

A few keys change how much fits on screen:

z changes row density, compact being the default.
L shows or hides the commit graph.
D changes the date format. The date_mode setting in your config takes relative, absolute or both.
o expands the commit header.
y copies the short SHA and Y the full SHA.
< and > shrink or grow the focused pane.

Your pane sizes, history scope and tree view are remembered per repository under ~/.local/state/gitty/.

If the repository still feels slow

The docs give one cause worth checking. On a repository with at least 10,000 commits or 20,000 index entries, gitty tunes git once in the background, writing a commit-graph among other things, unless auto_tune = false is set in your config. The guide Keep a git TUI fast on very large repositories explains what the commit-graph changes, with the figures from gitty’s own benchmark.

The History tab itself is described in Using gitty.