From 0a1f533e2835c856473e3e4046341a4d2f66764b Mon Sep 17 00:00:00 2001 From: Roger Shimizu Date: Sun, 20 Jun 2021 21:41:05 +0900 Subject: [PATCH] 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-abandon.1 | 35 +++ man/repo-branch.1 | 1 + man/repo-branches.1 | 58 +++++ man/repo-checkout.1 | 35 +++ man/repo-cherry-pick.1 | 28 ++ man/repo-diff.1 | 34 +++ man/repo-diffmanifests.1 | 61 +++++ man/repo-download.1 | 44 ++++ man/repo-forall.1 | 127 +++++++++ man/repo-gitc-delete.1 | 31 +++ man/repo-gitc-init.1 | 146 +++++++++++ man/repo-grep.1 | 118 +++++++++ man/repo-help.1 | 33 +++ man/repo-info.1 | 40 +++ man/repo-init.1 | 160 ++++++++++++ man/repo-list.1 | 57 ++++ man/repo-manifest.1 | 545 +++++++++++++++++++++++++++++++++++++++ man/repo-overview.1 | 39 +++ man/repo-prune.1 | 27 ++ man/repo-rebase.1 | 55 ++++ man/repo-selfupdate.1 | 35 +++ man/repo-smartsync.1 | 117 +++++++++ man/repo-stage.1 | 30 +++ man/repo-start.1 | 40 +++ man/repo-status.1 | 97 +++++++ man/repo-sync.1 | 208 +++++++++++++++ man/repo-upload.1 | 174 +++++++++++++ man/repo-version.1 | 24 ++ man/repo.1 | 93 +++++++ release/update-manpages | 85 ++++++ 30 files changed, 2577 insertions(+) create mode 100644 man/repo-abandon.1 create mode 100644 man/repo-branch.1 create mode 100644 man/repo-branches.1 create mode 100644 man/repo-checkout.1 create mode 100644 man/repo-cherry-pick.1 create mode 100644 man/repo-diff.1 create mode 100644 man/repo-diffmanifests.1 create mode 100644 man/repo-download.1 create mode 100644 man/repo-forall.1 create mode 100644 man/repo-gitc-delete.1 create mode 100644 man/repo-gitc-init.1 create mode 100644 man/repo-grep.1 create mode 100644 man/repo-help.1 create mode 100644 man/repo-info.1 create mode 100644 man/repo-init.1 create mode 100644 man/repo-list.1 create mode 100644 man/repo-manifest.1 create mode 100644 man/repo-overview.1 create mode 100644 man/repo-prune.1 create mode 100644 man/repo-rebase.1 create mode 100644 man/repo-selfupdate.1 create mode 100644 man/repo-smartsync.1 create mode 100644 man/repo-stage.1 create mode 100644 man/repo-start.1 create mode 100644 man/repo-status.1 create mode 100644 man/repo-sync.1 create mode 100644 man/repo-upload.1 create mode 100644 man/repo-version.1 create mode 100644 man/repo.1 create mode 100755 release/update-manpages diff --git a/man/repo-abandon.1 b/man/repo-abandon.1 new file mode 100644 index 00000000..fb3160c3 --- /dev/null +++ b/man/repo-abandon.1 @@ -0,0 +1,35 @@ +.\" DO NOT MODIFY THIS FILE! It was generated by help2man. +.TH REPO "1" "July 2021" "repo abandon" "Repo Manual" +.SH NAME +repo \- repo abandon - manual page for repo abandon +.SH SYNOPSIS +.B repo +\fI\,abandon \/\fR[\fI\,--all | \/\fR] [\fI\,\/\fR...] +.SH DESCRIPTION +Summary +.PP +Permanently abandon a development branch +.PP +This subcommand permanently abandons a development branch by +deleting it (and all its history) from your local repository. +.PP +It is equivalent to "git branch \fB\-D\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\-\-all\fR +delete all branches in all projects +.SS Logging options: +.TP +\fB\-v\fR, \fB\-\-verbose\fR +show all output +.TP +\fB\-q\fR, \fB\-\-quiet\fR +only show errors +.PP +Run `repo help abandon` to view the detailed manual. diff --git a/man/repo-branch.1 b/man/repo-branch.1 new file mode 100644 index 00000000..854ee98b --- /dev/null +++ b/man/repo-branch.1 @@ -0,0 +1 @@ +.so man1/repo-branches.1 \ No newline at end of file diff --git a/man/repo-branches.1 b/man/repo-branches.1 new file mode 100644 index 00000000..0080e467 --- /dev/null +++ b/man/repo-branches.1 @@ -0,0 +1,58 @@ +.\" DO NOT MODIFY THIS FILE! It was generated by help2man. +.TH REPO "1" "July 2021" "repo branches" "Repo Manual" +.SH NAME +repo \- repo branches - manual page for repo branches +.SH SYNOPSIS +.B repo +\fI\,branches \/\fR[\fI\,\/\fR...] +.SH DESCRIPTION +Summary +.PP +View current topic branches +.PP +Summarizes the currently available topic branches. +.PP +# Branch Display +.PP +The branch display output by this command is organized into four +columns of information; for example: +.TP +*P nocolor +| in repo +.TP +repo2 +| +.PP +The first column contains a * if the branch is the currently +checked out branch in any of the specified projects, or a blank +if no project has the branch checked out. +.PP +The second column contains either blank, p or P, depending upon +the upload status of the branch. +.IP +(blank): branch not yet published by repo upload +.IP +P: all commits were published by repo upload +p: only some commits were published by repo upload +.PP +The third column contains the branch name. +.PP +The fourth column (after the | separator) lists the projects that +the branch appears in, or does not appear in. If no project list +is shown, then the branch appears in all projects. +.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) +.SS Logging options: +.TP +\fB\-v\fR, \fB\-\-verbose\fR +show all output +.TP +\fB\-q\fR, \fB\-\-quiet\fR +only show errors +.PP +Run `repo help branches` to view the detailed manual. diff --git a/man/repo-checkout.1 b/man/repo-checkout.1 new file mode 100644 index 00000000..882b4baf --- /dev/null +++ b/man/repo-checkout.1 @@ -0,0 +1,35 @@ +.\" DO NOT MODIFY THIS FILE! It was generated by help2man. +.TH REPO "1" "July 2021" "repo checkout" "Repo Manual" +.SH NAME +repo \- repo checkout - manual page for repo checkout +.SH SYNOPSIS +.B repo +\fI\,checkout \/\fR[\fI\,\/\fR...] +.SH DESCRIPTION +Summary +.PP +Checkout a branch for development +.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) +.SS Logging options: +.TP +\fB\-v\fR, \fB\-\-verbose\fR +show all output +.TP +\fB\-q\fR, \fB\-\-quiet\fR +only show errors +.PP +Run `repo help checkout` to view the detailed manual. +.SH DETAILS +.PP +The 'repo checkout' command checks out an existing branch that was previously +created by 'repo start'. +.PP +The command is equivalent to: +.IP +repo forall [...] \fB\-c\fR git checkout diff --git a/man/repo-cherry-pick.1 b/man/repo-cherry-pick.1 new file mode 100644 index 00000000..e7716c55 --- /dev/null +++ b/man/repo-cherry-pick.1 @@ -0,0 +1,28 @@ +.\" DO NOT MODIFY THIS FILE! It was generated by help2man. +.TH REPO "1" "July 2021" "repo cherry-pick" "Repo Manual" +.SH NAME +repo \- repo cherry-pick - manual page for repo cherry-pick +.SH SYNOPSIS +.B repo +\fI\,cherry-pick \/\fR +.SH DESCRIPTION +Summary +.PP +Cherry\-pick a change. +.SH OPTIONS +.TP +\fB\-h\fR, \fB\-\-help\fR +show this help message and exit +.SS Logging options: +.TP +\fB\-v\fR, \fB\-\-verbose\fR +show all output +.TP +\fB\-q\fR, \fB\-\-quiet\fR +only show errors +.PP +Run `repo help cherry\-pick` to view the detailed manual. +.SH DETAILS +.PP +\&'repo cherry\-pick' cherry\-picks a change from one branch to another. The change +id will be updated, and a reference to the old change id will be added. diff --git a/man/repo-diff.1 b/man/repo-diff.1 new file mode 100644 index 00000000..aff36d24 --- /dev/null +++ b/man/repo-diff.1 @@ -0,0 +1,34 @@ +.\" DO NOT MODIFY THIS FILE! It was generated by help2man. +.TH REPO "1" "July 2021" "repo diff" "Repo Manual" +.SH NAME +repo \- repo diff - manual page for repo diff +.SH SYNOPSIS +.B repo +\fI\,diff \/\fR[\fI\,\/\fR...] +.SH DESCRIPTION +Summary +.PP +Show changes between commit and working tree +.PP +The \fB\-u\fR option causes 'repo diff' to generate diff output with file paths +relative to the repository root, so the output can be applied +to the Unix 'patch' command. +.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\-u\fR, \fB\-\-absolute\fR +paths are relative to the repository root +.SS Logging options: +.TP +\fB\-v\fR, \fB\-\-verbose\fR +show all output +.TP +\fB\-q\fR, \fB\-\-quiet\fR +only show errors +.PP +Run `repo help diff` to view the detailed manual. diff --git a/man/repo-diffmanifests.1 b/man/repo-diffmanifests.1 new file mode 100644 index 00000000..add50f17 --- /dev/null +++ b/man/repo-diffmanifests.1 @@ -0,0 +1,61 @@ +.\" DO NOT MODIFY THIS FILE! It was generated by help2man. +.TH REPO "1" "July 2021" "repo diffmanifests" "Repo Manual" +.SH NAME +repo \- repo diffmanifests - manual page for repo diffmanifests +.SH SYNOPSIS +.B repo +\fI\,diffmanifests manifest1.xml \/\fR[\fI\,manifest2.xml\/\fR] [\fI\,options\/\fR] +.SH DESCRIPTION +Summary +.PP +Manifest diff utility +.SH OPTIONS +.TP +\fB\-h\fR, \fB\-\-help\fR +show this help message and exit +.TP +\fB\-\-raw\fR +display raw diff +.TP +\fB\-\-no\-color\fR +does not display the diff in color +.TP +\fB\-\-pretty\-format=\fR +print the log using a custom git pretty format string +.SS Logging options: +.TP +\fB\-v\fR, \fB\-\-verbose\fR +show all output +.TP +\fB\-q\fR, \fB\-\-quiet\fR +only show errors +.PP +Run `repo help diffmanifests` to view the detailed manual. +.SH DETAILS +.PP +The repo diffmanifests command shows differences between project revisions of +manifest1 and manifest2. if manifest2 is not specified, current manifest.xml +will be used instead. Both absolute and relative paths may be used for +manifests. Relative paths start from project's ".repo/manifests" folder. +.PP +The \fB\-\-raw\fR option Displays the diff in a way that facilitates parsing, the +project pattern will be [] and the +commit pattern will be with status values respectively : +.IP +A = Added project +R = Removed project +C = Changed project +U = Project with unreachable revision(s) (revision(s) not found) +.PP +for project, and +.IP +A = Added commit +R = Removed commit +.PP +for a commit. +.PP +Only changed projects may contain commits, and commit status always starts with +a space, and are part of last printed project. Unreachable revisions may occur +if project is not up to date or if repo has not been initialized with all the +groups, in which case some projects won't be synced and their revisions won't be +found. diff --git a/man/repo-download.1 b/man/repo-download.1 new file mode 100644 index 00000000..cf7f767d --- /dev/null +++ b/man/repo-download.1 @@ -0,0 +1,44 @@ +.\" DO NOT MODIFY THIS FILE! It was generated by help2man. +.TH REPO "1" "July 2021" "repo download" "Repo Manual" +.SH NAME +repo \- repo download - manual page for repo download +.SH SYNOPSIS +.B repo +\fI\,download {\/\fR[\fI\,project\/\fR] \fI\,change\/\fR[\fI\,/patchset\/\fR]\fI\,}\/\fR... +.SH DESCRIPTION +Summary +.PP +Download and checkout a change +.SH OPTIONS +.TP +\fB\-h\fR, \fB\-\-help\fR +show this help message and exit +.TP +\fB\-b\fR BRANCH, \fB\-\-branch\fR=\fI\,BRANCH\/\fR +create a new branch first +.TP +\fB\-c\fR, \fB\-\-cherry\-pick\fR +cherry\-pick instead of checkout +.TP +\fB\-x\fR, \fB\-\-record\-origin\fR +pass \fB\-x\fR when cherry\-picking +.TP +\fB\-r\fR, \fB\-\-revert\fR +revert instead of checkout +.TP +\fB\-f\fR, \fB\-\-ff\-only\fR +force fast\-forward merge +.SS Logging options: +.TP +\fB\-v\fR, \fB\-\-verbose\fR +show all output +.TP +\fB\-q\fR, \fB\-\-quiet\fR +only show errors +.PP +Run `repo help download` to view the detailed manual. +.SH DETAILS +.PP +The 'repo download' command downloads a change from the review system and makes +it available in your project's local working directory. If no project is +specified try to use current directory as a project. 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. diff --git a/man/repo-gitc-delete.1 b/man/repo-gitc-delete.1 new file mode 100644 index 00000000..c84c6e45 --- /dev/null +++ b/man/repo-gitc-delete.1 @@ -0,0 +1,31 @@ +.\" DO NOT MODIFY THIS FILE! It was generated by help2man. +.TH REPO "1" "July 2021" "repo gitc-delete" "Repo Manual" +.SH NAME +repo \- repo gitc-delete - manual page for repo gitc-delete +.SH SYNOPSIS +.B repo +\fI\,gitc-delete\/\fR +.SH DESCRIPTION +Summary +.PP +Delete a GITC Client. +.SH OPTIONS +.TP +\fB\-h\fR, \fB\-\-help\fR +show this help message and exit +.TP +\fB\-f\fR, \fB\-\-force\fR +force the deletion (no prompt) +.SS Logging options: +.TP +\fB\-v\fR, \fB\-\-verbose\fR +show all output +.TP +\fB\-q\fR, \fB\-\-quiet\fR +only show errors +.PP +Run `repo help gitc\-delete` to view the detailed manual. +.SH DETAILS +.PP +This subcommand deletes the current GITC client, deleting the GITC manifest and +all locally downloaded sources. diff --git a/man/repo-gitc-init.1 b/man/repo-gitc-init.1 new file mode 100644 index 00000000..1d1b23a8 --- /dev/null +++ b/man/repo-gitc-init.1 @@ -0,0 +1,146 @@ +.\" DO NOT MODIFY THIS FILE! It was generated by help2man. +.TH REPO "1" "July 2021" "repo gitc-init" "Repo Manual" +.SH NAME +repo \- repo gitc-init - manual page for repo gitc-init +.SH SYNOPSIS +.B repo +\fI\,gitc-init \/\fR[\fI\,options\/\fR] [\fI\,client name\/\fR] +.SH DESCRIPTION +Summary +.PP +Initialize a GITC Client. +.SH OPTIONS +.TP +\fB\-h\fR, \fB\-\-help\fR +show this help message and exit +.SS Logging options: +.TP +\fB\-v\fR, \fB\-\-verbose\fR +show all output +.TP +\fB\-q\fR, \fB\-\-quiet\fR +only show errors +.SS Manifest options: +.TP +\fB\-u\fR URL, \fB\-\-manifest\-url\fR=\fI\,URL\/\fR +manifest repository location +.TP +\fB\-b\fR REVISION, \fB\-\-manifest\-branch\fR=\fI\,REVISION\/\fR +manifest branch or revision (use HEAD for default) +.TP +\fB\-m\fR NAME.xml, \fB\-\-manifest\-name\fR=\fI\,NAME\/\fR.xml +initial manifest file +.TP +\fB\-g\fR GROUP, \fB\-\-groups\fR=\fI\,GROUP\/\fR +restrict manifest projects to ones with specified +group(s) [default|all|G1,G2,G3|G4,\-G5,\-G6] +.TP +\fB\-p\fR PLATFORM, \fB\-\-platform\fR=\fI\,PLATFORM\/\fR +restrict manifest projects to ones with a specified +platform group [auto|all|none|linux|darwin|...] +.TP +\fB\-\-submodules\fR +sync any submodules associated with the manifest repo +.SS Manifest (only) checkout options: +.TP +\fB\-\-current\-branch\fR +fetch only current manifest branch from server +.TP +\fB\-\-no\-current\-branch\fR +fetch all manifest branches from server +.TP +\fB\-\-tags\fR +fetch tags in the manifest +.TP +\fB\-\-no\-tags\fR +don't fetch tags in the manifest +.SS Checkout modes: +.TP +\fB\-\-mirror\fR +create a replica of the remote repositories rather +than a client working directory +.TP +\fB\-\-archive\fR +checkout an archive instead of a git repository for +each project. See git archive. +.TP +\fB\-\-worktree\fR +use git\-worktree to manage projects +.SS Project checkout optimizations: +.TP +\fB\-\-reference\fR=\fI\,DIR\/\fR +location of mirror directory +.TP +\fB\-\-dissociate\fR +dissociate from reference mirrors after clone +.TP +\fB\-\-depth\fR=\fI\,DEPTH\/\fR +create a shallow clone with given depth; see git clone +.TP +\fB\-\-partial\-clone\fR +perform partial clone (https://gitscm.com/docs/gitrepositorylayout#_code_partialclone_code) +.TP +\fB\-\-no\-partial\-clone\fR +disable use of partial clone (https://gitscm.com/docs/gitrepositorylayout#_code_partialclone_code) +.TP +\fB\-\-partial\-clone\-exclude\fR=\fI\,PARTIAL_CLONE_EXCLUDE\/\fR +exclude the specified projects (a comma\-delimited +project names) from partial clone (https://gitscm.com/docs/gitrepositorylayout#_code_partialclone_code) +.TP +\fB\-\-clone\-filter\fR=\fI\,CLONE_FILTER\/\fR +filter for use with \fB\-\-partial\-clone\fR [default: +blob:none] +.TP +\fB\-\-use\-superproject\fR +use the manifest superproject to sync projects +.TP +\fB\-\-no\-use\-superproject\fR +disable use of manifest superprojects +.TP +\fB\-\-clone\-bundle\fR +enable use of \fI\,/clone.bundle\/\fP on HTTP/HTTPS (default if +not \fB\-\-partial\-clone\fR) +.TP +\fB\-\-no\-clone\-bundle\fR +disable use of \fI\,/clone.bundle\/\fP on HTTP/HTTPS (default if +\fB\-\-partial\-clone\fR) +.SS repo Version options: +.TP +\fB\-\-repo\-url\fR=\fI\,URL\/\fR +repo repository location ($REPO_URL) +.TP +\fB\-\-repo\-rev\fR=\fI\,REV\/\fR +repo branch or revision ($REPO_REV) +.TP +\fB\-\-no\-repo\-verify\fR +do not verify repo source code +.SS Other options: +.TP +\fB\-\-config\-name\fR +Always prompt for name/e\-mail +.SS GITC options: +.TP +\fB\-f\fR MANIFEST_FILE, \fB\-\-manifest\-file\fR=\fI\,MANIFEST_FILE\/\fR +Optional manifest file to use for this GITC client. +.TP +\fB\-c\fR GITC_CLIENT, \fB\-\-gitc\-client\fR=\fI\,GITC_CLIENT\/\fR +Name of the gitc_client instance to create or modify. +.PP +Run `repo help gitc\-init` to view the detailed manual. +.SH DETAILS +.PP +The 'repo gitc\-init' command is ran to initialize a new GITC client for use with +the GITC file system. +.PP +This command will setup the client directory, initialize repo, just like repo +init does, and then downloads the manifest collection and installs it in the +\&.repo/directory of the GITC client. +.PP +Once this is done, a GITC manifest is generated by pulling the HEAD SHA for each +project and generates the properly formatted XML file and installs it as +\&.manifest in the GITC client directory. +.PP +The \fB\-c\fR argument is required to specify the GITC client name. +.PP +The optional \fB\-f\fR argument can be used to specify the manifest file to use for +this GITC client. diff --git a/man/repo-grep.1 b/man/repo-grep.1 new file mode 100644 index 00000000..fb515a7b --- /dev/null +++ b/man/repo-grep.1 @@ -0,0 +1,118 @@ +.\" DO NOT MODIFY THIS FILE! It was generated by help2man. +.TH REPO "1" "July 2021" "repo grep" "Repo Manual" +.SH NAME +repo \- repo grep - manual page for repo grep +.SH SYNOPSIS +.B repo +\fI\,grep {pattern | -e pattern} \/\fR[\fI\,\/\fR...] +.SH DESCRIPTION +Summary +.PP +Print lines matching a pattern +.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) +.SS Logging options: +.TP +\fB\-\-verbose\fR +show all output +.TP +\fB\-q\fR, \fB\-\-quiet\fR +only show errors +.SS Sources: +.TP +\fB\-\-cached\fR +Search the index, instead of the work tree +.TP +\fB\-r\fR TREEish, \fB\-\-revision\fR=\fI\,TREEish\/\fR +Search TREEish, instead of the work tree +.SS Pattern: +.TP +\fB\-e\fR PATTERN +Pattern to search for +.TP +\fB\-i\fR, \fB\-\-ignore\-case\fR +Ignore case differences +.TP +\fB\-a\fR, \fB\-\-text\fR +Process binary files as if they were text +.TP +\fB\-I\fR +Don't match the pattern in binary files +.TP +\fB\-w\fR, \fB\-\-word\-regexp\fR +Match the pattern only at word boundaries +.TP +\fB\-v\fR, \fB\-\-invert\-match\fR +Select non\-matching lines +.TP +\fB\-G\fR, \fB\-\-basic\-regexp\fR +Use POSIX basic regexp for patterns (default) +.TP +\fB\-E\fR, \fB\-\-extended\-regexp\fR +Use POSIX extended regexp for patterns +.TP +\fB\-F\fR, \fB\-\-fixed\-strings\fR +Use fixed strings (not regexp) for pattern +.SS Pattern Grouping: +.TP +\fB\-\-all\-match\fR +Limit match to lines that have all patterns +.TP +\fB\-\-and\fR, \fB\-\-or\fR, \fB\-\-not\fR +Boolean operators to combine patterns +.TP +\-(, \-) +Boolean operator grouping +.SS Output: +.TP +\fB\-n\fR +Prefix the line number to matching lines +.TP +\fB\-C\fR CONTEXT +Show CONTEXT lines around match +.TP +\fB\-B\fR CONTEXT +Show CONTEXT lines before match +.TP +\fB\-A\fR CONTEXT +Show CONTEXT lines after match +.TP +\fB\-l\fR, \fB\-\-name\-only\fR, \fB\-\-files\-with\-matches\fR +Show only file names containing matching lines +.TP +\fB\-L\fR, \fB\-\-files\-without\-match\fR +Show only file names not containing matching lines +.PP +Run `repo help grep` to view the detailed manual. +.SH DETAILS +.PP +Search for the specified patterns in all project files. +.PP +Boolean Options +.PP +The following options can appear as often as necessary to express the pattern to +locate: +.HP +\fB\-e\fR PATTERN +.HP +\fB\-\-and\fR, \fB\-\-or\fR, \fB\-\-not\fR, \-(, \-) +.PP +Further, the \fB\-r\fR/\-\-revision option may be specified multiple times in order to +scan multiple trees. If the same file matches in more than one tree, only the +first result is reported, prefixed by the revision name it was found under. +.PP +Examples +.PP +Look for a line that has '#define' and either 'MAX_PATH or 'PATH_MAX': +.IP +repo grep \fB\-e\fR '#define' \fB\-\-and\fR \-\e( \fB\-e\fR MAX_PATH \fB\-e\fR PATH_MAX \e) +.PP +Look for a line that has 'NODE' or 'Unexpected' in files that contain a line +that matches both expressions: +.IP +repo grep \fB\-\-all\-match\fR \fB\-e\fR NODE \fB\-e\fR Unexpected diff --git a/man/repo-help.1 b/man/repo-help.1 new file mode 100644 index 00000000..d6da3c51 --- /dev/null +++ b/man/repo-help.1 @@ -0,0 +1,33 @@ +.\" DO NOT MODIFY THIS FILE! It was generated by help2man. +.TH REPO "1" "July 2021" "repo help" "Repo Manual" +.SH NAME +repo \- repo help - manual page for repo help +.SH SYNOPSIS +.B repo +\fI\,help \/\fR[\fI\,--all|command\/\fR] +.SH DESCRIPTION +Summary +.PP +Display detailed help on a command +.SH OPTIONS +.TP +\fB\-h\fR, \fB\-\-help\fR +show this help message and exit +.TP +\fB\-a\fR, \fB\-\-all\fR +show the complete list of commands +.TP +\fB\-\-help\-all\fR +show the \fB\-\-help\fR of all commands +.SS Logging options: +.TP +\fB\-v\fR, \fB\-\-verbose\fR +show all output +.TP +\fB\-q\fR, \fB\-\-quiet\fR +only show errors +.PP +Run `repo help help` to view the detailed manual. +.SH DETAILS +.PP +Displays detailed usage information about a command. diff --git a/man/repo-info.1 b/man/repo-info.1 new file mode 100644 index 00000000..cf7c17b8 --- /dev/null +++ b/man/repo-info.1 @@ -0,0 +1,40 @@ +.\" DO NOT MODIFY THIS FILE! It was generated by help2man. +.TH REPO "1" "July 2021" "repo info" "Repo Manual" +.SH NAME +repo \- repo info - manual page for repo info +.SH SYNOPSIS +.B repo +\fI\,info \/\fR[\fI\,-dl\/\fR] [\fI\,-o \/\fR[\fI\,-c\/\fR]] [\fI\,\/\fR...] +.SH DESCRIPTION +Summary +.PP +Get info on the manifest branch, current branch or unmerged branches +.SH OPTIONS +.TP +\fB\-h\fR, \fB\-\-help\fR +show this help message and exit +.TP +\fB\-d\fR, \fB\-\-diff\fR +show full info and commit diff including remote +branches +.TP +\fB\-o\fR, \fB\-\-overview\fR +show overview of all local commits +.TP +\fB\-c\fR, \fB\-\-current\-branch\fR +consider only checked out branches +.TP +\fB\-\-no\-current\-branch\fR +consider all local branches +.TP +\fB\-l\fR, \fB\-\-local\-only\fR +disable all remote operations +.SS Logging options: +.TP +\fB\-v\fR, \fB\-\-verbose\fR +show all output +.TP +\fB\-q\fR, \fB\-\-quiet\fR +only show errors +.PP +Run `repo help info` to view the detailed manual. diff --git a/man/repo-init.1 b/man/repo-init.1 new file mode 100644 index 00000000..e860f95d --- /dev/null +++ b/man/repo-init.1 @@ -0,0 +1,160 @@ +.\" DO NOT MODIFY THIS FILE! It was generated by help2man. +.TH REPO "1" "July 2021" "repo init" "Repo Manual" +.SH NAME +repo \- repo init - manual page for repo init +.SH SYNOPSIS +.B repo +\fI\,init \/\fR[\fI\,options\/\fR] [\fI\,manifest url\/\fR] +.SH DESCRIPTION +Summary +.PP +Initialize a repo client checkout in the current directory +.SH OPTIONS +.TP +\fB\-h\fR, \fB\-\-help\fR +show this help message and exit +.SS Logging options: +.TP +\fB\-v\fR, \fB\-\-verbose\fR +show all output +.TP +\fB\-q\fR, \fB\-\-quiet\fR +only show errors +.SS Manifest options: +.TP +\fB\-u\fR URL, \fB\-\-manifest\-url\fR=\fI\,URL\/\fR +manifest repository location +.TP +\fB\-b\fR REVISION, \fB\-\-manifest\-branch\fR=\fI\,REVISION\/\fR +manifest branch or revision (use HEAD for default) +.TP +\fB\-m\fR NAME.xml, \fB\-\-manifest\-name\fR=\fI\,NAME\/\fR.xml +initial manifest file +.TP +\fB\-g\fR GROUP, \fB\-\-groups\fR=\fI\,GROUP\/\fR +restrict manifest projects to ones with specified +group(s) [default|all|G1,G2,G3|G4,\-G5,\-G6] +.TP +\fB\-p\fR PLATFORM, \fB\-\-platform\fR=\fI\,PLATFORM\/\fR +restrict manifest projects to ones with a specified +platform group [auto|all|none|linux|darwin|...] +.TP +\fB\-\-submodules\fR +sync any submodules associated with the manifest repo +.SS Manifest (only) checkout options: +.TP +\fB\-c\fR, \fB\-\-current\-branch\fR +fetch only current manifest branch from server +.TP +\fB\-\-no\-current\-branch\fR +fetch all manifest branches from server +.TP +\fB\-\-tags\fR +fetch tags in the manifest +.TP +\fB\-\-no\-tags\fR +don't fetch tags in the manifest +.SS Checkout modes: +.TP +\fB\-\-mirror\fR +create a replica of the remote repositories rather +than a client working directory +.TP +\fB\-\-archive\fR +checkout an archive instead of a git repository for +each project. See git archive. +.TP +\fB\-\-worktree\fR +use git\-worktree to manage projects +.SS Project checkout optimizations: +.TP +\fB\-\-reference\fR=\fI\,DIR\/\fR +location of mirror directory +.TP +\fB\-\-dissociate\fR +dissociate from reference mirrors after clone +.TP +\fB\-\-depth\fR=\fI\,DEPTH\/\fR +create a shallow clone with given depth; see git clone +.TP +\fB\-\-partial\-clone\fR +perform partial clone (https://gitscm.com/docs/gitrepositorylayout#_code_partialclone_code) +.TP +\fB\-\-no\-partial\-clone\fR +disable use of partial clone (https://gitscm.com/docs/gitrepositorylayout#_code_partialclone_code) +.TP +\fB\-\-partial\-clone\-exclude\fR=\fI\,PARTIAL_CLONE_EXCLUDE\/\fR +exclude the specified projects (a comma\-delimited +project names) from partial clone (https://gitscm.com/docs/gitrepositorylayout#_code_partialclone_code) +.TP +\fB\-\-clone\-filter\fR=\fI\,CLONE_FILTER\/\fR +filter for use with \fB\-\-partial\-clone\fR [default: +blob:none] +.TP +\fB\-\-use\-superproject\fR +use the manifest superproject to sync projects +.TP +\fB\-\-no\-use\-superproject\fR +disable use of manifest superprojects +.TP +\fB\-\-clone\-bundle\fR +enable use of \fI\,/clone.bundle\/\fP on HTTP/HTTPS (default if +not \fB\-\-partial\-clone\fR) +.TP +\fB\-\-no\-clone\-bundle\fR +disable use of \fI\,/clone.bundle\/\fP on HTTP/HTTPS (default if +\fB\-\-partial\-clone\fR) +.SS repo Version options: +.TP +\fB\-\-repo\-url\fR=\fI\,URL\/\fR +repo repository location ($REPO_URL) +.TP +\fB\-\-repo\-rev\fR=\fI\,REV\/\fR +repo branch or revision ($REPO_REV) +.TP +\fB\-\-no\-repo\-verify\fR +do not verify repo source code +.SS Other options: +.TP +\fB\-\-config\-name\fR +Always prompt for name/e\-mail +.PP +Run `repo help init` to view the detailed manual. +.SH DETAILS +.PP +The 'repo init' command is run once to install and initialize repo. The latest +repo source code and manifest collection is downloaded from the server and is +installed in the .repo/ directory in the current working directory. +.PP +When creating a new checkout, the manifest URL is the only required setting. It +may be specified using the \fB\-\-manifest\-url\fR option, or as the first optional +argument. +.PP +The optional \fB\-b\fR argument can be used to select the manifest branch to checkout +and use. If no branch is specified, the remote's default branch is used. This is +equivalent to using \fB\-b\fR HEAD. +.PP +The optional \fB\-m\fR argument can be used to specify an alternate manifest to be +used. If no manifest is specified, the manifest default.xml will be used. +.PP +The \fB\-\-reference\fR option can be used to point to a directory that has the content +of a \fB\-\-mirror\fR sync. This will make the working directory use as much data as +possible from the local reference directory when fetching from the server. This +will make the sync go a lot faster by reducing data traffic on the network. +.PP +The \fB\-\-dissociate\fR option can be used to borrow the objects from the directory +specified with the \fB\-\-reference\fR option only to reduce network transfer, and stop +borrowing from them after a first clone is made by making necessary local copies +of borrowed objects. +.PP +The \fB\-\-no\-clone\-bundle\fR option disables any attempt to use \fI\,$URL/clone.bundle\/\fP to +bootstrap a new Git repository from a resumeable bundle file on a content +delivery network. This may be necessary if there are problems with the local +Python HTTP client or proxy configuration, but the Git binary works. +.PP +Switching Manifest Branches +.PP +To switch to another manifest branch, `repo init \fB\-b\fR otherbranch` may be used in +an existing client. However, as this only updates the manifest, a subsequent +`repo sync` (or `repo sync \fB\-d\fR`) is necessary to update the working directory +files. diff --git a/man/repo-list.1 b/man/repo-list.1 new file mode 100644 index 00000000..a86315ae --- /dev/null +++ b/man/repo-list.1 @@ -0,0 +1,57 @@ +.\" DO NOT MODIFY THIS FILE! It was generated by help2man. +.TH REPO "1" "July 2021" "repo list" "Repo Manual" +.SH NAME +repo \- repo list - manual page for repo list +.SH SYNOPSIS +.B repo +\fI\,list \/\fR[\fI\,-f\/\fR] [\fI\,\/\fR...] +.SH DESCRIPTION +Summary +.PP +List projects and their associated directories +.PP +repo list [\-f] \fB\-r\fR str1 [str2]... +.SH OPTIONS +.TP +\fB\-h\fR, \fB\-\-help\fR +show this help message and exit +.TP +\fB\-r\fR, \fB\-\-regex\fR +filter the project list based on regex or wildcard +matching of strings +.TP +\fB\-g\fR GROUPS, \fB\-\-groups\fR=\fI\,GROUPS\/\fR +filter the project list based on the groups the +project is in +.TP +\fB\-a\fR, \fB\-\-all\fR +show projects regardless of checkout state +.TP +\fB\-f\fR, \fB\-\-fullpath\fR +display the full work tree path instead of the +relative path +.TP +\fB\-n\fR, \fB\-\-name\-only\fR +display only the name of the repository +.TP +\fB\-p\fR, \fB\-\-path\-only\fR +display only the path of the repository +.SS Logging options: +.TP +\fB\-v\fR, \fB\-\-verbose\fR +show all output +.TP +\fB\-q\fR, \fB\-\-quiet\fR +only show errors +.PP +Run `repo help list` to view the detailed manual. +.SH DETAILS +.PP +List all projects; pass '.' to list the project for the cwd. +.PP +By default, only projects that currently exist in the checkout are shown. If you +want to list all projects (using the specified filter settings), use the \fB\-\-all\fR +option. If you want to show all projects regardless of the manifest groups, then +also pass \fB\-\-groups\fR all. +.PP +This is similar to running: repo forall \fB\-c\fR 'echo "$REPO_PATH : $REPO_PROJECT"'. diff --git a/man/repo-manifest.1 b/man/repo-manifest.1 new file mode 100644 index 00000000..e42cc42e --- /dev/null +++ b/man/repo-manifest.1 @@ -0,0 +1,545 @@ +.\" DO NOT MODIFY THIS FILE! It was generated by help2man. +.TH REPO "1" "July 2021" "repo manifest" "Repo Manual" +.SH NAME +repo \- repo manifest - manual page for repo manifest +.SH SYNOPSIS +.B repo +\fI\,manifest \/\fR[\fI\,-o {-|NAME.xml}\/\fR] [\fI\,-m MANIFEST.xml\/\fR] [\fI\,-r\/\fR] +.SH DESCRIPTION +Summary +.PP +Manifest inspection utility +.SH OPTIONS +.TP +\fB\-h\fR, \fB\-\-help\fR +show this help message and exit +.TP +\fB\-r\fR, \fB\-\-revision\-as\-HEAD\fR +save revisions as current HEAD +.TP +\fB\-m\fR NAME.xml, \fB\-\-manifest\-name\fR=\fI\,NAME\/\fR.xml +temporary manifest to use for this sync +.TP +\fB\-\-suppress\-upstream\-revision\fR +if in \fB\-r\fR mode, do not write the upstream field (only +of use if the branch names for a sha1 manifest are +sensitive) +.TP +\fB\-\-suppress\-dest\-branch\fR +if in \fB\-r\fR mode, do not write the dest\-branch field +(only of use if the branch names for a sha1 manifest +are sensitive) +.TP +\fB\-\-json\fR +output manifest in JSON format (experimental) +.TP +\fB\-\-pretty\fR +format output for humans to read +.TP +\fB\-o\fR \-|NAME.xml, \fB\-\-output\-file\fR=\fI\,\-\/\fR|NAME.xml +file to save the manifest to +.SS Logging options: +.TP +\fB\-v\fR, \fB\-\-verbose\fR +show all output +.TP +\fB\-q\fR, \fB\-\-quiet\fR +only show errors +.PP +Run `repo help manifest` to view the detailed manual. +.SH DETAILS +.PP +With the \fB\-o\fR option, exports the current manifest for inspection. The manifest +and (if present) local_manifests/ are combined together to produce a single +manifest file. This file can be stored in a Git repository for use during future +\&'repo init' invocations. +.PP +The \fB\-r\fR option can be used to generate a manifest file with project revisions set +to the current commit hash. These are known as "revision locked manifests", as +they don't follow a particular branch. In this case, the 'upstream' attribute is +set to the ref we were on when the manifest was generated. The 'dest\-branch' +attribute is set to indicate the remote ref to push changes to via 'repo +upload'. +.PP +repo Manifest Format +.PP +A repo manifest describes the structure of a repo client; that is the +directories that are visible and where they should be obtained from with git. +.PP +The basic structure of a manifest is a bare Git repository holding a single +`default.xml` XML file in the top level directory. +.PP +Manifests are inherently version controlled, since they are kept within a Git +repository. Updates to manifests are automatically obtained by clients during +`repo sync`. +.PP +[TOC] +.PP +XML File Format +.PP +A manifest XML file (e.g. `default.xml`) roughly conforms to the following DTD: +.PP +```xml +.IP + +.IP + + + + + + + +.IP + + + + + + + + + +.IP + + +.TP + +.TP + +.TP + +.TP + +.TP + +.IP + + + + + + + + +.IP + + + + +.IP + + + +.IP + + + +.IP + + + + + + +.IP + + + +.IP + + + +.IP + + + +.IP + + +.IP + + + +.PP +]> +``` +.PP +For compatibility purposes across repo releases, all unknown elements are +silently ignored. However, repo reserves all possible names for itself for +future use. If you want to use custom elements, the `x\-*` namespace is reserved +for that purpose, and repo guarantees to never allocate any corresponding names. +.PP +A description of the elements and their attributes follows. +.PP +Element manifest +.PP +The root element of the file. +.PP +Element notice +.PP +Arbitrary text that is displayed to users whenever `repo sync` finishes. The +content is simply passed through as it exists in the manifest. +.PP +Element remote +.PP +One or more remote elements may be specified. Each remote element specifies a +Git URL shared by one or more projects and (optionally) the Gerrit review server +those projects upload changes through. +.PP +Attribute `name`: A short name unique to this manifest file. The name specified +here is used as the remote name in each project's .git/config, and is therefore +automatically available to commands like `git fetch`, `git remote`, `git pull` +and `git push`. +.PP +Attribute `alias`: The alias, if specified, is used to override `name` to be set +as the remote name in each project's .git/config. Its value can be duplicated +while attribute `name` has to be unique in the manifest file. This helps each +project to be able to have same remote name which actually points to different +remote url. +.PP +Attribute `fetch`: The Git URL prefix for all projects which use this remote. +Each project's name is appended to this prefix to form the actual URL used to +clone the project. +.PP +Attribute `pushurl`: The Git "push" URL prefix for all projects which use this +remote. Each project's name is appended to this prefix to form the actual URL +used to "git push" the project. This attribute is optional; if not specified +then "git push" will use the same URL as the `fetch` attribute. +.PP +Attribute `review`: Hostname of the Gerrit server where reviews are uploaded to +by `repo upload`. This attribute is optional; if not specified then `repo +upload` will not function. +.PP +Attribute `revision`: Name of a Git branch (e.g. `main` or `refs/heads/main`). +Remotes with their own revision will override the default revision. +.PP +Element default +.PP +At most one default element may be specified. Its remote and revision attributes +are used when a project element does not specify its own remote or revision +attribute. +.PP +Attribute `remote`: Name of a previously defined remote element. Project +elements lacking a remote attribute of their own will use this remote. +.PP +Attribute `revision`: Name of a Git branch (e.g. `main` or `refs/heads/main`). +Project elements lacking their own revision attribute will use this revision. +.PP +Attribute `dest\-branch`: Name of a Git branch (e.g. `main`). Project elements +not setting their own `dest\-branch` will inherit this value. If this value is +not set, projects will use `revision` by default instead. +.PP +Attribute `upstream`: Name of the Git ref in which a sha1 can be found. Used +when syncing a revision locked manifest in \fB\-c\fR mode to avoid having to sync the +entire ref space. Project elements not setting their own `upstream` will inherit +this value. +.PP +Attribute `sync\-j`: Number of parallel jobs to use when synching. +.PP +Attribute `sync\-c`: Set to true to only sync the given Git branch (specified in +the `revision` attribute) rather than the whole ref space. Project elements +lacking a sync\-c element of their own will use this value. +.PP +Attribute `sync\-s`: Set to true to also sync sub\-projects. +.PP +Attribute `sync\-tags`: Set to false to only sync the given Git branch (specified +in the `revision` attribute) rather than the other ref tags. +.PP +Element manifest\-server +.PP +At most one manifest\-server may be specified. The url attribute is used to +specify the URL of a manifest server, which is an XML RPC service. +.PP +The manifest server should implement the following RPC methods: +.IP +GetApprovedManifest(branch, target) +.PP +Return a manifest in which each project is pegged to a known good revision for +the current branch and target. This is used by repo sync when the \fB\-\-smart\-sync\fR +option is given. +.PP +The target to use is defined by environment variables TARGET_PRODUCT and +TARGET_BUILD_VARIANT. These variables are used to create a string of the form +$TARGET_PRODUCT\-$TARGET_BUILD_VARIANT, e.g. passion\-userdebug. If one of those +variables or both are not present, the program will call GetApprovedManifest +without the target parameter and the manifest server should choose a reasonable +default target. +.IP +GetManifest(tag) +.PP +Return a manifest in which each project is pegged to the revision at the +specified tag. This is used by repo sync when the \fB\-\-smart\-tag\fR option is given. +.PP +Element project +.PP +One or more project elements may be specified. Each element describes a single +Git repository to be cloned into the repo client workspace. You may specify +Git\-submodules by creating a nested project. Git\-submodules will be +automatically recognized and inherit their parent's attributes, but those may be +overridden by an explicitly specified project element. +.PP +Attribute `name`: A unique name for this project. The project's name is appended +onto its remote's fetch URL to generate the actual URL to configure the Git +remote with. The URL gets formed as: +.IP +${remote_fetch}/${project_name}.git +.PP +where ${remote_fetch} is the remote's fetch attribute and ${project_name} is the +project's name attribute. The suffix ".git" is always appended as repo assumes +the upstream is a forest of bare Git repositories. If the project has a parent +element, its name will be prefixed by the parent's. +.PP +The project name must match the name Gerrit knows, if Gerrit is being used for +code reviews. +.PP +"name" must not be empty, and may not be an absolute path or use "." or ".." +path components. It is always interpreted relative to the remote's fetch +settings, so if a different base path is needed, declare a different remote with +the new settings needed. These restrictions are not enforced for [Local +Manifests]. +.PP +Attribute `path`: An optional path relative to the top directory of the repo +client where the Git working directory for this project should be placed. If not +supplied the project "name" is used. If the project has a parent element, its +path will be prefixed by the parent's. +.PP +"path" may not be an absolute path or use "." or ".." path components. These +restrictions are not enforced for [Local Manifests]. +.PP +If you want to place files into the root of the checkout (e.g. a README or +Makefile or another build script), use the [copyfile] or [linkfile] elements +instead. +.PP +Attribute `remote`: Name of a previously defined remote element. If not supplied +the remote given by the default element is used. +.PP +Attribute `revision`: Name of the Git branch the manifest wants to track for +this project. Names can be relative to refs/heads (e.g. just "main") or absolute +(e.g. "refs/heads/main"). Tags and/or explicit SHA\-1s should work in theory, but +have not been extensively tested. If not supplied the revision given by the +remote element is used if applicable, else the default element is used. +.PP +Attribute `dest\-branch`: Name of a Git branch (e.g. `main`). When using `repo +upload`, changes will be submitted for code review on this branch. If +unspecified both here and in the default element, `revision` is used instead. +.PP +Attribute `groups`: List of groups to which this project belongs, whitespace or +comma separated. All projects belong to the group "all", and each project +automatically belongs to a group of its name:`name` and path:`path`. E.g. for +``, that project definition is +implicitly in the following manifest groups: default, name:monkeys, and +path:barrel\-of. If you place a project in the group "notdefault", it will not be +automatically downloaded by repo. If the project has a parent element, the +`name` and `path` here are the prefixed ones. +.PP +Attribute `sync\-c`: Set to true to only sync the given Git branch (specified in +the `revision` attribute) rather than the whole ref space. +.PP +Attribute `sync\-s`: Set to true to also sync sub\-projects. +.PP +Attribute `upstream`: Name of the Git ref in which a sha1 can be found. Used +when syncing a revision locked manifest in \fB\-c\fR mode to avoid having to sync the +entire ref space. +.PP +Attribute `clone\-depth`: Set the depth to use when fetching this project. If +specified, this value will override any value given to repo init with the +\fB\-\-depth\fR option on the command line. +.PP +Attribute `force\-path`: Set to true to force this project to create the local +mirror repository according to its `path` attribute (if supplied) rather than +the `name` attribute. This attribute only applies to the local mirrors syncing, +it will be ignored when syncing the projects in a client working directory. +.PP +Element extend\-project +.PP +Modify the attributes of the named project. +.PP +This element is mostly useful in a local manifest file, to modify the attributes +of an existing project without completely replacing the existing project +definition. This makes the local manifest more robust against changes to the +original manifest. +.PP +Attribute `path`: If specified, limit the change to projects checked out at the +specified path, rather than all projects with the given name. +.PP +Attribute `groups`: List of additional groups to which this project belongs. +Same syntax as the corresponding element of `project`. +.PP +Attribute `revision`: If specified, overrides the revision of the original +project. Same syntax as the corresponding element of `project`. +.PP +Attribute `remote`: If specified, overrides the remote of the original project. +Same syntax as the corresponding element of `project`. +.PP +Element annotation +.PP +Zero or more annotation elements may be specified as children of a project +element. Each element describes a name\-value pair that will be exported into +each project's environment during a 'forall' command, prefixed with REPO__. In +addition, there is an optional attribute "keep" which accepts the case +insensitive values "true" (default) or "false". This attribute determines +whether or not the annotation will be kept when exported with the manifest +subcommand. +.PP +Element copyfile +.PP +Zero or more copyfile elements may be specified as children of a project +element. Each element describes a src\-dest pair of files; the "src" file will be +copied to the "dest" place during `repo sync` command. +.PP +"src" is project relative, "dest" is relative to the top of the tree. Copying +from paths outside of the project or to paths outside of the repo client is not +allowed. +.PP +"src" and "dest" must be files. Directories or symlinks are not allowed. +Intermediate paths must not be symlinks either. +.PP +Parent directories of "dest" will be automatically created if missing. +.PP +Element linkfile +.PP +It's just like copyfile and runs at the same time as copyfile but instead of +copying it creates a symlink. +.PP +The symlink is created at "dest" (relative to the top of the tree) and points to +the path specified by "src" which is a path in the project. +.PP +Parent directories of "dest" will be automatically created if missing. +.PP +The symlink target may be a file or directory, but it may not point outside of +the repo client. +.PP +Element remove\-project +.PP +Deletes the named project from the internal manifest table, possibly allowing a +subsequent project element in the same manifest file to replace the project with +a different source. +.PP +This element is mostly useful in a local manifest file, where the user can +remove a project, and possibly replace it with their own definition. +.PP +Attribute `optional`: Set to true to ignore remove\-project elements with no +matching `project` element. +.PP +Element repo\-hooks +.PP +NB: See the [practical documentation](./repo\-hooks.md) for using repo hooks. +.PP +Only one repo\-hooks element may be specified at a time. Attempting to redefine +it will fail to parse. +.PP +Attribute `in\-project`: The project where the hooks are defined. The value must +match the `name` attribute (**not** the `path` attribute) of a previously +defined `project` element. +.PP +Attribute `enabled\-list`: List of hooks to use, whitespace or comma separated. +.PP +Element superproject +.PP +*** *Note*: This is currently a WIP. *** +.PP +NB: See the [git superprojects documentation]( +https://en.wikibooks.org/wiki/Git/Submodules_and_Superprojects) for background +information. +.PP +This element is used to specify the URL of the superproject. It has "name" and +"remote" as atrributes. Only "name" is required while the others have reasonable +defaults. At most one superproject may be specified. Attempting to redefine it +will fail to parse. +.PP +Attribute `name`: A unique name for the superproject. This attribute has the +same meaning as project's name attribute. See the [element +project](#element\-project) for more information. +.PP +Attribute `remote`: Name of a previously defined remote element. If not supplied +the remote given by the default element is used. +.PP +Element contactinfo +.PP +*** *Note*: This is currently a WIP. *** +.PP +This element is used to let manifest authors self\-register contact info. It has +"bugurl" as a required atrribute. This element can be repeated, and any later +entries will clobber earlier ones. This would allow manifest authors who extend +manifests to specify their own contact info. +.PP +Attribute `bugurl`: The URL to file a bug against the manifest owner. +.PP +Element include +.PP +This element provides the capability of including another manifest file into the +originating manifest. Normal rules apply for the target manifest to include \- it +must be a usable manifest on its own. +.PP +Attribute `name`: the manifest to include, specified relative to the manifest +repository's root. +.PP +"name" may not be an absolute path or use "." or ".." path components. These +restrictions are not enforced for [Local Manifests]. +.PP +Attribute `groups`: List of additional groups to which all projects in the +included manifest belong. This appends and recurses, meaning all projects in +sub\-manifests carry all parent include groups. Same syntax as the corresponding +element of `project`. +.PP +Local Manifests +.PP +Additional remotes and projects may be added through local manifest files stored +in `$TOP_DIR/.repo/local_manifests/*.xml`. +.PP +For example: +.IP +\f(CW$ ls .repo/local_manifests\fR +.IP +local_manifest.xml +another_local_manifest.xml +.IP +\f(CW$ cat .repo/local_manifests/local_manifest.xml\fR +.IP + + +.IP + +.IP + +.IP + +.PP +Users may add projects to the local manifest(s) prior to a `repo sync` +invocation, instructing repo to automatically download and manage these extra +projects. +.PP +Manifest files stored in `$TOP_DIR/.repo/local_manifests/*.xml` will be loaded +in alphabetical order. +.PP +Projects from local manifest files are added into local:: group. +.PP +The legacy `$TOP_DIR/.repo/local_manifest.xml` path is no longer supported. +.SS [copyfile]: #Element\-copyfile [linkfile]: #Element\-linkfile [Local Manifests]: +.PP +#local\-manifests diff --git a/man/repo-overview.1 b/man/repo-overview.1 new file mode 100644 index 00000000..a12c7640 --- /dev/null +++ b/man/repo-overview.1 @@ -0,0 +1,39 @@ +.\" DO NOT MODIFY THIS FILE! It was generated by help2man. +.TH REPO "1" "July 2021" "repo overview" "Repo Manual" +.SH NAME +repo \- repo overview - manual page for repo overview +.SH SYNOPSIS +.B repo +\fI\,overview \/\fR[\fI\,--current-branch\/\fR] [\fI\,\/\fR...] +.SH DESCRIPTION +Summary +.PP +Display overview of unmerged project branches +.SH OPTIONS +.TP +\fB\-h\fR, \fB\-\-help\fR +show this help message and exit +.TP +\fB\-c\fR, \fB\-\-current\-branch\fR +consider only checked out branches +.TP +\fB\-\-no\-current\-branch\fR +consider all local branches +.SS Logging options: +.TP +\fB\-v\fR, \fB\-\-verbose\fR +show all output +.TP +\fB\-q\fR, \fB\-\-quiet\fR +only show errors +.PP +Run `repo help overview` to view the detailed manual. +.SH DETAILS +.PP +The 'repo overview' command is used to display an overview of the projects +branches, and list any local commits that have not yet been merged into the +project. +.PP +The \fB\-c\fR/\-\-current\-branch option can be used to restrict the output to only +branches currently checked out in each project. By default, all branches are +displayed. diff --git a/man/repo-prune.1 b/man/repo-prune.1 new file mode 100644 index 00000000..2479542c --- /dev/null +++ b/man/repo-prune.1 @@ -0,0 +1,27 @@ +.\" DO NOT MODIFY THIS FILE! It was generated by help2man. +.TH REPO "1" "July 2021" "repo prune" "Repo Manual" +.SH NAME +repo \- repo prune - manual page for repo prune +.SH SYNOPSIS +.B repo +\fI\,prune \/\fR[\fI\,\/\fR...] +.SH DESCRIPTION +Summary +.PP +Prune (delete) already merged topics +.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) +.SS Logging options: +.TP +\fB\-v\fR, \fB\-\-verbose\fR +show all output +.TP +\fB\-q\fR, \fB\-\-quiet\fR +only show errors +.PP +Run `repo help prune` to view the detailed manual. diff --git a/man/repo-rebase.1 b/man/repo-rebase.1 new file mode 100644 index 00000000..aa261036 --- /dev/null +++ b/man/repo-rebase.1 @@ -0,0 +1,55 @@ +.\" DO NOT MODIFY THIS FILE! It was generated by help2man. +.TH REPO "1" "July 2021" "repo rebase" "Repo Manual" +.SH NAME +repo \- repo rebase - manual page for repo rebase +.SH SYNOPSIS +.B repo +\fI\,rebase {\/\fR[\fI\,\/\fR...] \fI\,| -i \/\fR...\fI\,}\/\fR +.SH DESCRIPTION +Summary +.PP +Rebase local branches on upstream branch +.SH OPTIONS +.TP +\fB\-h\fR, \fB\-\-help\fR +show this help message and exit +.TP +\fB\-\-fail\-fast\fR +stop rebasing after first error is hit +.TP +\fB\-f\fR, \fB\-\-force\-rebase\fR +pass \fB\-\-force\-rebase\fR to git rebase +.TP +\fB\-\-no\-ff\fR +pass \fB\-\-no\-ff\fR to git rebase +.TP +\fB\-\-autosquash\fR +pass \fB\-\-autosquash\fR to git rebase +.TP +\fB\-\-whitespace\fR=\fI\,WS\/\fR +pass \fB\-\-whitespace\fR to git rebase +.TP +\fB\-\-auto\-stash\fR +stash local modifications before starting +.TP +\fB\-m\fR, \fB\-\-onto\-manifest\fR +rebase onto the manifest version instead of upstream +HEAD (this helps to make sure the local tree stays +consistent if you previously synced to a manifest) +.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\-i\fR, \fB\-\-interactive\fR +interactive rebase (single project only) +.PP +Run `repo help rebase` to view the detailed manual. +.SH DETAILS +.PP +\&'repo rebase' uses git rebase to move local changes in the current topic branch +to the HEAD of the upstream history, useful when you have made commits in a +topic branch but need to incorporate new upstream changes "underneath" them. diff --git a/man/repo-selfupdate.1 b/man/repo-selfupdate.1 new file mode 100644 index 00000000..70c855ab --- /dev/null +++ b/man/repo-selfupdate.1 @@ -0,0 +1,35 @@ +.\" DO NOT MODIFY THIS FILE! It was generated by help2man. +.TH REPO "1" "July 2021" "repo selfupdate" "Repo Manual" +.SH NAME +repo \- repo selfupdate - manual page for repo selfupdate +.SH SYNOPSIS +.B repo +\fI\,selfupdate\/\fR +.SH DESCRIPTION +Summary +.PP +Update repo to the latest version +.SH OPTIONS +.TP +\fB\-h\fR, \fB\-\-help\fR +show this help message and exit +.SS Logging options: +.TP +\fB\-v\fR, \fB\-\-verbose\fR +show all output +.TP +\fB\-q\fR, \fB\-\-quiet\fR +only show errors +.SS repo Version options: +.TP +\fB\-\-no\-repo\-verify\fR +do not verify repo source code +.PP +Run `repo help selfupdate` to view the detailed manual. +.SH DETAILS +.PP +The 'repo selfupdate' command upgrades repo to the latest version, if a newer +version is available. +.PP +Normally this is done automatically by 'repo sync' and does not need to be +performed by an end\-user. diff --git a/man/repo-smartsync.1 b/man/repo-smartsync.1 new file mode 100644 index 00000000..ad98b479 --- /dev/null +++ b/man/repo-smartsync.1 @@ -0,0 +1,117 @@ +.\" DO NOT MODIFY THIS FILE! It was generated by help2man. +.TH REPO "1" "July 2021" "repo smartsync" "Repo Manual" +.SH NAME +repo \- repo smartsync - manual page for repo smartsync +.SH SYNOPSIS +.B repo +\fI\,smartsync \/\fR[\fI\,\/\fR...] +.SH DESCRIPTION +Summary +.PP +Update working tree to the latest known good revision +.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: 1) +.TP +\fB\-\-jobs\-network\fR=\fI\,JOBS\/\fR +number of network jobs to run in parallel (defaults to +\fB\-\-jobs\fR) +.TP +\fB\-\-jobs\-checkout\fR=\fI\,JOBS\/\fR +number of local checkout jobs to run in parallel +(defaults to \fB\-\-jobs\fR) +.TP +\fB\-f\fR, \fB\-\-force\-broken\fR +obsolete option (to be deleted in the future) +.TP +\fB\-\-fail\-fast\fR +stop syncing after first error is hit +.TP +\fB\-\-force\-sync\fR +overwrite an existing git directory if it needs to +point to a different object directory. WARNING: this +may cause loss of data +.TP +\fB\-\-force\-remove\-dirty\fR +force remove projects with uncommitted modifications +if projects no longer exist in the manifest. WARNING: +this may cause loss of data +.TP +\fB\-l\fR, \fB\-\-local\-only\fR +only update working tree, don't fetch +.TP +\fB\-\-no\-manifest\-update\fR, \fB\-\-nmu\fR +use the existing manifest checkout as\-is. (do not +update to the latest revision) +.TP +\fB\-n\fR, \fB\-\-network\-only\fR +fetch only, don't update working tree +.TP +\fB\-d\fR, \fB\-\-detach\fR +detach projects back to manifest revision +.TP +\fB\-c\fR, \fB\-\-current\-branch\fR +fetch only current branch from server +.TP +\fB\-\-no\-current\-branch\fR +fetch all branches from server +.TP +\fB\-m\fR NAME.xml, \fB\-\-manifest\-name\fR=\fI\,NAME\/\fR.xml +temporary manifest to use for this sync +.TP +\fB\-\-clone\-bundle\fR +enable use of \fI\,/clone.bundle\/\fP on HTTP/HTTPS +.TP +\fB\-\-no\-clone\-bundle\fR +disable use of \fI\,/clone.bundle\/\fP on HTTP/HTTPS +.TP +\fB\-u\fR MANIFEST_SERVER_USERNAME, \fB\-\-manifest\-server\-username\fR=\fI\,MANIFEST_SERVER_USERNAME\/\fR +username to authenticate with the manifest server +.TP +\fB\-p\fR MANIFEST_SERVER_PASSWORD, \fB\-\-manifest\-server\-password\fR=\fI\,MANIFEST_SERVER_PASSWORD\/\fR +password to authenticate with the manifest server +.TP +\fB\-\-fetch\-submodules\fR +fetch submodules from server +.TP +\fB\-\-use\-superproject\fR +use the manifest superproject to sync projects +.TP +\fB\-\-no\-use\-superproject\fR +disable use of manifest superprojects +.TP +\fB\-\-tags\fR +fetch tags +.TP +\fB\-\-no\-tags\fR +don't fetch tags +.TP +\fB\-\-optimized\-fetch\fR +only fetch projects fixed to sha1 if revision does not +exist locally +.TP +\fB\-\-retry\-fetches\fR=\fI\,RETRY_FETCHES\/\fR +number of times to retry fetches on transient errors +.TP +\fB\-\-prune\fR +delete refs that no longer exist on the remote +.SS Logging options: +.TP +\fB\-v\fR, \fB\-\-verbose\fR +show all output +.TP +\fB\-q\fR, \fB\-\-quiet\fR +only show errors +.SS repo Version options: +.TP +\fB\-\-no\-repo\-verify\fR +do not verify repo source code +.PP +Run `repo help smartsync` to view the detailed manual. +.SH DETAILS +.PP +The 'repo smartsync' command is a shortcut for sync \fB\-s\fR. diff --git a/man/repo-stage.1 b/man/repo-stage.1 new file mode 100644 index 00000000..07e1cac6 --- /dev/null +++ b/man/repo-stage.1 @@ -0,0 +1,30 @@ +.\" DO NOT MODIFY THIS FILE! It was generated by help2man. +.TH REPO "1" "July 2021" "repo stage" "Repo Manual" +.SH NAME +repo \- repo stage - manual page for repo stage +.SH SYNOPSIS +.B repo +\fI\,stage -i \/\fR[\fI\,\/\fR...] +.SH DESCRIPTION +Summary +.PP +Stage file(s) for commit +.SH OPTIONS +.TP +\fB\-h\fR, \fB\-\-help\fR +show this help message and exit +.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\-i\fR, \fB\-\-interactive\fR +use interactive staging +.PP +Run `repo help stage` to view the detailed manual. +.SH DETAILS +.PP +The 'repo stage' command stages files to prepare the next commit. diff --git a/man/repo-start.1 b/man/repo-start.1 new file mode 100644 index 00000000..cda3739f --- /dev/null +++ b/man/repo-start.1 @@ -0,0 +1,40 @@ +.\" DO NOT MODIFY THIS FILE! It was generated by help2man. +.TH REPO "1" "July 2021" "repo start" "Repo Manual" +.SH NAME +repo \- repo start - manual page for repo start +.SH SYNOPSIS +.B repo +\fI\,start \/\fR[\fI\,--all | \/\fR...] +.SH DESCRIPTION +Summary +.PP +Start a new branch for development +.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\-\-all\fR +begin branch in all projects +.TP +\fB\-r\fR REVISION, \fB\-\-rev\fR=\fI\,REVISION\/\fR, \fB\-\-revision\fR=\fI\,REVISION\/\fR +point branch at this revision instead of upstream +.TP +\fB\-\-head\fR, \fB\-\-HEAD\fR +abbreviation for \fB\-\-rev\fR HEAD +.SS Logging options: +.TP +\fB\-v\fR, \fB\-\-verbose\fR +show all output +.TP +\fB\-q\fR, \fB\-\-quiet\fR +only show errors +.PP +Run `repo help start` to view the detailed manual. +.SH DETAILS +.PP +\&'repo start' begins a new branch of development, starting from the revision +specified in the manifest. diff --git a/man/repo-status.1 b/man/repo-status.1 new file mode 100644 index 00000000..6037ae1a --- /dev/null +++ b/man/repo-status.1 @@ -0,0 +1,97 @@ +.\" DO NOT MODIFY THIS FILE! It was generated by help2man. +.TH REPO "1" "July 2021" "repo status" "Repo Manual" +.SH NAME +repo \- repo status - manual page for repo status +.SH SYNOPSIS +.B repo +\fI\,status \/\fR[\fI\,\/\fR...] +.SH DESCRIPTION +Summary +.PP +Show the working tree status +.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\-o\fR, \fB\-\-orphans\fR +include objects in working directory outside of repo +projects +.SS Logging options: +.TP +\fB\-v\fR, \fB\-\-verbose\fR +show all output +.TP +\fB\-q\fR, \fB\-\-quiet\fR +only show errors +.PP +Run `repo help status` to view the detailed manual. +.SH DETAILS +.PP +\&'repo status' compares the working tree to the staging area (aka index), and the +most recent commit on this branch (HEAD), in each project specified. A summary +is displayed, one line per file where there is a difference between these three +states. +.PP +The \fB\-j\fR/\-\-jobs option can be used to run multiple status queries in parallel. +.PP +The \fB\-o\fR/\-\-orphans option can be used to show objects that are in the working +directory, but not associated with a repo project. This includes unmanaged +top\-level files and directories, but also includes deeper items. For example, if +dir/subdir/proj1 and dir/subdir/proj2 are repo projects, dir/subdir/proj3 will +be shown if it is not known to repo. +.PP +Status Display +.PP +The status display is organized into three columns of information, for example +if the file 'subcmds/status.py' is modified in the project 'repo' on branch +\&'devwork': +.TP +project repo/ +branch devwork +.TP +\fB\-m\fR +subcmds/status.py +.PP +The first column explains how the staging area (index) differs from the last +commit (HEAD). Its values are always displayed in upper case and have the +following meanings: +.TP +\-: +no difference +.TP +A: +added (not in HEAD, in index ) +.TP +M: +modified ( in HEAD, in index, different content ) +.TP +D: +deleted ( in HEAD, not in index ) +.TP +R: +renamed (not in HEAD, in index, path changed ) +.TP +C: +copied (not in HEAD, in index, copied from another) +.TP +T: +mode changed ( in HEAD, in index, same content ) +.TP +U: +unmerged; conflict resolution required +.PP +The second column explains how the working directory differs from the index. Its +values are always displayed in lower case and have the following meanings: +.TP +\-: +new / unknown (not in index, in work tree ) +.TP +m: +modified ( in index, in work tree, modified ) +.TP +d: +deleted ( in index, not in work tree ) diff --git a/man/repo-sync.1 b/man/repo-sync.1 new file mode 100644 index 00000000..70f7c207 --- /dev/null +++ b/man/repo-sync.1 @@ -0,0 +1,208 @@ +.\" DO NOT MODIFY THIS FILE! It was generated by help2man. +.TH REPO "1" "July 2021" "repo sync" "Repo Manual" +.SH NAME +repo \- repo sync - manual page for repo sync +.SH SYNOPSIS +.B repo +\fI\,sync \/\fR[\fI\,\/\fR...] +.SH DESCRIPTION +Summary +.PP +Update working tree to the latest revision +.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: 1) +.TP +\fB\-\-jobs\-network\fR=\fI\,JOBS\/\fR +number of network jobs to run in parallel (defaults to +\fB\-\-jobs\fR) +.TP +\fB\-\-jobs\-checkout\fR=\fI\,JOBS\/\fR +number of local checkout jobs to run in parallel +(defaults to \fB\-\-jobs\fR) +.TP +\fB\-f\fR, \fB\-\-force\-broken\fR +obsolete option (to be deleted in the future) +.TP +\fB\-\-fail\-fast\fR +stop syncing after first error is hit +.TP +\fB\-\-force\-sync\fR +overwrite an existing git directory if it needs to +point to a different object directory. WARNING: this +may cause loss of data +.TP +\fB\-\-force\-remove\-dirty\fR +force remove projects with uncommitted modifications +if projects no longer exist in the manifest. WARNING: +this may cause loss of data +.TP +\fB\-l\fR, \fB\-\-local\-only\fR +only update working tree, don't fetch +.TP +\fB\-\-no\-manifest\-update\fR, \fB\-\-nmu\fR +use the existing manifest checkout as\-is. (do not +update to the latest revision) +.TP +\fB\-n\fR, \fB\-\-network\-only\fR +fetch only, don't update working tree +.TP +\fB\-d\fR, \fB\-\-detach\fR +detach projects back to manifest revision +.TP +\fB\-c\fR, \fB\-\-current\-branch\fR +fetch only current branch from server +.TP +\fB\-\-no\-current\-branch\fR +fetch all branches from server +.TP +\fB\-m\fR NAME.xml, \fB\-\-manifest\-name\fR=\fI\,NAME\/\fR.xml +temporary manifest to use for this sync +.TP +\fB\-\-clone\-bundle\fR +enable use of \fI\,/clone.bundle\/\fP on HTTP/HTTPS +.TP +\fB\-\-no\-clone\-bundle\fR +disable use of \fI\,/clone.bundle\/\fP on HTTP/HTTPS +.TP +\fB\-u\fR MANIFEST_SERVER_USERNAME, \fB\-\-manifest\-server\-username\fR=\fI\,MANIFEST_SERVER_USERNAME\/\fR +username to authenticate with the manifest server +.TP +\fB\-p\fR MANIFEST_SERVER_PASSWORD, \fB\-\-manifest\-server\-password\fR=\fI\,MANIFEST_SERVER_PASSWORD\/\fR +password to authenticate with the manifest server +.TP +\fB\-\-fetch\-submodules\fR +fetch submodules from server +.TP +\fB\-\-use\-superproject\fR +use the manifest superproject to sync projects +.TP +\fB\-\-no\-use\-superproject\fR +disable use of manifest superprojects +.TP +\fB\-\-tags\fR +fetch tags +.TP +\fB\-\-no\-tags\fR +don't fetch tags +.TP +\fB\-\-optimized\-fetch\fR +only fetch projects fixed to sha1 if revision does not +exist locally +.TP +\fB\-\-retry\-fetches\fR=\fI\,RETRY_FETCHES\/\fR +number of times to retry fetches on transient errors +.TP +\fB\-\-prune\fR +delete refs that no longer exist on the remote +.TP +\fB\-s\fR, \fB\-\-smart\-sync\fR +smart sync using manifest from the latest known good +build +.TP +\fB\-t\fR SMART_TAG, \fB\-\-smart\-tag\fR=\fI\,SMART_TAG\/\fR +smart sync using manifest from a known tag +.SS Logging options: +.TP +\fB\-v\fR, \fB\-\-verbose\fR +show all output +.TP +\fB\-q\fR, \fB\-\-quiet\fR +only show errors +.SS repo Version options: +.TP +\fB\-\-no\-repo\-verify\fR +do not verify repo source code +.PP +Run `repo help sync` to view the detailed manual. +.SH DETAILS +.PP +The 'repo sync' command synchronizes local project directories with the remote +repositories specified in the manifest. If a local project does not yet exist, +it will clone a new local directory from the remote repository and set up +tracking branches as specified in the manifest. If the local project already +exists, 'repo sync' will update the remote branches and rebase any new local +changes on top of the new remote changes. +.PP +\&'repo sync' will synchronize all projects listed at the command line. Projects +can be specified either by name, or by a relative or absolute path to the +project's local directory. If no projects are specified, 'repo sync' will +synchronize all projects listed in the manifest. +.PP +The \fB\-d\fR/\-\-detach option can be used to switch specified projects back to the +manifest revision. This option is especially helpful if the project is currently +on a topic branch, but the manifest revision is temporarily needed. +.PP +The \fB\-s\fR/\-\-smart\-sync option can be used to sync to a known good build as +specified by the manifest\-server element in the current manifest. The +\fB\-t\fR/\-\-smart\-tag option is similar and allows you to specify a custom tag/label. +.PP +The \fB\-u\fR/\-\-manifest\-server\-username and \fB\-p\fR/\-\-manifest\-server\-password options can +be used to specify a username and password to authenticate with the manifest +server when using the \fB\-s\fR or \fB\-t\fR option. +.PP +If \fB\-u\fR and \fB\-p\fR are not specified when using the \fB\-s\fR or \fB\-t\fR option, 'repo sync' will +attempt to read authentication credentials for the manifest server from the +user's .netrc file. +.PP +\&'repo sync' will not use authentication credentials from \fB\-u\fR/\-p or .netrc if the +manifest server specified in the manifest file already includes credentials. +.PP +By default, all projects will be synced. The \fB\-\-fail\-fast\fR option can be used to +halt syncing as soon as possible when the first project fails to sync. +.PP +The \fB\-\-force\-sync\fR option can be used to overwrite existing git directories if +they have previously been linked to a different object directory. WARNING: This +may cause data to be lost since refs may be removed when overwriting. +.PP +The \fB\-\-force\-remove\-dirty\fR option can be used to remove previously used projects +with uncommitted changes. WARNING: This may cause data to be lost since +uncommitted changes may be removed with projects that no longer exist in the +manifest. +.PP +The \fB\-\-no\-clone\-bundle\fR option disables any attempt to use \fI\,$URL/clone.bundle\/\fP to +bootstrap a new Git repository from a resumeable bundle file on a content +delivery network. This may be necessary if there are problems with the local +Python HTTP client or proxy configuration, but the Git binary works. +.PP +The \fB\-\-fetch\-submodules\fR option enables fetching Git submodules of a project from +server. +.PP +The \fB\-c\fR/\-\-current\-branch option can be used to only fetch objects that are on the +branch specified by a project's revision. +.PP +The \fB\-\-optimized\-fetch\fR option can be used to only fetch projects that are fixed +to a sha1 revision if the sha1 revision does not already exist locally. +.PP +The \fB\-\-prune\fR option can be used to remove any refs that no longer exist on the +remote. +.PP +SSH Connections +.PP +If at least one project remote URL uses an SSH connection (ssh://, git+ssh://, +or user@host:path syntax) repo will automatically enable the SSH ControlMaster +option when connecting to that host. This feature permits other projects in the +same 'repo sync' session to reuse the same SSH tunnel, saving connection setup +overheads. +.PP +To disable this behavior on UNIX platforms, set the GIT_SSH environment variable +to 'ssh'. For example: +.IP +export GIT_SSH=ssh +repo sync +.PP +Compatibility +.PP +This feature is automatically disabled on Windows, due to the lack of UNIX +domain socket support. +.PP +This feature is not compatible with url.insteadof rewrites in the user's +~/.gitconfig. 'repo sync' is currently not able to perform the rewrite early +enough to establish the ControlMaster tunnel. +.PP +If the remote SSH daemon is Gerrit Code Review, version 2.0.10 or later is +required to fix a server side protocol bug. diff --git a/man/repo-upload.1 b/man/repo-upload.1 new file mode 100644 index 00000000..6deed047 --- /dev/null +++ b/man/repo-upload.1 @@ -0,0 +1,174 @@ +.\" DO NOT MODIFY THIS FILE! It was generated by help2man. +.TH REPO "1" "July 2021" "repo upload" "Repo Manual" +.SH NAME +repo \- repo upload - manual page for repo upload +.SH SYNOPSIS +.B repo +\fI\,upload \/\fR[\fI\,--re --cc\/\fR] [\fI\,\/\fR]... +.SH DESCRIPTION +Summary +.PP +Upload changes for code review +.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\-t\fR +send local branch name to Gerrit Code Review +.TP +\fB\-\-hashtag\fR=\fI\,HASHTAGS\/\fR, \fB\-\-ht\fR=\fI\,HASHTAGS\/\fR +add hashtags (comma delimited) to the review +.TP +\fB\-\-hashtag\-branch\fR, \fB\-\-htb\fR +add local branch name as a hashtag +.TP +\fB\-l\fR LABELS, \fB\-\-label\fR=\fI\,LABELS\/\fR +add a label when uploading +.TP +\fB\-\-re\fR=\fI\,REVIEWERS\/\fR, \fB\-\-reviewers\fR=\fI\,REVIEWERS\/\fR +request reviews from these people +.TP +\fB\-\-cc\fR=\fI\,CC\/\fR +also send email to these email addresses +.TP +\fB\-\-br\fR=\fI\,BRANCH\/\fR, \fB\-\-branch\fR=\fI\,BRANCH\/\fR +(local) branch to upload +.TP +\fB\-c\fR, \fB\-\-current\-branch\fR +upload current git branch +.TP +\fB\-\-no\-current\-branch\fR +upload all git branches +.TP +\fB\-\-ne\fR, \fB\-\-no\-emails\fR +do not send e\-mails on upload +.TP +\fB\-p\fR, \fB\-\-private\fR +upload as a private change (deprecated; use \fB\-\-wip\fR) +.TP +\fB\-w\fR, \fB\-\-wip\fR +upload as a work\-in\-progress change +.TP +\fB\-o\fR PUSH_OPTIONS, \fB\-\-push\-option\fR=\fI\,PUSH_OPTIONS\/\fR +additional push options to transmit +.TP +\fB\-D\fR BRANCH, \fB\-\-destination\fR=\fI\,BRANCH\/\fR, \fB\-\-dest\fR=\fI\,BRANCH\/\fR +submit for review on this target branch +.TP +\fB\-n\fR, \fB\-\-dry\-run\fR +do everything except actually upload the CL +.TP +\fB\-y\fR, \fB\-\-yes\fR +answer yes to all safe prompts +.TP +\fB\-\-no\-cert\-checks\fR +disable verifying ssl certs (unsafe) +.SS Logging options: +.TP +\fB\-v\fR, \fB\-\-verbose\fR +show all output +.TP +\fB\-q\fR, \fB\-\-quiet\fR +only show errors +.SS pre\-upload hooks: +.TP +\fB\-\-no\-verify\fR +Do not run the pre\-upload hook. +.TP +\fB\-\-verify\fR +Run the pre\-upload hook without prompting. +.TP +\fB\-\-ignore\-hooks\fR +Do not abort if pre\-upload hooks fail. +.PP +Run `repo help upload` to view the detailed manual. +.SH DETAILS +.PP +The 'repo upload' command is used to send changes to the Gerrit Code Review +system. It searches for topic branches in local projects that have not yet been +published for review. If multiple topic branches are found, 'repo upload' opens +an editor to allow the user to select which branches to upload. +.PP +\&'repo upload' searches for uploadable changes in all projects listed at the +command line. Projects can be specified either by name, or by a relative or +absolute path to the project's local directory. If no projects are specified, +\&'repo upload' will search for uploadable changes in all projects listed in the +manifest. +.PP +If the \fB\-\-reviewers\fR or \fB\-\-cc\fR options are passed, those emails are added to the +respective list of users, and emails are sent to any new users. Users passed as +\fB\-\-reviewers\fR must already be registered with the code review system, or the +upload will fail. +.PP +Configuration +.PP +review.URL.autoupload: +.PP +To disable the "Upload ... (y/N)?" prompt, you can set a per\-project or global +Git configuration option. If review.URL.autoupload is set to "true" then repo +will assume you always answer "y" at the prompt, and will not prompt you +further. If it is set to "false" then repo will assume you always answer "n", +and will abort. +.PP +review.URL.autoreviewer: +.PP +To automatically append a user or mailing list to reviews, you can set a +per\-project or global Git option to do so. +.PP +review.URL.autocopy: +.PP +To automatically copy a user or mailing list to all uploaded reviews, you can +set a per\-project or global Git option to do so. Specifically, +review.URL.autocopy can be set to a comma separated list of reviewers who you +always want copied on all uploads with a non\-empty \fB\-\-re\fR argument. +.PP +review.URL.username: +.PP +Override the username used to connect to Gerrit Code Review. By default the +local part of the email address is used. +.PP +The URL must match the review URL listed in the manifest XML file, or in the +\&.git/config within the project. For example: +.IP +[remote "origin"] +.IP +url = git://git.example.com/project.git +review = http://review.example.com/ +.IP +[review "http://review.example.com/"] +.IP +autoupload = true +autocopy = johndoe@company.com,my\-team\-alias@company.com +.PP +review.URL.uploadtopic: +.PP +To add a topic branch whenever uploading a commit, you can set a per\-project or +global Git option to do so. If review.URL.uploadtopic is set to "true" then repo +will assume you always want the equivalent of the \fB\-t\fR option to the repo command. +If unset or set to "false" then repo will make use of only the command line +option. +.PP +review.URL.uploadhashtags: +.PP +To add hashtags whenever uploading a commit, you can set a per\-project or global +Git option to do so. The value of review.URL.uploadhashtags will be used as +comma delimited hashtags like the \fB\-\-hashtag\fR option. +.PP +review.URL.uploadlabels: +.PP +To add labels whenever uploading a commit, you can set a per\-project or global +Git option to do so. The value of review.URL.uploadlabels will be used as comma +delimited labels like the \fB\-\-label\fR option. +.PP +review.URL.uploadnotify: +.PP +Control e\-mail notifications when uploading. +https://gerrit\-review.googlesource.com/Documentation/user\-upload.html#notify +.PP +References +.PP +Gerrit Code Review: https://www.gerritcodereview.com/ diff --git a/man/repo-version.1 b/man/repo-version.1 new file mode 100644 index 00000000..cc703f61 --- /dev/null +++ b/man/repo-version.1 @@ -0,0 +1,24 @@ +.\" DO NOT MODIFY THIS FILE! It was generated by help2man. +.TH REPO "1" "July 2021" "repo version" "Repo Manual" +.SH NAME +repo \- repo version - manual page for repo version +.SH SYNOPSIS +.B repo +\fI\,version\/\fR +.SH DESCRIPTION +Summary +.PP +Display the version of repo +.SH OPTIONS +.TP +\fB\-h\fR, \fB\-\-help\fR +show this help message and exit +.SS Logging options: +.TP +\fB\-v\fR, \fB\-\-verbose\fR +show all output +.TP +\fB\-q\fR, \fB\-\-quiet\fR +only show errors +.PP +Run `repo help version` to view the detailed manual. diff --git a/man/repo.1 b/man/repo.1 new file mode 100644 index 00000000..0bc3acdb --- /dev/null +++ b/man/repo.1 @@ -0,0 +1,93 @@ +.\" DO NOT MODIFY THIS FILE! It was generated by help2man. +.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: +.TP +abandon +Permanently abandon a development branch +.TP +branch +View current topic branches +.TP +branches +View current topic branches +.TP +checkout +Checkout a branch for development +.TP +cherry\-pick +Cherry\-pick a change. +.TP +diff +Show changes between commit and working tree +.TP +diffmanifests +Manifest diff utility +.TP +download +Download and checkout a change +.TP +forall +Run a shell command in each project +.TP +gitc\-delete +Delete a GITC Client. +.TP +gitc\-init +Initialize a GITC Client. +.TP +grep +Print lines matching a pattern +.TP +help +Display detailed help on a command +.TP +info +Get info on the manifest branch, current branch or unmerged branches +.TP +init +Initialize a repo client checkout in the current directory +.TP +list +List projects and their associated directories +.TP +manifest +Manifest inspection utility +.TP +overview +Display overview of unmerged project branches +.TP +prune +Prune (delete) already merged topics +.TP +rebase +Rebase local branches on upstream branch +.TP +selfupdate +Update repo to the latest version +.TP +smartsync +Update working tree to the latest known good revision +.TP +stage +Stage file(s) for commit +.TP +start +Start a new branch for development +.TP +status +Show the working tree status +.TP +sync +Update working tree to the latest revision +.TP +upload +Upload changes for code review +.TP +version +Display the version of repo +.PP +See 'repo help ' for more information on a specific command. diff --git a/release/update-manpages b/release/update-manpages new file mode 100755 index 00000000..3aeee206 --- /dev/null +++ b/release/update-manpages @@ -0,0 +1,85 @@ +#!/usr/bin/env python3 +# Copyright (C) 2021 The Android Open Source Project +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +"""Helper tool for generating manual page for all repo commands. + +This is intended to be run before every official Repo release. +""" + +from pathlib import Path +from functools import partial +import argparse +import multiprocessing +import os +import re +import shutil +import subprocess +import sys +import tempfile + +TOPDIR = Path(__file__).resolve().parent.parent +MANDIR = TOPDIR.joinpath('man') + +# Load repo local modules. +sys.path.insert(0, str(TOPDIR)) +from git_command import RepoSourceVersion +import subcmds + +def worker(cmd, **kwargs): + subprocess.run(cmd, **kwargs) + +def main(argv): + parser = argparse.ArgumentParser(description=__doc__) + opts = parser.parse_args(argv) + + if not shutil.which('help2man'): + sys.exit('Please install help2man to continue.') + + # "repo branch" is an alias for "repo branches". + del subcmds.all_commands['branch'] + (MANDIR / 'repo-branch.1').write_text('.so man1/repo-branches.1') + + version = RepoSourceVersion() + cmdlist = [['help2man', '-N', '-n', f'repo {cmd} - manual page for repo {cmd}', + '-S', f'repo {cmd}', '-m', 'Repo Manual', f'--version-string={version}', + '-o', MANDIR.joinpath(f'repo-{cmd}.1'), TOPDIR.joinpath('repo'), + '-h', f'help {cmd}'] for cmd in subcmds.all_commands] + cmdlist.append(['help2man', '-N', '-n', 'repository management tool built on top of git', + '-S', 'repo', '-m', 'Repo Manual', f'--version-string={version}', + '-o', MANDIR.joinpath('repo.1'), TOPDIR.joinpath('repo'), + '-h', 'help --all']) + + with tempfile.TemporaryDirectory() as tempdir: + repo_dir = Path(tempdir) / '.repo' + repo_dir.mkdir() + (repo_dir / 'repo').symlink_to(TOPDIR) + + # Run all cmd in parallel, and wait for them to finish. + with multiprocessing.Pool() as pool: + pool.map(partial(worker, cwd=tempdir, check=True), cmdlist) + + regex = ( + (r'(It was generated by help2man) [0-9.]+', '\g<1>.'), + (r'^\.IP\n(.*:)\n', '.SS \g<1>\n'), + (r'^\.PP\nDescription', '.SH DETAILS'), + ) + for path in MANDIR.glob('*.1'): + data = path.read_text() + for pattern, replacement in regex: + data = re.sub(pattern, replacement, data, flags=re.M) + path.write_text(data) + +if __name__ == '__main__': + sys.exit(main(sys.argv[1:]))