Improve --help output + make CI prevent copies of --help output from going out-of-sync

.github/workflows/enforce-copies-of-help-output-in-sync.yml

@@ -0,0 +1,59 @@
+# This file is part of git-big-picture
+#
+# Copyright (C) 2021 Sebastian Pipping <sebastian@pipping.org>
+#
+# git-big-picture is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# git-big-picture 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 General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with git-big-picture.  If not, see <http://www.gnu.org/licenses/>.
+
+name: Enforce that copies of --help output are in sync
+
+on:
+- pull_request
+- push
+
+jobs:
+  run_pre_commit:
+    name: Check if copies of --help output are in sync
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+
+      - name: Set up Python 3.9
+        uses: actions/setup-python@v2.2.1
+        with:
+          python-version: 3.9
+
+      - name: Install build dependencies
+        run: |
+          sudo apt-get install --no-install-recommends -y help2man
+
+      - name: Install git-big-picture entry point script
+        run: |-
+          pip install \
+            --disable-pip-version-check \
+            --user \
+            --no-warn-script-location \
+            .
+          echo "PATH=${HOME}/.local/bin:${PATH}" >> "${GITHUB_ENV}"
+
+      - name: Check if the man page is in sync with --help output
+        run: |-
+          rm git-big-picture.1  # to enforce a diff for the generator to remove
+          ./sync-manpage-with-help-output.sh
+          git diff --exit-code -- git-big-picture.1
+
+      - name: Check if the readme is in sync with --help output
+        run: |-
+          sed 's,OPTIONS,XXX,' -i README.rst  # to enforce a diff for the generator to remove
+          ./sync-readme-with-help-output.sh
+          git diff --exit-code -- README.rst

README.rst

@@ -167,6 +167,8 @@ Usage
     $ git-big-picture --help
     usage: git-big-picture OPTIONS [REPOSITORY]
 
+    Visualize Git repositories
+
     positional arguments:
       REPOSITORY            path to the Git working directory
                             (default: current directory)
@@ -212,14 +214,21 @@ Usage
       -R, --no-roots        do not show root commits
       -m, --merges          include merge commits
       -M, --no-merges       do not include merge commits
-      -i, --bifurcations    include bifurcation commits
+      -i, --bifurcations    include bifurcation commits; a bifurcation commit is a
+                            commit that is a parent to more than one other commits,
+                            i.e. it marks the point where one or more new branches
+                            came to life; bifurcation commits can also be thought of
+                            as the counterpart of merge commits
       -I, --no-bifurcations
                             do not include bifurcation commits
       -c, --commit-messages
                             include commit messages on labels
       -C, --no-commit-messages
                             do not include commit messages on labels
 
+    git-big-picture is software libre, licensed under the GPL v3 or later license.
+    Please report bugs at https://github.com/git-big-picture/git-big-picture/issues.  Thank you!
+
 Usage Examples
 --------------
 

git-big-picture.1

@@ -1,9 +1,14 @@
-.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.47.16.
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man.
 .TH GIT-BIG-PICTURE "1" "January 2021" "git-big-picture 1.0.0" "User Commands"
 .SH NAME
-git-big-picture \- visualize git repositories
+git-big-picture \- Visualize Git repositories
+.SH SYNOPSIS
+
+.B git\-big\-picture
+OPTIONS [REPOSITORY]
 .SH DESCRIPTION
-git\-big\-picture OPTIONS [REPOSITORY]
+.PP
+Visualize Git repositories
 .SS "positional arguments:"
 .TP
 REPOSITORY
@@ -23,7 +28,7 @@ run cProfile profiler writing pstats output to FILE
 \fB\-d\fR, \fB\-\-debug\fR
 activate debug output
 .SS "output options:"
-.IP
+.PP
 Options to control output and format
 .TP
 \fB\-f\fR FMT, \fB\-\-format\fR FMT
