From 56345c345bdfdd71399d17ccd0ffe8f39bf720eb Mon Sep 17 00:00:00 2001 From: Mike Frysinger Date: Mon, 26 Jul 2021 23:46:32 -0400 Subject: repo: refactor help output handling Currently we have the behavior: * `repo`: Equivalent to `repo help` -- only shows common subcommands (with short description), and then exits 0. * `repo --help`: Shows repo's core options, lists all commands (no specific info), and then exits 0. The first case is not behaving well: * If you run `repo` without a specific subcommand, that's an error, so we should be exiting 1 instead. * Showing only subcommands and no actual option summary makes it seem like repo itself doesn't take any options. This confuses users. Let's rework things a bit. Now we have the behavior: * `repo`: Shows repo's core options, lists all commands (no specific info), and then exits 1. * `repo --help`: Shows repo's core options, shows common subcommands (with short description), and then exits 0. * `repo --help-all`: Shows repo's core options, shows all subcommands (with short description), and then exits 0. Basically we swap the behavior of `repo` and `repo --help`, and fix the exit status when the subcommand is missing. The addition of --help-all is mostly for the man pages. We were relying on `repo help --all` to generate the repo(1) man page, but that too omitted the core repo options. Now the man page includes all the core repo options and provides a summary of all commands. Change-Id: I1f99b99d5b8af2591f96a078d0647a3d76d6b0fc Reviewed-on: https://gerrit-review.googlesource.com/c/git-repo/+/312908 Reviewed-by: Xin Li Tested-by: Mike Frysinger --- man/repo.1 | 42 +++++++++++++++++++++++++++++++++++++++--- 1 file changed, 39 insertions(+), 3 deletions(-) (limited to 'man/repo.1') diff --git a/man/repo.1 b/man/repo.1 index 0bc3acdb..0e85b0b7 100644 --- a/man/repo.1 +++ b/man/repo.1 @@ -2,9 +2,44 @@ .TH REPO "1" "July 2021" "repo" "Repo Manual" .SH NAME repo \- repository management tool built on top of git -.SH DESCRIPTION -usage: repo COMMAND [ARGS] -The complete list of recognized repo commands are: +.SH SYNOPSIS +.B repo +[\fI\,-p|--paginate|--no-pager\/\fR] \fI\,COMMAND \/\fR[\fI\,ARGS\/\fR] +.SH OPTIONS +.TP +\fB\-h\fR, \fB\-\-help\fR +show this help message and exit +.TP +\fB\-\-help\-all\fR +show this help message with all subcommands and exit +.TP +\fB\-p\fR, \fB\-\-paginate\fR +display command output in the pager +.TP +\fB\-\-no\-pager\fR +disable the pager +.TP +\fB\-\-color\fR=\fI\,COLOR\/\fR +control color usage: auto, always, never +.TP +\fB\-\-trace\fR +trace git command execution (REPO_TRACE=1) +.TP +\fB\-\-trace\-python\fR +trace python command execution +.TP +\fB\-\-time\fR +time repo command execution +.TP +\fB\-\-version\fR +display this version of repo +.TP +\fB\-\-event\-log\fR=\fI\,EVENT_LOG\/\fR +filename of event log to append timeline to +.TP +\fB\-\-git\-trace2\-event\-log\fR=\fI\,GIT_TRACE2_EVENT_LOG\/\fR +directory to write git trace2 event log to +.SS "The complete list of recognized repo commands are:" .TP abandon Permanently abandon a development branch @@ -91,3 +126,4 @@ version Display the version of repo .PP See 'repo help ' for more information on a specific command. +Bug reports: https://bugs.chromium.org/p/gerrit/issues/entry?template=Repo+tool+issue -- cgit v1.2.3-54-g00ecf