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
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240

.Dd August 1, 2026
.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 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.
.Pp
In the main view:
.Bl -tag -width "Mouse wheel" -compact
.It Ic Up No / Ic k
Move selection up
.It Ic Down No / Ic j
Move selection down
.It Ic PgUp
Scroll one page up
.It Ic PgDown
Scroll one page down
.It Ic Home No / Ic g
Go to first line
.It Ic End No / Ic G
Go to last line
.It Ic Mouse wheel
Scroll up or down
.It Ic Left click
Select the line under the pointer
.It Ic Enter
Show commit details for the selected line
.It Ic a
Show git log for the author of the selected line
.It Ic b
Blame the selected file
.Pq directory view only
.It Ic e
Open the file at the current line in
.Ev EDITOR
.It Ic r
Refresh blame data
.It Ic h No / Ic F1
Show the help screen
.It Ic q
Quit, or return from the current view
.It Ic Ctrl-c No / Ic Ctrl-q
Force quit
.It Ic Ctrl-u
Toggle the debug UI
.El
.Pp
In the detail and help overlays the same movement keys and the mouse wheel
scroll the overlay content, and
.Ic q
closes it.
.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
.Nm
enables mouse reporting, which takes over the terminal emulator's own mouse
handling.
Click-drag text selection therefore no longer works directly; hold
.Ic Shift
while dragging to select and copy text, as supported by most terminal
emulators.
.Pp
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.