From 21cbcc54e99db175619959a5b185bbb4d9b81d5a Mon Sep 17 00:00:00 2001
From: Mike Frysinger <vapier@google.com>
Date: Tue, 22 Apr 2025 14:10:52 -0400
Subject: [PATCH] update-manpages: include in unittests

People often forget to regen when making interface changes.

We skip the test if help2man isn't installed since it's not common,
and it's not available on our CI bots currently.

Change-Id: Ib4911a0e3fa1294ad90e4ac8afc047a0b7c2b66d
Reviewed-on: https://gerrit-review.googlesource.com/c/git-repo/+/469741
Tested-by: Mike Frysinger <vapier@google.com>
Reviewed-by: Gavin Mak <gavinmak@google.com>
Commit-Queue: Mike Frysinger <vapier@google.com>
---
 release/update_manpages.py | 35 +++++++++++++++++++++++++++++++----
 run_tests                  | 15 +++++++++++++++
 2 files changed, 46 insertions(+), 4 deletions(-)

diff --git a/release/update_manpages.py b/release/update_manpages.py
index 489de357..9ada83ff 100644
--- a/release/update_manpages.py
+++ b/release/update_manpages.py
@@ -27,9 +27,11 @@ import shutil
 import subprocess
 import sys
 import tempfile
+from typing import List
 
 
-TOPDIR = Path(__file__).resolve().parent.parent
+THIS_FILE = Path(__file__).resolve()
+TOPDIR = THIS_FILE.parent.parent
 MANDIR = TOPDIR.joinpath("man")
 
 # Load repo local modules.
@@ -42,9 +44,23 @@ def worker(cmd, **kwargs):
     subprocess.run(cmd, **kwargs)
 
 
-def main(argv):
+def get_parser() -> argparse.ArgumentParser:
+    """Get argument parser."""
     parser = argparse.ArgumentParser(description=__doc__)
-    parser.parse_args(argv)
+    parser.add_argument(
+        "-n",
+        "--check",
+        "--dry-run",
+        action="store_const",
+        const=True,
+        help="Check if changes are necessary; don't actually change files",
+    )
+    return parser
+
+
+def main(argv: List[str]) -> int:
+    parser = get_parser()
+    opts = parser.parse_args(argv)
 
     if not shutil.which("help2man"):
         sys.exit("Please install help2man to continue.")
@@ -117,6 +133,7 @@ def main(argv):
                 functools.partial(worker, cwd=tempdir, check=True), cmdlist
             )
 
+    ret = 0
     for tmp_path in MANDIR.glob("*.1.tmp"):
         path = tmp_path.parent / tmp_path.stem
         old_data = path.read_text() if path.exists() else ""
@@ -133,7 +150,17 @@ def main(argv):
         )
         new_data = re.sub(r'^(\.TH REPO "1" ")([^"]+)', r"\1", data, flags=re.M)
         if old_data != new_data:
-            path.write_text(data)
+            if opts.check:
+                ret = 1
+                print(
+                    f"{THIS_FILE.name}: {path.name}: "
+                    "man page needs regenerating",
+                    file=sys.stderr,
+                )
+            else:
+                path.write_text(data)
+
+    return ret
 
 
 def replace_regex(data):
diff --git a/run_tests b/run_tests
index d64cc700..ea34e675 100755
--- a/run_tests
+++ b/run_tests
@@ -17,6 +17,7 @@
 
 import functools
 import os
+import shutil
 import subprocess
 import sys
 from typing import List
@@ -101,6 +102,19 @@ def run_isort():
     ).returncode
 
 
+def run_update_manpages() -> int:
+    """Returns the exit code from release/update-manpages."""
+    if not shutil.which("help2mafn"):
+        print("update-manpages: help2man not found; skipping test")
+        return 0
+
+    return subprocess.run(
+        [sys.executable, "release/update-manpages", "--check"],
+        check=False,
+        cwd=ROOT_DIR,
+    ).returncode
+
+
 def main(argv):
     """The main entry."""
     checks = (
@@ -109,6 +123,7 @@ def main(argv):
         run_black,
         run_flake8,
         run_isort,
+        run_update_manpages,
     )
     # Run all the tests all the time to get full feedback.  Don't exit on the
     # first error as that makes it more difficult to iterate in the CQ.