gitlimes
limes — the fortified frontier of the Roman empire; the line that shows you where the borders ran.
A fast, low-memory CLI for asking a git repository what happened and who did it.
○ d98c4b9 7m Ondrej Martinek (HEAD -> main) merge: branches and who
├─╮
│ ● ef98597 7m Ondrej Martinek feat(cmd): add branches and who
│ ● ad98623 12m Ondrej Martinek chore: force lf line endings
├─╯
○ b2621f3 14m Ondrej Martinek merge: log command
Why
git log is fast but hard to scan. TUIs like tig and lazygit are good but hold state and
take over the terminal. GitHub needs a browser and a network round trip. gitlimes prints a
readable, coloured answer and exits.
Install
Prebuilt binaries for Linux, macOS and Windows are attached to each
release. Download, extract, put gitlimes on
your PATH.
From crates.io:
cargo install gitlimes
From source:
git clone https://github.com/Drew-lgtm/gitLimes
cd gitLimes
cargo build --release
The binary lands in target/release/gitlimes and needs git on PATH. Tip: alias limes=gitlimes.
Documentation
- Man page —
man/gitlimes.1. Bundled in every release archive. Read it without installing it withman ./man/gitlimes.1, or install it for good:sudo cp man/gitlimes.1 /usr/local/share/man/man1/ sudo mandb # or: sudo makewhatis, on some systems - tldr page —
tldr/gitlimes.md: the handful of commands most people reach for first, in tldr-pages format. Not yet part of the upstreamtldr-pages/tldrrepository; until it is, view it withtldr --render tldr/gitlimes.md(thetldr-node-clientsupports--renderon a local file) or just read it directly. - Every command's own
--helpis the fastest reference and always matches the binary you're running, since it's built from the same source. The man page and tldr page are maintained by hand alongside it and cover the same options in more depth.
Commands
gitlimes log coloured commit history
gitlimes branches branch overview with age, tracking and staleness
gitlimes who author and contribution stats
gitlimes graph unicode branch graph
Every command takes --help and --json. --color / --no-color and --pager / --no-pager
override tty detection; NO_COLOR, GITLIMES_PAGER and PAGER are honoured.
NO_COLOR disables colour when set to a non-empty value, so NO_COLOR= cancels an inherited
setting rather than silently stripping colour. A pager setting may be a bare command with
arguments (less -S), a path containing spaces (C:\Program Files\Git\usr\bin\less.exe), or both
if the path is quoted. The pager only starts once there is something to write, so a command that
fails never opens one over the top of git's error message.
log
gitlimes log [REV] [-n N] [--author PAT] [--since DATE] [--oneline] [-- PATH...]
Short hash, age, author, ref decorations, subject. Filters are passed straight through to git.
branches
gitlimes branches [-a] [--stale DAYS] [--vs REF]
Sorted by last commit. Ahead/behind comes free from the tracked upstream; --vs REF compares
against an arbitrary branch instead, in the same single git process via %(ahead-behind:)
(git 2.41+, with a per-branch fallback on older versions).
who
gitlimes who [PATH] [--since DATE] [--limit N] [--lines]
Commits per author with share, first and last seen, and an activity sparkline. Authors
are keyed by email, so one person committing under several names stays one row — and the email
column shows which identity it is. Pass a path to ask who owns a directory. --lines adds
added/removed line counts and is opt-in because it roughly doubles the work git has to do.
The sparkline spans the whole history rather than a fixed recent window, so a repository that went quiet years ago still shows its shape. Its scale adapts - the header says what one block is worth - because the span is not known until the oldest commit is read, and remembering every timestamp to find it would make memory scale with history. Instead the buckets start one day wide and double whenever a commit falls off the left edge.
graph
gitlimes graph [REV] [-n N] [-a] [--ascii]
Filled dots are ordinary commits, hollow dots are merges. Each branch keeps one colour for its
whole life, even as it changes column. --ascii for terminals without box-drawing characters.
Below the eviction limit described next, every parent-child edge git reports is drawn, correctly
and unambiguously — no edge is ever lost or invented. What is not guaranteed is git's own
exact column layout: gitlimes assigns each new lane the leftmost free column and only folds two
lanes together once their literal shared commit is reached, so on some multi-branch histories it
opens a lane, or takes an extra row to close one, in a different place than git log --graph
would. The commit graph itself always ends up correct; the picture of it can differ, usually by
being more compact — where git needs three rows to untangle a crossing merge, the box-drawing
form often needs one — but occasionally the reverse.
One honest limitation. A lane is retired when the commit it waits for arrives, and the table is capped at 64 lanes so it cannot grow without bound. Past that cap the stalest lane is dropped, and with it an edge — so the drawing stops being exact in the stronger sense: an edge is actually missing, not just laid out differently. Two things reach it:
- A commit filter (
--author,--since, a path, or a shallow clone). git still reports each commit's real parents, but the filter hides some of them, so lanes are opened for commits that will never arrive. - More than 64 branches genuinely open at once, which an unfiltered
--allcan reach on a repository with many active branches.
When it happens, gitlimes says so on stderr rather than passing a sketch off as the real thing. A merge with more parents than the cap is not affected: the table grows to fit one commit's parents, since that is bounded by the commit rather than by the length of the history.
Machine-readable output
Every command takes --json and emits newline-delimited JSON: one self-contained object per line,
never a wrapping array. An array would have to be closed at the end, which means either buffering
the whole result or emitting something that is invalid until the process exits. NDJSON stays
streamable, survives head, and jq -s collects it into an array when a consumer wants one.
$ gitlimes log -n 1 --json | jq -r '.subject'
$ gitlimes who --json | jq -s 'map(select(.commits > 10))'
graph --json carries the lane geometry alongside each commit:
That is what lets another renderer — an SVG export, a canvas, a TUI — draw the graph without re-deriving the layout.
Schema stability
There is deliberately no version field. A stamp on every line would cost bytes on every
record and would not prevent the failure it looks like it guards against — a field renamed by
accident. tests/cli.rs pins the exact key set of every command instead, so a
rename fails CI rather than someone's script; gitlimes --version identifies the format.
The contract is additive: new keys may appear in any release, so ignore keys you do not
recognise; existing keys are not renamed, retyped or removed without a version bump recorded in
CHANGELOG.md. Conditional keys are absent rather than null — head on a commit,
track on a branch, added and removed without --lines. The full key list per command is
in the changelog.
Character encoding
A repository may set i18n.commitEncoding to something other than UTF-8, in which case git
writes the commit message and subject in that charset verbatim. log, graph and who pass
--encoding=UTF-8 to every git log call, so git does the transcoding — a subject in Latin-1
or similar comes through correctly rather than being silently replaced. This costs nothing on an
ordinary UTF-8 repository; it is a no-op there.
Author and committer identity is not covered. Verified directly against a hand-built commit
object: --encoding only ever transcodes the message body, never %an/%ae/%cn/%ce, and
branches reads names via git for-each-ref, which has no --encoding flag at all. A non-ASCII
author name or email written in a non-UTF-8 charset can still come through as the Unicode
replacement character (�) in any command's output, including --json. This is a genuine,
currently-unfixed limitation rather than an oversight left undocumented — a real fix would mean
carrying raw bytes through a pipeline that is &str-typed end to end, which is disproportionate
to how rarely this actually comes up. tests/cli.rs pins both halves of this:
that the subject is recovered, and that the identity fields are not, so a future fix is a
deliberate, visible change rather than a silent one.
Use it as a library
The reusable engine is a library; the CLI is one consumer of it. A TUI, a graphical front end or a script can link against it instead of shelling out and parsing text.
use ;
let mut records = spawn_lines?;
while let Some = records.next_record?
records.finish?;
graph::lanes turns a commit stream into branch-lane geometry and draws nothing; graph::draw
renders that geometry as terminal rows. The split is deliberate — a second renderer reuses the
layout instead of reimplementing it.
Design premise: flat memory
gitlimes spawns git and streams its output through a buffer that is reused for every record.
It never collects the history into memory.
| Command | Peak memory scales with |
|---|---|
log |
one commit record |
graph |
simultaneously open branch lanes |
who |
unique authors |
branches |
refs |
Nothing scales with history length. Measured on a 4359-commit, 215-ref repository:
log -n 10 -> 3.52 MB private
log -n 4000 -> 3.51 MB private
graph -n 10 -> 3.41 MB private
graph -n 4000 -> 3.55 MB private
400x the work for 0.1 MB. The floor is the process image; the marginal cost of history is effectively zero.
Zero dependencies
No clap, no chrono, no crossterm — only the standard library. Argument parsing, ANSI
escapes and tty detection are all small enough to own, and git formats dates for us. The result
is a 385 KB binary, an empty supply chain, and a build that finishes in seconds.
The one piece of platform code is a ~20 line kernel32 call to enable ANSI processing on
Windows conhost; Windows Terminal, macOS and Linux need nothing.
Tests
cargo test
127 tests in two layers.
66 unit tests cover the pure logic — lane assignment for linear history, merges, octopus merges, fork folding, lane reuse and compaction; rendering tests that pin the exact glyph output for each case; JSON escaping; pager resolution; and column fitting, relative dates and sparklines.
60 integration tests run the real built binary against a real git repository. That is the only
way to cover the streaming record reader in repo.rs and the hand-rolled argument parsing, so
they carry the claims that matter: that commit order matches git's, that a subject containing a
pipe, quotes, a backslash and non-ASCII text survives the field-separated record format, that a
multi-line commit body never leaks into the output, that colour is off when stdout is a pipe, and
that every command exits non-zero with a readable message outside a repository.
The fixture builds a repository with a known merge topology and pins everything that would
otherwise vary per machine: no system or global git config, an explicit author, committer and
date on every single call, no signing, and an explicit default branch. Forcing the identity on
every call — not just on git commit — matters more than it looks: with no configured user git
quietly invents one from the OS username and hostname, so an unattributed git merge is authored
by whoever ran the tests and who reports a phantom extra author that differs per machine.
Tests never ship. #[cfg(test)] compiles them out entirely, and the integration tests live in
tests/, which is only built by cargo test — the release binary contains no test code at all.
CI
.github/workflows/ci.yml runs on every push and pull request to
main:
- fmt + clippy —
cargo fmt --checkandcargo clippy --all-targets -- -D warnings. - test — the full suite on
ubuntu-latest,macos-latestandwindows-latest. This is what actually earns the cross-platform claim; the project is developed on Windows, so Linux and macOS are otherwise untested. - smoke test — builds the release binary (which
cargo testnever exercises, since it tests the debug build) and runs every subcommand against this repository's own history, checked out at full depth. gitlimes is built from--no-ffmerges, so the graph must contain a merge dot; if lane rendering regresses, the job fails. - msrv — builds and tests on the exact toolchain named by
rust-versioninCargo.toml, so the stated minimum stays true rather than aspirational.
There is no dependency cache: with zero dependencies a cold build takes seconds, and restoring a cache would cost more time than it saves.
.github/workflows/release.yml runs on a v*.*.* tag: it builds
for Linux, macOS (both architectures) and Windows, smoke-tests each native binary, and attaches
archives plus SHA-256 checksums to the GitHub Release.
Publishing to crates.io is deliberately not automated. A published version can never be deleted, only yanked, so it stays a manual, considered act:
cargo publish --dry-run
cargo publish
License
Dual-licensed under either of
- Apache License, Version 2.0 (LICENSE-APACHE)
- MIT license (LICENSE-MIT)
at your option. This is the convention across the Rust ecosystem: MIT is permissive and short, and Apache-2.0 adds an explicit patent grant.
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in this work by you shall be dual-licensed as above, without any additional terms or conditions.