Skip to content
shieldsPublic

About

Git history viewer

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

ghist

An opinionated git log replacement, with a Unicode graph and Git’s own colors.

Behavior

ghist [-p|--patch] [--stat] [<rev>|<a>..<b>|<a>...<b>|^<rev>…] [--] [<path>…]

Git handles revision syntax, topological order, path filtering, mailmap, encodings, and diffs. SHA-1 and SHA-256 repositories, shallow clones, and replacement objects work as they do in git log.

Use -p or --patch for patches, --stat for a summary, or both. Merges show neither. Root commits show changes against the empty tree unless log.showRoot is false. Git’s diff algorithm, rename detection, and diff colors apply.

The other flags are -h/--help, --version, and --completions <bash|zsh>. There are no display flags.

Display

●─╮  sha1 3f2a9c1e5b7d9f0a2c4e6b8d0f1a3c5e7b9d1f3a (HEAD -> main)
│ │  Merge: a1b2c3d4e5f6789012345678901234567890abcd f4e5d6c7b8a90123456789012345678901234567
│ │  Author:     Grace Hopper <grace@example.com>
│ │  Commit:     Ada Lovelace <ada@example.com>
│ │  AuthorDate: 2026-10-04 09:12:44 -0400
│ │  CommitDate: 2026-10-05 20:41:13 -0700
│ │
│ │      Add the frobnicator
  • Full hashes are labeled sha1 or sha256. The part after Git’s abbreviation is dimmed. Abbreviations follow core.abbrev, including Git’s automatic default and no for full hashes. Merge parents also show full hashes with the same dimming.
  • Commit: appears only when the committer’s identity differs from the author’s after mailmap. CommitDate: appears only when the date or time zone differs. Dates retain each identity’s own time zone.
  • Decorations are always shown. Graph lanes use log.graphColors, or Git’s default palette. The graph always uses Unicode.
  • Stat widths account for the graph column. Terminal width comes from COLUMNS, the terminal, or 80 columns, in that order.
  • Message tab stops and stat filename alignment use ghist’s Unicode character widths, so their spacing can differ from Git’s.
  • Generated lines have no trailing whitespace. Patch bytes are preserved, including trailing whitespace and Git’s colors. Patch index lines use the same core.abbrev setting as commit headers.

Color follows Git’s configuration. NO_COLOR disables automatic color; explicit color.ui=always or color.diff=always still wins. Invalid color values are errors, including invalid log.graphColors entries.

When stdout is a terminal, the pager is $GIT_PAGER, then core.pager, then $PAGER, then less. An empty value or cat disables it. LESS=FRX and LV=-c are defaults only when those variables are unset. Git diagnostics appear after the pager exits. A failed pager returns an error; quitting a successful pager early, or piping into head, succeeds and prints only Git’s warnings.

Recommended usage

if command -v ghist >/dev/null 2>&1; then
    alias gl='ghist'
else
    alias gl='git log --graph --pretty=fuller --topo-order'
fi

Requires Git 2.29 or newer and a Unix system. Build and install from this checkout with make install. On large repositories, a commit graph can improve first-page latency:

git commit-graph write --reachable

Shell completions

For Bash, including macOS’s Bash 3.2, add this to ~/.bashrc:

source <(ghist --completions bash)

For Zsh, add this to ~/.zshrc after initializing completion:

autoload -Uz compinit
compinit
source <(ghist --completions zsh)

Completions include supported options, local branches, tags, remote refs, HEAD, revision ranges, exclusions, and filesystem paths. After --, only paths are offered. The scripts use Git directly and require no additional completion package. Generating a script works outside a Git repository.

Development

Install Bash, Zsh, Bun, Lefthook, and cargo-llvm-cov, then run:

bun install --frozen-lockfile
rustup toolchain install "$(make print-nightly)" --profile minimal --component llvm-tools-preview
lefthook install
make lint test coverage

rust-toolchain.toml pins stable Rust. Coverage uses the dated nightly in the Makefile and requires 100% line coverage. The pre-commit hook runs lint and coverage. make fmt formats Rust, documentation, and configuration files.

The generated differential tests compare output with Git. Run PROPTEST_CASES=1024 make test for the full milestone check, or set GHIST_DIFF_REPOS to a colon-separated list of local repositories for full history comparisons. The edge-case matrix records behavioral coverage; the design describes the protocol.

Run make bench BENCH_REPO=/path/to/repo with hyperfine installed to compare first page, full history, patches, and stats with Git.

BENCH_REV selects the patch/stat range and defaults to HEAD~100..HEAD. See the recorded benchmarks for timings and the release profile decision.

Publishing

make publish-dry-run packages a temporary copy of the current commit using gitcalver. It requires a clean checkout on the default branch. Install gitcalver with cargo install gitcalver --locked. make publish publishes that version.

The first publish is manual: crates.io Trusted Publishing cannot create a crate. After it exists, configure its trusted publisher for shields/ghist, workflow publish.yml, and environment release. See the crates.io setup instructions. Subsequent pushes to main run the full CI workflow before publishing with a short-lived OIDC token.

About

Git history viewer

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages