From 0a1f533e2835c856473e3e4046341a4d2f66764b Mon Sep 17 00:00:00 2001 From: Roger Shimizu Date: Sun, 20 Jun 2021 21:41:05 +0900 Subject: Add script 'release/update-manpages' to generate manpages Debian package started to ship manpages for repo since 2.8 [1] And it's about for one year. So I think it should be upstreamed. The script depends on help2man, which is available in both debian [2] and ubuntu [3]. [1] https://tracker.debian.org/news/1150858/accepted-repo-28-1-source-into-unstable [2] https://tracker.debian.org/pkg/help2man [3] https://launchpad.net/ubuntu/+source/help2man Change-Id: Ide2b356d0944ebde34cc96c6d5a782655bd72288 Signed-off-by: Roger Shimizu Reviewed-on: https://gerrit-review.googlesource.com/c/git-repo/+/309782 Reviewed-by: Mike Frysinger --- man/repo-forall.1 | 127 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 127 insertions(+) create mode 100644 man/repo-forall.1 (limited to 'man/repo-forall.1') diff --git a/man/repo-forall.1 b/man/repo-forall.1 new file mode 100644 index 00000000..194f4d20 --- /dev/null +++ b/man/repo-forall.1 @@ -0,0 +1,127 @@ +.\" DO NOT MODIFY THIS FILE! It was generated by help2man. +.TH REPO "1" "July 2021" "repo forall" "Repo Manual" +.SH NAME +repo \- repo forall - manual page for repo forall +.SH SYNOPSIS +.B repo +\fI\,forall \/\fR[\fI\,\/\fR...] \fI\,-c \/\fR[\fI\,\/\fR...] +.SH DESCRIPTION +Summary +.PP +Run a shell command in each project +.PP +repo forall \fB\-r\fR str1 [str2] ... \fB\-c\fR [...] +.SH OPTIONS +.TP +\fB\-h\fR, \fB\-\-help\fR +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) +.TP +\fB\-r\fR, \fB\-\-regex\fR +execute the command only on projects matching regex or +wildcard expression +.TP +\fB\-i\fR, \fB\-\-inverse\-regex\fR +execute the command only on projects not matching +regex or wildcard expression +.TP +\fB\-g\fR GROUPS, \fB\-\-groups\fR=\fI\,GROUPS\/\fR +execute the command only on projects matching the +specified groups +.TP +\fB\-c\fR, \fB\-\-command\fR +command (and arguments) to execute +.TP +\fB\-e\fR, \fB\-\-abort\-on\-errors\fR +abort if a command exits unsuccessfully +.TP +\fB\-\-ignore\-missing\fR +silently skip & do not exit non\-zero due missing +checkouts +.TP +\fB\-\-interactive\fR +force interactive usage +.SS Logging options: +.TP +\fB\-v\fR, \fB\-\-verbose\fR +show all output +.TP +\fB\-q\fR, \fB\-\-quiet\fR +only show errors +.TP +\fB\-p\fR +show project headers before output +.PP +Run `repo help forall` to view the detailed manual. +.SH DETAILS +.PP +Executes the same shell command in each project. +.PP +The \fB\-r\fR option allows running the command only on projects matching regex or +wildcard expression. +.PP +By default, projects are processed non\-interactively in parallel. If you want to +run interactive commands, make sure to pass \fB\-\-interactive\fR to force \fB\-\-jobs\fR 1. +While the processing order of projects is not guaranteed, the order of project +output is stable. +.PP +Output Formatting +.PP +The \fB\-p\fR option causes 'repo forall' to bind pipes to the command's stdin, stdout +and stderr streams, and pipe all output into a continuous stream that is +displayed in a single pager session. Project headings are inserted before the +output of each command is displayed. If the command produces no output in a +project, no heading is displayed. +.PP +The formatting convention used by \fB\-p\fR is very suitable for some types of +searching, e.g. `repo forall \fB\-p\fR \fB\-c\fR git log \fB\-SFoo\fR` will print all commits that +add or remove references to Foo. +.PP +The \fB\-v\fR option causes 'repo forall' to display stderr messages if a command +produces output only on stderr. Normally the \fB\-p\fR option causes command output to +be suppressed until the command produces at least one byte of output on stdout. +.PP +Environment +.PP +pwd is the project's working directory. If the current client is a mirror +client, then pwd is the Git repository. +.PP +REPO_PROJECT is set to the unique name of the project. +.PP +REPO_PATH is the path relative the the root of the client. +.PP +REPO_REMOTE is the name of the remote system from the manifest. +.PP +REPO_LREV is the name of the revision from the manifest, translated to a local +tracking branch. If you need to pass the manifest revision to a locally executed +git command, use REPO_LREV. +.PP +REPO_RREV is the name of the revision from the manifest, exactly as written in +the manifest. +.PP +REPO_COUNT is the total number of projects being iterated. +.PP +REPO_I is the current (1\-based) iteration count. Can be used in conjunction with +REPO_COUNT to add a simple progress indicator to your command. +.PP +REPO__* are any extra environment variables, specified by the "annotation" +element under any project element. This can be useful for differentiating trees +based on user\-specific criteria, or simply annotating tree details. +.PP +shell positional arguments ($1, $2, .., $#) are set to any arguments following +. +.PP +Example: to list projects: +.IP +repo forall \fB\-c\fR 'echo $REPO_PROJECT' +.PP +Notice that $REPO_PROJECT is quoted to ensure it is expanded in the context of +running instead of in the calling shell. +.PP +Unless \fB\-p\fR is used, stdin, stdout, stderr are inherited from the terminal and are +not redirected. +.PP +If \fB\-e\fR is used, when a command exits unsuccessfully, 'repo forall' will abort +without iterating through the remaining projects. -- cgit v1.2.3-54-g00ecf