# gitlimes
[](https://github.com/Drew-lgtm/gitLimes/actions/workflows/ci.yml)
*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](https://github.com/Drew-lgtm/gitLimes/releases). 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`](man/gitlimes.1). Bundled in every release archive. Read it
without installing it with `man ./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`](tldr/gitlimes.md): the handful of commands most people
reach for first, in [tldr-pages](https://github.com/tldr-pages/tldr) format. Not yet part of
the upstream `tldr-pages/tldr` repository; until it is, view it with `tldr --render
tldr/gitlimes.md` (the [`tldr-node-client`](https://github.com/tldr-pages/tldr-node-client)
supports `--render` on a local file) or just read it directly.
- Every command's own `--help` is 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 `--all` can 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.
```console
```
`graph --json` carries the lane geometry alongside each commit:
```json
{"short":"6ff6ffe","subject":"merge: json output",
"graph":{"col":0,"lanes":2,"merge":true,"closing":[],"opening":[1],"shifts":[]}}
```
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`](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](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`](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.
```rust
use gitlimes::repo::{self, Commit, Records, LOG_FORMAT};
let mut records = Records::spawn_lines(repo::git(&["log", LOG_FORMAT, "--"]))?;
while let Some(record) = records.next_record()? {
if let Some(commit) = Commit::parse(&record) {
println!("{} {}", commit.short, commit.subject);
}
}
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.
| `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`](.github/workflows/ci.yml) runs on every push and pull request to
`main`:
- **fmt + clippy** — `cargo fmt --check` and `cargo clippy --all-targets -- -D warnings`.
- **test** — the full suite on `ubuntu-latest`, `macos-latest` and `windows-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 test` never 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-ff` merges, 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-version` in `Cargo.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`](.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](LICENSE-APACHE))
- MIT license ([LICENSE-MIT](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.