From ffa33879383147e41eca708448ffac4727054e1e Mon Sep 17 00:00:00 2001
From: "C. McEnroe" <june@causal.agency>
Date: Wed, 8 Sep 2021 21:58:07 -0400
Subject: Document and install git-comment

---
 bin/.gitignore         |  1 +
 bin/Makefile           |  1 +
 bin/README.7           |  4 ++-
 bin/git-comment.pl     | 23 ++++++++++---
 bin/man1/git-comment.1 | 88 ++++++++++++++++++++++++++++++++++++++++++++++++++
 5 files changed, 111 insertions(+), 6 deletions(-)
 create mode 100644 bin/man1/git-comment.1

diff --git a/bin/.gitignore b/bin/.gitignore
index d065f60e..58203f7e 100644
--- a/bin/.gitignore
+++ b/bin/.gitignore
@@ -12,6 +12,7 @@ ever
 fbatt
 fbclock
 freecell
+git-comment
 glitch
 hilex
 htagml
diff --git a/bin/Makefile b/bin/Makefile
index b3c8adea..9e8d5281 100644
--- a/bin/Makefile
+++ b/bin/Makefile
@@ -13,6 +13,7 @@ BINS += bit
 BINS += c
 BINS += dehtml
 BINS += dtch
+BINS += git-comment
 BINS += glitch
 BINS += hilex
 BINS += htagml
diff --git a/bin/README.7 b/bin/README.7
index 441bf693..cdae4def 100644
--- a/bin/README.7
+++ b/bin/README.7
@@ -1,4 +1,4 @@
-.Dd September  7, 2021
+.Dd September  8, 2021
 .Dt BIN 7
 .Os "Causal Agency"
 .
@@ -38,6 +38,8 @@ framebuffer battery indicator
 framebuffer clock
 .It Xr freecell 6
 patience game
+.It Xr git-comment 1
+add commit comments
 .It Xr glitch 1
 PNG glitcher
 .It Xr hilex 1
diff --git a/bin/git-comment.pl b/bin/git-comment.pl
index 42ff9143..c8cd9d40 100644
--- a/bin/git-comment.pl
+++ b/bin/git-comment.pl
@@ -1,6 +1,20 @@
 #!/usr/bin/env perl
+# Copyright (C) 2021  C. McEnroe <june@causal.agency>
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Affero General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Affero General Public License for more details.
+#
+# You should have received a copy of the GNU Affero General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
-# FIXME?
+# MacPorts is strange.
 use lib (split(/:/, $ENV{GITPERLLIB} || '/opt/local/share/perl5'));
 
 use strict;
@@ -10,13 +24,10 @@ use Git;
 
 my $repo = Git->repository();
 
-my $all = 0;
+my ($all, $minGroup, $minRepeat, $noRepeat) = (0, 2, 20, 0);
 my $commentStart = $repo->config('comment.start') // "/*";
 my $commentLead = $repo->config('comment.lead') // " *";
 my $commentEnd = $repo->config('comment.end') // " */";
-my $minGroup = $repo->config('comment.minGroup') // 2;
-my $minRepeat = $repo->config('comment.minRepeat') // 20;
-my $noRepeat = $repo->config_bool('comment.noRepeat');
 GetOptions(
 	'all' => \$all,
 	'comment-start=s' => \$commentStart,
@@ -56,8 +67,10 @@ while (<$pipe>) {
 		);
 		$abbrev{$commit} = shift @body;
 		$body{$commit} = \@body;
+
 	} elsif (/^summary (.*)/) {
 		$summary{$commit} = $1;
+
 	} elsif (/^\t(\s*)(.*)/) {
 		my ($indent, $line) = ($1, $2);
 		unless ($printed) {
diff --git a/bin/man1/git-comment.1 b/bin/man1/git-comment.1
new file mode 100644
index 00000000..9c9b4cd6
--- /dev/null
+++ b/bin/man1/git-comment.1
@@ -0,0 +1,88 @@
+.Dd September  8, 2021
+.Dt GIT-COMMENT 1
+.Os
+.
+.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 Ar options ...
+.Op Fl \-
+.Ar file
+.
+.Sh DESCRIPTION
+Annotates the given file with comments
+containing the commit messages
+of the revisions
+which last modified
+each group of lines.
+.
+.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 20 lines.
+.
+.It Fl \-no-repeat
+Avoid repeating comments entirely.
+.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
-- 
cgit 1.4.1