1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181

.Dd October 10, 2025
.Dt GIT-BLIMEY 1
.Os
.Sh NAME
.Nm git-blimey
.Nd interactive git blame viewer
.Sh SYNOPSIS
.Nm
.Op Fl -debug
.Op Fl -debug-ui
.Op Fl -viewport-offset Ns = Ns Ar line
.Ar file Ns Op : Ns Ar line
.Sh DESCRIPTION
.Nm
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.
.Pp
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
.Sq a
to view the git log for an author, showing all their commits in the repository.
.Pp
The arguments are as follows:
.Bl -tag -width Ds
.It Fl -debug
Print parsed blame data to stdout in JSON format instead of showing the
interactive interface.
Useful for debugging or scripting.
.It Fl -debug-ui
Enable debug logging to
.Pa debug.log
for UI events and performance metrics.
Shows detailed information about internal state changes and rendering performance.
.It Fl -viewport-offset Ns = Ns Ar 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
.Ar file Ns : Ns Ar 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
.Pq e.g., Dq --viewport-offset=71 'file.go:100'
when micro calculates offset 71 accounting for wrapped lines.
.It Ar file Ns Op : Ns Ar line
The file to blame.
Optionally specify a line number to position the cursor on startup.
When used without
.Fl -viewport-offset ,
the viewport is automatically centered on the cursor line
.Pq e.g., Dq main.go:42 .
.El
.Sh FEATURES
.Ss Syntax Highlighting
Source code is colorized using
.Xr bat 1
with appropriate language syntax detection.
If
.Xr bat 1
is not available, plain text content is displayed.
.Ss Commit Information
Each line displays:
.Bl -bullet -compact
.It
Short commit hash (8 characters)
.It
Extended message indicator - shows
.Dq +
when a commit has descriptive body text beyond standard git attributes
.It
Author name with color-coded emoji identifier
.It
Relative timestamp (seconds, minutes, hours, days, months, or years)
.It
Line number
.It
Syntax-highlighted source code
.El
.Pp
The commit subject line appears in the bottom border when a line is selected.
.Ss File Watching
.Nm
automatically detects when the blamed file changes on disk and displays
a notification.
File changes are detected using native filesystem events
.Pq inotify on Linux, FSEvents on macOS, kqueue on BSD .
.Pp
The program also periodically checks if the latest commit affecting the file
has changed, detecting operations like
.Xr git-commit 1
.Fl -amend
or
.Xr git-rebase 1 .
.Ss Performance
.Bl -bullet -compact
.It
Asynchronous blame loading with progress indicator
.It
Efficient viewport rendering for large files (tested with files of 1M lines of code and thousands of commits)
.It
Lazy colorization for very large files
.It
Extended message detection cached to avoid redundant git operations
.It
Concurrent git queries with throttling (max 10 concurrent tasks)
.El
.Sh ENVIRONMENT
.Bl -tag -width Ds
.It Ev EDITOR
Specifies the text editor to use when opening the file for editing.
If not set, git-blimey will use
.Xr micro 1
if available in
.Ev PATH .
See
.Lk https://github.com/zyedidia/micro
for installation instructions.
.El
.Sh FILES
.Bl -tag -width Ds
.It Pa debug.log
Debug log file created when
.Fl -debug-ui
is enabled.
Contains detailed information about UI state changes and performance metrics.
.El
.Sh EXIT STATUS
.Ex -std
.Sh EXAMPLES
View blame for a file:
.Bd -literal -offset indent
$ git-blimey main.go
.Ed
.Pp
Jump to a specific line (cursor position, viewport centered):
.Bd -literal -offset indent
$ git-blimey src/handler.rs:142
.Ed
.Pp
Match editor's viewport with soft wrapping:
.Bd -literal -offset indent
$ git-blimey --viewport-offset=71 src/handler.rs:100
.Ed
.Pp
Editor integration calculates offset accounting for wrapped lines.
Git-blimey adds +3 for its header, preserving cursor's exact screen position.
.Pp
Without wrapping (simple case):
.Bd -literal -offset indent
$ git-blimey --viewport-offset=0 src/handler.rs:20
.Ed
.Pp
First line visible at top, cursor at line 20 (screen row 20).
.Sh SEE ALSO
.Xr git-blame 1 ,
.Xr bat 1 ,
.Xr micro 1
.Sh AUTHORS
.An Profpatsch
.Sh CAVEATS
The program requires that the file being blamed is within a git repository.
Files outside of git repositories cannot be processed.
.Pp
Syntax highlighting requires
.Xr bat 1
to be installed and available in
.Ev PATH .
Without it, content is displayed as plain text.
.Pp
File editing (press 'e') requires either the
.Ev EDITOR
environment variable to be set, or
.Xr micro 1
to be installed and available in
.Ev PATH .
If neither is available, the edit command will not work.