@@ -64,7 +69,7 @@ file that is opened using the viewer command (default:
 tell other running processes to open that file on their
 behalf, to then shut themselves down
 .SS "filter options:"
-.IP
+.PP
 Options to control commit/ref selection
 .TP
 \fB\-a\fR, \fB\-\-all\fR
@@ -95,7 +100,11 @@ include merge commits
 do not include merge commits
 .TP
 \fB\-i\fR, \fB\-\-bifurcations\fR
-include bifurcation commits
+include bifurcation commits; a bifurcation commit is a
+commit that is a parent to more than one other commits,
+i.e. it marks the point where one or more new branches
+came to life; bifurcation commits can also be thought of
+as the counterpart of merge commits
 .TP
 \fB\-I\fR, \fB\-\-no\-bifurcations\fR
 do not include bifurcation commits
@@ -105,3 +114,9 @@ include commit messages on labels
 .TP
 \fB\-C\fR, \fB\-\-no\-commit\-messages\fR
 do not include commit messages on labels
+.PP
+.SH EPILOG
+
+.B git\-big\-picture
+is software libre, licensed under the GPL v3 or later license.
+Please report bugs at https://github.com/git\-big\-picture/git\-big\-picture/issues.  Thank you!

git_big_picture/_main.py

@@ -118,10 +118,19 @@
 
 USAGE = "%(prog)s OPTIONS [REPOSITORY]"
 
+_EPILOG = textwrap.dedent("""
+    git-big-picture is software libre, licensed under the GPL v3 or later license.
+    Please report bugs at https://github.com/git-big-picture/git-big-picture/issues.  Thank you!
+""")
+
+_RIGHT_COLUMN_WRAP_WIDTH = 57
+
 
 def create_parser():
     parser = argparse.ArgumentParser(prog='git-big-picture',
                                      usage=USAGE,
+                                     description='Visualize Git repositories',
+                                     epilog=_EPILOG,
                                      formatter_class=argparse.RawTextHelpFormatter)
     parser.add_argument('--version', action='version', version=f'%(prog)s {__version__}')
 
@@ -205,7 +214,7 @@ def create_parser():
                                       'viewer commands that tell other running processes '
                                       'to open that file on their behalf'
                                       ', to then shut themselves down',
-                                      width=57)))
+                                      width=_RIGHT_COLUMN_WRAP_WIDTH)))
 
     filter_group = parser.add_argument_group("filter options",
                                              "Options to control commit/ref selection")
@@ -275,7 +284,16 @@ def create_parser():
                               default=None,
                               action='store_true',
                               dest=BIFURCATIONS,
-                              help='include bifurcation commits')
+                              help='\n'.join(
+                                  textwrap.wrap(
+                                      'include bifurcation commits'
+                                      '; a bifurcation commit is a commit that '
+                                      'is a parent to more than one other commits, '
+                                      'i.e. it marks the point where one or more '
+                                      'new branches came to life; bifurcation '
+                                      'commits can also be thought of as the '
+                                      'counterpart of merge commits',
+                                      width=_RIGHT_COLUMN_WRAP_WIDTH)))
     filter_group.add_argument('-I',
                               '--no-bifurcations',
                               default=None,

sync-manpage-with-help-output.sh

@@ -0,0 +1,46 @@
+#! /usr/bin/env bash
+# This file is part of git-big-picture
+#
+# Copyright (C) 2021 Sebastian Pipping <sebastian@pipping.org>
+#
+# git-big-picture is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# git-big-picture 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 General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with git-big-picture.  If not, see <http://www.gnu.org/licenses/>.
+
+set -e
+set -o pipefail
+
+_BUILD_MONTH=2021-01  # for reproducible builds; bump when doing releases
+
+sed_args=(
+    # Produce familiar section "synopsis"
+    -e 's,^\.SH DESCRIPTION,.SH SYNOPSIS,'
+    -e 's,^usage: ,,'
+    -e 's,^git\\-big\\-picture OPTIONS.*,\0\n.SH DESCRIPTION,'
+
+    # Be robust towards version difference between local help2man and CI help2man
+    -e 's,It was generated by help2man .*,It was generated by help2man.,'
+
+    # Fix over-indent of argument group description
+    -e 's,^\.IP,.PP,'
+
+    # Put epilog in its own section
+    -e 's,^git\\-big\\-picture is software libre.*,.SH EPILOG\n\0,'
+
+    # Format "git-big-picture" in bold everywhere after section "NAME"
+    -e 's,\(git\\-big\\-picture\) ,\n.B \1\n,g'
+)
+
+SOURCE_DATE_EPOCH="$(date --date="${_BUILD_MONTH}-15" +%s)" \
+    help2man --no-info --name 'Visualize Git repositories' git-big-picture \
+    | sed "${sed_args[@]}" \
+    > git-big-picture.1

sync-readme-with-help-output.sh

@@ -0,0 +1,45 @@
+#! /usr/bin/env bash
+# This file is part of git-big-picture
+#
+# Copyright (C) 2021 Sebastian Pipping <sebastian@pipping.org>
+#
+# git-big-picture is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# git-big-picture 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 General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with git-big-picture.  If not, see <http://www.gnu.org/licenses/>.
+
+set -e
+set -o pipefail
+
+tempfile="$(mktemp)"
+remove_tempfile() {
+    if [[ -e "${tempfile}" ]]; then
+        rm -v "${tempfile}"
+    fi
+}
+trap remove_tempfile EXIT
+
+text_before_help_output() {
+    awk '/usage:/ { hide = 1 } !hide { print }' "$1"
+}
+
+text_after_help_output() {
+    awk '/Usage Examples/ { show = 1 } show { print }' "$1"
+}
+
+{
+    text_before_help_output README.rst
+    git-big-picture --help | sed '/./ s,^,    ,'
+    echo
+    text_after_help_output README.rst
+} > "${tempfile}"
+
+mv "${tempfile}" README.rst