man: make output system independent

The current help output might change based on the number of CPU cores
available (since it reflects the dynamic --jobs logic).  This is good
for users running repo locally, but not good for shipping static man
pages.  Hook the help output to have it generate the same output all
the time.

Change-Id: I3098ceddc0ad914b0b8e3b25d660b5a264cb41ee
Reviewed-on: https://gerrit-review.googlesource.com/c/git-repo/+/312882
Reviewed-by: Roger Shimizu <rosh@debian.org>
Reviewed-by: Mike Frysinger <vapier@google.com>
Tested-by: Mike Frysinger <vapier@google.com>

14 files changed, 38 insertions, 13 deletions

diff --git a/command.py b/command.py
index 4087cab5..b972a0be 100644
--- a/command.py
+++ b/command.py
@@ -24,6 +24,10 @@ from error import InvalidProjectGroupsError
 import progress
 
 
+# Are we generating man-pages?
+GENERATE_MANPAGES = os.environ.get('_REPO_GENERATE_MANPAGES_') == ' indeed! '
+
+
 # Number of projects to submit to a single worker process at a time.
 # This number represents a tradeoff between the overhead of IPC and finer
 # grained opportunity for parallelism. This particular value was chosen by
@@ -122,10 +126,14 @@ class Command(object):
                  help='only show errors')
 
     if self.PARALLEL_JOBS is not None:
+      default = 'based on number of CPU cores'
+      if not GENERATE_MANPAGES:
+        # Only include active cpu count if we aren't generating man pages.
+        default = f'%default; {default}'
       p.add_option(
           '-j', '--jobs',
           type=int, default=self.PARALLEL_JOBS,
-          help='number of jobs to run in parallel (default: %s)' % self.PARALLEL_JOBS)
+          help=f'number of jobs to run in parallel (default: {default})')
 
   def _Options(self, p):
     """Initialize the option parser with subcommand-specific options."""
diff --git a/man/repo-abandon.1 b/man/repo-abandon.1
index fb3160c3..b3c0422f 100644
--- a/man/repo-abandon.1
+++ b/man/repo-abandon.1
@@ -20,7 +20,8 @@ It is equivalent to "git branch \fB\-D\fR <branchname>".
 show this help message and exit
 .TP
 \fB\-j\fR JOBS, \fB\-\-jobs\fR=\fI\,JOBS\/\fR
-number of jobs to run in parallel (default: 4)
+number of jobs to run in parallel (default: based on
+number of CPU cores)
 .TP
 \fB\-\-all\fR
 delete all branches in all projects
diff --git a/man/repo-branches.1 b/man/repo-branches.1
index 0080e467..7fe0b02d 100644
--- a/man/repo-branches.1
+++ b/man/repo-branches.1
@@ -46,7 +46,8 @@ is shown, then the branch appears in all projects.
 show this help message and exit
 .TP
 \fB\-j\fR JOBS, \fB\-\-jobs\fR=\fI\,JOBS\/\fR
-number of jobs to run in parallel (default: 4)
+number of jobs to run in parallel (default: based on
+number of CPU cores)
 .SS Logging options:
 .TP
 \fB\-v\fR, \fB\-\-verbose\fR
diff --git a/man/repo-checkout.1 b/man/repo-checkout.1
index 882b4baf..6dd3e6ca 100644
--- a/man/repo-checkout.1
+++ b/man/repo-checkout.1
@@ -15,7 +15,8 @@ Checkout a branch for development
 show this help message and exit
 .TP
 \fB\-j\fR JOBS, \fB\-\-jobs\fR=\fI\,JOBS\/\fR
-number of jobs to run in parallel (default: 4)
+number of jobs to run in parallel (default: based on
+number of CPU cores)
 .SS Logging options:
 .TP
 \fB\-v\fR, \fB\-\-verbose\fR
diff --git a/man/repo-diff.1 b/man/repo-diff.1
index aff36d24..890f8d22 100644
--- a/man/repo-diff.1
+++ b/man/repo-diff.1
@@ -19,7 +19,8 @@ to the Unix 'patch' command.
 show this help message and exit
 .TP
 \fB\-j\fR JOBS, \fB\-\-jobs\fR=\fI\,JOBS\/\fR
-number of jobs to run in parallel (default: 4)
+number of jobs to run in parallel (default: based on
+number of CPU cores)
 .TP
 \fB\-u\fR, \fB\-\-absolute\fR
 paths are relative to the repository root
diff --git a/man/repo-forall.1 b/man/repo-forall.1
index 194f4d20..eb2ad57b 100644
--- a/man/repo-forall.1
+++ b/man/repo-forall.1
@@ -17,7 +17,8 @@ repo forall \fB\-r\fR str1 [str2] ... \fB\-c\fR <command> [<arg>...]
 show this help message and exit
 .TP
 \fB\-j\fR JOBS, \fB\-\-jobs\fR=\fI\,JOBS\/\fR
-number of jobs to run in parallel (default: 4)
+number of jobs to run in parallel (default: based on
+number of CPU cores)
 .TP
 \fB\-r\fR, \fB\-\-regex\fR
 execute the command only on projects matching regex or
