Publish "git-comment"

2 files changed, 191 insertions, 0 deletions

diff --git a/www/text.causal.agency/026-git-comment.7 b/www/text.causal.agency/026-git-comment.7
new file mode 100644
index 00000000..fefb497e
--- /dev/null
+++ b/www/text.causal.agency/026-git-comment.7
@@ -0,0 +1,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.
diff --git a/www/text.causal.agency/Makefile b/www/text.causal.agency/Makefile
index afe07a14..be1a4f1b 100644
--- a/www/text.causal.agency/Makefile
+++ b/www/text.causal.agency/Makefile
@@ -28,6 +28,7 @@ TXTS += 022-swans-are-dead.txt
 TXTS += 023-sparse-checkout.txt
 TXTS += 024-seprintf.txt
 TXTS += 025-v6-pwd.txt
+TXTS += 026-git-comment.txt
 
 all: ${TXTS}