git-blimey(1)

NAME

git-blimey - interactive git blame viewer

SYNOPSIS

git-blimey [--debug] [--debug-ui] [--viewport-offset=line] file[:line]

DESCRIPTION

git-blimey is an interactive terminal user interface for browsing git blame information with syntax highlighting and commit details. It provides a fast, efficient way to explore the history of changes in a file, showing who made each change and when.

The program displays a table with commit information, author details, timestamps, and syntax-highlighted source code. Each line can be inspected to view full commit details including the complete commit message. Press 'a' to view the git log for an author, showing all their commits in the repository.

The arguments are as follows:

--debug

Print parsed blame data to stdout in JSON format instead of showing the interactive interface. Useful for debugging or scripting.

--debug-ui

Enable debug logging to debug.log for UI events and performance metrics. Shows detailed information about internal state changes and rendering performance.

--viewport-offset=offset

Specify the viewport offset calculated by the editor. This value accounts for soft wrapping (long lines taking multiple screen rows). Git-blimey adds 3 to account for its UI header, preserving the cursor's absolute screen position. Independent of cursor position set by file:line. Can be negative when there is heavy line wrapping near the start of the file. Useful for editor integration to match the exact visual layout (e.g., "--viewport-offset=71 'file.go:100'") when micro calculates offset 71 accounting for wrapped lines.

file[:line]

The file to blame. Optionally specify a line number to position the cursor on startup. When used without --viewport-offset, the viewport is automatically centered on the cursor line (e.g., "main.go:42").

FEATURES

Navigation

The selection and the viewport move independently. Cursor keys move the selection and scroll the viewport only when the selection would leave it, while scrolling commands move the viewport and drag the selection along only once it would go off screen: the selection sticks to the top row when scrolling down and to the bottom row when scrolling up.

In the main view:

Up / k

Move selection up

Down / j

Move selection down

PgUp

Scroll one page up

PgDown

Scroll one page down

Home / g

Go to first line

End / G

Go to last line

Mouse wheel

Scroll up or down

Left click

Select the line under the pointer

Enter

Show commit details for the selected line

a

Show git log for the author of the selected line

b

Blame the selected file (directory view only)

e

Open the file at the current line in EDITOR

r

Refresh blame data

h / F1

Show the help screen

q

Quit, or return from the current view

Ctrl-c / Ctrl-q

Force quit

Ctrl-u

Toggle the debug UI

In the detail and help overlays the same movement keys and the mouse wheel scroll the overlay content, and q closes it.

Syntax Highlighting

Source code is colorized using bat(1) with appropriate language syntax detection. If bat(1) is not available, plain text content is displayed.

Commit Information

Each line displays:

• Short commit hash (8 characters)
• Extended message indicator - shows "+" when a commit has descriptive body text beyond standard git attributes
• Author name with color-coded emoji identifier
• Relative timestamp (seconds, minutes, hours, days, months, or years)
• Line number
• Syntax-highlighted source code

The commit subject line appears in the bottom border when a line is selected.

File Watching

git-blimey automatically detects when the blamed file changes on disk and displays a notification. File changes are detected using native filesystem events (inotify on Linux, FSEvents on macOS, kqueue on BSD).

The program also periodically checks if the latest commit affecting the file has changed, detecting operations like git-commit(1) --amend or git-rebase(1).

Performance

• Asynchronous blame loading with progress indicator
• Efficient viewport rendering for large files (tested with files of 1M lines of code and thousands of commits)
• Lazy colorization for very large files
• Extended message detection cached to avoid redundant git operations
• Concurrent git queries with throttling (max 10 concurrent tasks)

ENVIRONMENT

EDITOR

Specifies the text editor to use when opening the file for editing. If not set, git-blimey will use micro(1) if available in PATH. See https://github.com/zyedidia/micro for installation instructions.

FILES

debug.log

Debug log file created when --debug-ui is enabled. Contains detailed information about UI state changes and performance metrics.

EXIT STATUS

The git-blimey utility exits 0 on success, and >0 if an error occurs.

EXAMPLES

View blame for a file:

$ git-blimey main.go

Jump to a specific line (cursor position, viewport centered):

$ git-blimey src/handler.rs:142

Match editor's viewport with soft wrapping:

$ git-blimey --viewport-offset=71 src/handler.rs:100

Editor integration calculates offset accounting for wrapped lines. Git-blimey adds +3 for its header, preserving cursor's exact screen position.

Without wrapping (simple case):

$ git-blimey --viewport-offset=0 src/handler.rs:20

First line visible at top, cursor at line 20 (screen row 20).

SEE ALSO

git-blame(1), bat(1), micro(1)

AUTHORS

Profpatsch

CAVEATS

git-blimey enables mouse reporting, which takes over the terminal emulator's own mouse handling. Click-drag text selection therefore no longer works directly; hold Shift while dragging to select and copy text, as supported by most terminal emulators.

The program requires that the file being blamed is within a git repository. Files outside of git repositories cannot be processed.

Syntax highlighting requires bat(1) to be installed and available in PATH. Without it, content is displayed as plain text.

File editing (press 'e') requires either the EDITOR environment variable to be set, or micro(1) to be installed and available in PATH. If neither is available, the edit command will not work.