diff --git a/man/repo-grep.1 b/man/repo-grep.1
index fb515a7b..be410588 100644
--- a/man/repo-grep.1
+++ b/man/repo-grep.1
@@ -15,7 +15,8 @@ Print lines matching a pattern
 show this help message and exit
 .TP
 \fB\-j\fR JOBS, \fB\-\-jobs\fR=\fI\,JOBS\/\fR
-number of jobs to run in parallel (default: 4)
+number of jobs to run in parallel (default: based on
+number of CPU cores)
 .SS Logging options:
 .TP
 \fB\-\-verbose\fR
diff --git a/man/repo-prune.1 b/man/repo-prune.1
index 2479542c..bd68a373 100644
--- a/man/repo-prune.1
+++ b/man/repo-prune.1
@@ -15,7 +15,8 @@ Prune (delete) already merged topics
 show this help message and exit
 .TP
 \fB\-j\fR JOBS, \fB\-\-jobs\fR=\fI\,JOBS\/\fR
-number of jobs to run in parallel (default: 4)
+number of jobs to run in parallel (default: based on
+number of CPU cores)
 .SS Logging options:
 .TP
 \fB\-v\fR, \fB\-\-verbose\fR
diff --git a/man/repo-smartsync.1 b/man/repo-smartsync.1
index ad98b479..5d939117 100644
--- a/man/repo-smartsync.1
+++ b/man/repo-smartsync.1
@@ -15,7 +15,8 @@ Update working tree to the latest known good revision
 show this help message and exit
 .TP
 \fB\-j\fR JOBS, \fB\-\-jobs\fR=\fI\,JOBS\/\fR
-number of jobs to run in parallel (default: 1)
+number of jobs to run in parallel (default: based on
+number of CPU cores)
 .TP
 \fB\-\-jobs\-network\fR=\fI\,JOBS\/\fR
 number of network jobs to run in parallel (defaults to
diff --git a/man/repo-start.1 b/man/repo-start.1
index cda3739f..b00a31f4 100644
--- a/man/repo-start.1
+++ b/man/repo-start.1
@@ -15,7 +15,8 @@ Start a new branch for development
 show this help message and exit
 .TP
 \fB\-j\fR JOBS, \fB\-\-jobs\fR=\fI\,JOBS\/\fR
-number of jobs to run in parallel (default: 4)
+number of jobs to run in parallel (default: based on
+number of CPU cores)
 .TP
 \fB\-\-all\fR
 begin branch in all projects
diff --git a/man/repo-status.1 b/man/repo-status.1
index 6037ae1a..fbae2c5d 100644
--- a/man/repo-status.1
+++ b/man/repo-status.1
@@ -15,7 +15,8 @@ Show the working tree status
 show this help message and exit
 .TP
 \fB\-j\fR JOBS, \fB\-\-jobs\fR=\fI\,JOBS\/\fR
-number of jobs to run in parallel (default: 4)
+number of jobs to run in parallel (default: based on
+number of CPU cores)
 .TP
 \fB\-o\fR, \fB\-\-orphans\fR
 include objects in working directory outside of repo
diff --git a/man/repo-sync.1 b/man/repo-sync.1
index 70f7c207..c87c9701 100644
--- a/man/repo-sync.1
+++ b/man/repo-sync.1
@@ -15,7 +15,8 @@ Update working tree to the latest revision
 show this help message and exit
 .TP
 \fB\-j\fR JOBS, \fB\-\-jobs\fR=\fI\,JOBS\/\fR
-number of jobs to run in parallel (default: 1)
+number of jobs to run in parallel (default: based on
+number of CPU cores)
 .TP
 \fB\-\-jobs\-network\fR=\fI\,JOBS\/\fR
 number of network jobs to run in parallel (defaults to
diff --git a/man/repo-upload.1 b/man/repo-upload.1
index 6deed047..36a0daca 100644
--- a/man/repo-upload.1
+++ b/man/repo-upload.1
@@ -15,7 +15,8 @@ Upload changes for code review
 show this help message and exit
 .TP
 \fB\-j\fR JOBS, \fB\-\-jobs\fR=\fI\,JOBS\/\fR
-number of jobs to run in parallel (default: 4)
+number of jobs to run in parallel (default: based on
+number of CPU cores)
 .TP
 \fB\-t\fR
 send local branch name to Gerrit Code Review
diff --git a/release/update-manpages b/release/update-manpages
index f841f306..6ef3ec11 100755
--- a/release/update-manpages
+++ b/release/update-manpages
@@ -47,6 +47,11 @@ def main(argv):
   if not shutil.which('help2man'):
     sys.exit('Please install help2man to continue.')
 
+  # Let repo know we're generating man pages so it can avoid some dynamic
+  # behavior (like probing active number of CPUs).  We use a weird name &
+  # value to make it less likely for users to set this var themselves.
+  os.environ['_REPO_GENERATE_MANPAGES_'] = ' indeed! '
+
   # "repo branch" is an alias for "repo branches".
   del subcmds.all_commands['branch']
   (MANDIR / 'repo-branch.1').write_text('.so man1/repo-branches.1')