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
|
.Dd September 10, 2021
.Dt GIT-COMMENT 7
.Os "Causal Agency"
.
.Sh NAME
.Nm git-comment
.Nd add comments from commit messages
.
.Sh SYNOPSIS
.Nm git comment
.Op Fl \-all
.Op Fl \-comment-start Ar string
.Op Fl \-comment-lead Ar string
.Op Fl \-comment-end Ar string
.Op Fl \-min-group Ar lines
.Op Fl \-min-repeat Ar lines
.Op Fl \-no-repeat
.Op Fl \-pretty Ar format
.Op Ar options ...
.Op Fl \-
.Ar file
.
.Sh DESCRIPTION
The
.Nm
command
adds comments to a file
showing the commit messages
which last modified
each group of lines.
By default only commit messages with bodies
and which modified groups of at least 2 lines
are added.
Each comment contains
the abbreviated commit hash
and the commit summary,
followed by the commit body.
.
.Pp
.Nm
accepts all the options of
.Xr git-blame 1
in addition to the following:
.Bl -tag -width Ds
.It Fl \-all
Include all commit messages.
The default is to include
only commit messages with bodies
(lines after the summary).
.
.It Fl \-comment-start Ar string
Start comments with
.Ar string .
The default is the value of
.Cm comment.start
or
.Ql /* .
.
.It Fl \-comment-lead Ar string
Continue comments with the leading
.Ar string .
The default is the value of
.Cm comment.lead
or
.Ql " *" .
.
.It Fl \-comment-end Ar string
End comments with
.Ar string .
The default is the value of
.Cm comment.end
or
.Ql " */" .
.
.It Fl \-min-group Ar lines
Add comments only for groups of at least
.Ar lines .
The default is 2 lines.
.
.It Fl \-min-repeat Ar lines
Avoid repeating a comment
if it occurred in the last
.Ar lines .
The default is 30 lines.
.
.It Fl \-no-repeat
Avoid repeating comments entirely.
.
.It Fl \-pretty Ar format
Set the pretty-print format
to use for commit messages.
The default is the value of
.Cm comment.pretty
or
.Ql format:%h\ %s%n%n%-b .
See
.Xr git-show 1 .
.El
.
.Sh EXAMPLES
For files with
.Ql #
comments:
.Bd -literal -offset indent
git config comment.start '#'
git config comment.lead '#'
git config comment.end ''
.Ed
.
.Pp
Add as many comments as possible:
.Bd -literal -offset indent
git comment --all --min-group 1 --min-repeat 1
.Ed
.
.Pp
Some examples of output from
.Xr catgirl 1 :
.Bd -literal
/* 347e2b4 Don't apply uiThreshold to Network and Debug
*
* Messages don't really need to be hidden from <network> and I think
* it could be confusing. Debug messages are all Cold so everything
* would be hidden, and I want to keep them that way so that <debug>
* doesn't clutter the status line needlessly.
*/
if (id == Network || id == Debug) {
window->thresh = Cold;
} else {
window->thresh = uiThreshold;
}
/* b4c26a2 Measure timestamp width using ncurses
*
* This allows for non-ASCII characters in timestamps, and simplifies
* things by including the trailing space in the width.
*/
int y;
char buf[TimeCap];
struct tm *time = localtime(&(time_t) { -22100400 });
size_t len = strftime(buf, sizeof(buf), uiTime.format, time);
if (!len) errx(EX_CONFIG, "invalid timestamp format: %s", uiTime.format);
waddstr(main, buf);
waddch(main, ' ');
getyx(main, y, uiTime.width);
(void)y;
/* 43b1dba Restore toggling ignore with M--
*
* So that pressing M-- repeatedly maintains the previous behavior.
*/
if (n < 0 && window->thresh == Ice) {
window->thresh = Cold;
} else {
window->thresh += n;
}
/* 1891c77 Preserve colon from previous tab-complete
*
* This fixes the case when pinging multiple nicks and one of them needs to
* be cycled through.
*/
bool colon = (tab.len >= 2 && buf[tab.pos + tab.len - 2] == L':');
.Ed
.
.Sh SEE ALSO
.Lk https://git.causal.agency/src/tree/bin/git-comment.pl
.
.Sh AUTHORS
.An june Aq Mt june@causal.agency
.
.Pp
In case it's unclear,
this is a
.Xr git 1
subcommand I wrote.
Did you know you can add new
.Xr git 1
subcommands just by
adding executables named
.Pa git-*
to somewhere in
.Ev PATH ?
.
.Pp
This is also,
I think,
my third Perl script ever.
It's an interestingly shaped language.
Quite neat.
|