Skip to main content

gvt — Git Visual Timeline

A keyboard-driven TUI for exploring the commit history of any file in a git repo. Think lazygit meets a video timeline scrubber, focused on per-file history.

gvt full layout

gvt is a read-only history explorer, not a git UI. It doesn't stage, commit, push, or manage branches — lazygit is great for that. gvt does one thing: lets you scrub through a file's commit timeline, see what changed and when, and understand how code evolved over time. It's the tool you reach for when you're staring at a file and asking "how did this get here?"

Install

pipx install git-visual-timeline

pipx installs gvt in an isolated environment and puts it on your PATH — the recommended way to install Python CLI tools. Install pipx itself with brew install pipx (macOS) or apt install pipx (Debian/Ubuntu).

Usage

# Open in any git repo
gvt

# Jump directly to a file
gvt path/to/file.py

Layout

gvt uses a 5-pane layout, each accessible by number key:

Pane Name What it shows
1 Files File tree with lazy-loading directories
2 Timeline Heatmap of commits (green=adds, red=deletes, amber=mixed)
3 Commits Message, hash, date, and stats for visible commits
4 Diff Syntax-highlighted diff with blame, search, and context controls
5 Changed Files All files touched by the current commit

Features

Timeline Navigation

Scrub through a file's commit history one tick at a time. Each tick is colored by change type — green for additions, red for deletions, amber for mixed.

Timeline navigation

Pin Mode

Press x to pin a commit, then move to another and press x again to diff any two commits. Press x a third time to clear. Use X to snap the nearest pin to your cursor.

Pin mode

Inline Blame

Toggle blame annotations with b to see who last modified each line, right-aligned alongside the diff.

Blame mode

Press f for an fzf-style fuzzy file picker that filters as you type.

File search

Press c to fuzzy search all repo commits by message, branch, or author.

Commit search

All Features

  • Syntax-highlighted diffs with inline, whole-file (w), and side-by-side (d) views
  • Diff search (/) — regex search within the diff with n/p to navigate matches
  • Commit search (c) — fuzzy search all repo commits by message, branch, or author
  • Time filter (t) — filter timeline by date range (1w, 1m, 3m, 6m, 1y, custom date)
  • Contributor breakdown (B) — who changed the file and how much
  • WIP indicator — hollow tick showing uncommitted changes
  • Copy to clipboard (y/Y) — short or full commit hash
  • Open in editor (e) — open current file in $VISUAL/$EDITOR/vim
  • Remember last file — reopens to the last file you were viewing per repo
  • tmux integration — seamless pane switching at edges
  • Preloaded diffs — adjacent commits pre-cached for instant navigation
  • Context-sensitive status bar showing relevant shortcuts per pane

Keybindings

Global

Key Action
1-5 Jump to pane
Ctrl+h/j/k/l Navigate panes directionally
c Search commits (all repo)
f / Ctrl+P Search files
t Time filter
w Toggle whole-file view
d Toggle side-by-side diff
b Toggle inline blame
B Contributor breakdown
/ Search in diff
n/p Next/prev diff hunk
y / Y Copy short/full commit hash
e Open file in editor
? Help
q Quit (with confirmation)
qq Quit immediately

Timeline (Pane 2)

Key Action
h/l Move cursor
0/$ Jump to first/last commit
x Pin commit (1st=start, 2nd=end, 3rd=clear)
X Snap nearest pin to cursor

Diff (Pane 4)

Key Action
j/k Scroll vertically
h/l Scroll horizontally
g/G Top/bottom
+/- More/less context lines

Search Modals

Key Action
Tab / Shift+Tab Navigate results
Ctrl+n / Ctrl+p Navigate results (alternative)
Enter Select
Esc Close

Requirements

  • Python 3.10+
  • A git repository

License

MIT

Metadata

Release files for git-visual-timeline 0.2.4

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for git-visual-timeline 0.2.4
File Size Uploaded Provenance Actions
git_visual_timeline-0.2.4.tar.gz 51.4 kB Without provenance Details for git_visual_timeline-0.2.4.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for git-visual-timeline 0.2.4
File Interpreter ABI Platform Actions
git_visual_timeline-0.2.4-py3-none-any.whl Python 3 none any Details for git_visual_timeline-0.2.4-py3-none-any.whl

Total release size: 95.3 kB

Release files / git_visual_timeline-0.2.4.tar.gz

Download URL git_visual_timeline-0.2.4.tar.gz
Size 51.4 kB
Tags Source
SHA-256 checksum
How to use checksums
790f4f32359a48c2f2e5a1f9a355e316fcb3cb38fa9462b04a5b6f166b90a03c
BLAKE2b-256 checksum
How to use checksums
d373189ffa56d92b3f5a6a5bcbfbc111aeeb2eb9bce98098df2f355439190e43
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.14.3

Release files / git_visual_timeline-0.2.4-py3-none-any.whl

Download URL git_visual_timeline-0.2.4-py3-none-any.whl
Size 43.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
fa11df1b5480b85fa4e31df9a444f1a88a53efb792d42126ecfe3643dabecacb
BLAKE2b-256 checksum
How to use checksums
e2eebf0a7007e1d66d0ca0070e2106c0486c30c8dd89b1ddb6ade1e5ef1e5475
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.14.3

Security for git-visual-timeline 0.2.4

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page