eac_tools 0.2.1 → 0.4.0

data/sub/avm-tools/sub/eac_git/vendor/git-subrepo/man/man1/git-subrepo.1

@@ -0,0 +1,743 @@
+.\" Automatically generated by Pod::Man 4.10 (Pod::Simple 3.35)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" Set up some character translations and predefined strings.  \*(-- will
+.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
+.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
+.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
+.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
+.\" nothing in troff, for use with C<>.
+.tr \(*W-
+.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
+.ie n \{\
+.    ds -- \(*W-
+.    ds PI pi
+.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
+.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
+.    ds L" ""
+.    ds R" ""
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds -- \|\(em\|
+.    ds PI \(*p
+.    ds L" ``
+.    ds R" ''
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "STDIN 1"
+.TH STDIN 1 "January 2020" "Generated by Swim v0.1.48" "Git Submodule Alternative"
+.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
+.\" way too many mistakes in technical documents.
+.if n .ad l
+.nh
+.SH "Name"
+.IX Header "Name"
+git-subrepo \- Git Submodule Alternative
+.SH "Synopsis"
+.IX Header "Synopsis"
+.Vb 1
+\&    git subrepo \-h    # Help Overview
+\&
+\&    git subrepo clone <remote\-url> [<subdir>]
+\&    git subrepo init <subdir>
+\&    git subrepo pull <subdir>
+\&    git subrepo push <subdir>
+\&
+\&    git subrepo fetch <subdir>
+\&    git subrepo branch <subdir>
+\&    git subrepo commit <subdir>
+\&    git subrepo config <subdir>
+\&
+\&    git subrepo status [<subdir>]
+\&    git subrepo clean <subdir>
+\&
+\&    git subrepo help [<command> | \-\-all]
+\&    git subrepo version
+\&    git subrepo upgrade
+.Ve
+.SH "Description"
+.IX Header "Description"
+This git command \*(L"clones\*(R" an external git repo into a subdirectory of your
+repo. Later on, upstream changes can be pulled in, and local changes can be
+pushed back. Simple.
+.SH "Benefits"
+.IX Header "Benefits"
+This command is an improvement from \f(CW\*(C`git\-submodule\*(C'\fR and \f(CW\*(C`git\-subtree\*(C'\fR; two
+other git commands with similar goals, but various problems.
+.PP
+It assumes there are 3 main roles of people interacting with a repo, and
+attempts to serve them all well:
+.IP "\(bu" 4
+\&\fBowner\fR \- The person who authors/owns/maintains a repo.
+.IP "\(bu" 4
+\&\fBusers\fR \- People who are just using/installing the repo.
+.IP "\(bu" 4
+\&\fBcollaborators\fR \- People who commit code to the repo and subrepos.
+.PP
+The \f(CW\*(C`git\-subrepo\*(C'\fR command benefits these roles in the following ways:
+.IP "\(bu" 4
+Simple and intuitive commandline usage (with tab completion).
+.IP "\(bu" 4
+Users get your repo and all your subrepos just by cloning your repo.
+.IP "\(bu" 4
+Users do not need to install \f(CW\*(C`git\-subrepo\*(C'\fR, ever.
+.IP "\(bu" 4
+Collaborators do not need to install unless they want to push/pull.
+.IP "\(bu" 4
+Collaborators know when a subdir is a subrepo (it has a \f(CW\*(C`.gitrepo\*(C'\fR file).
+.IP "\(bu" 4
+The \f(CW\*(C`.gitrepo\*(C'\fR file never gets pushed back to the subrepo upstream.
+.IP "\(bu" 4
+Well named branches and remotes are generated for manual operations.
+.IP "\(bu" 4
+Owners do not deal with the complications of keeping submodules in sync.
+.IP "\(bu" 4
+Subrepo repositories can contain subrepos themselves.
+.IP "\(bu" 4
+Branching with subrepos JustWorks™.
+.IP "\(bu" 4
+Different branches can have different subrepos in different states, etc.
+.IP "\(bu" 4
+Moving/renaming/deleting a subrepo subdir JustWorks™.
+.IP "\(bu" 4
+You can \f(CW\*(C`init\*(C'\fR an existing subdirectory into a subrepo.
+.IP "\(bu" 4
+Your git history is kept squeaky clean.
+.IP "\(bu" 4
+Upstream history (clone/pull) is condensed into a single commit.
+.IP "\(bu" 4
+Pulls can use a \f(CW\*(C`merge\*(C'\fR, \f(CW\*(C`rebase\*(C'\fR or \f(CW\*(C`force\*(C'\fR strategies.
+.IP "\(bu" 4
+You can see the subrepo history with \f(CW\*(C`git log subrepo/<subdir>/fetch\*(C'\fR.
+.IP "\(bu" 4
+Commits pushed back upstream are \fBnot\fR condensed (by default).
+.IP "\(bu" 4
+Trivial to try any subrepo operations and then reset back.
+.IP "\(bu" 4
+No configuration required.
+.IP "\(bu" 4
+Does not introduce history that messes up other git commands.
+.IP "\(bu" 4
+Fixes known rebase failures with \f(CW\*(C`git\-subtree\*(C'\fR.
+.SH "Installation"
+.IX Header "Installation"
+The best short answer is:
+.PP
+.Vb 2
+\&    git clone https://github.com/ingydotnet/git\-subrepo /path/to/git\-subrepo
+\&    echo \*(Aqsource /path/to/git\-subrepo/.rc\*(Aq >> ~/.bashrc
+.Ve
+.PP
+The complete \*(L"Installation Instructions\*(R" can be found below.
+.PP
+Note: git-subrepo needs a git version (> 2.7) that supports worktree:s.
+.SH "Commands"
+.IX Header "Commands"
+All the \fBsubrepo\fR commands use names of actual Git commands and try to do
+operations that are similar to their Git counterparts. They also attempt to
+give similar output in an attempt to make the subrepo usage intuitive to
+experienced Git users.
+.PP
+Please note that the commands are \fInot\fR exact equivalents, and do not take
+all the same arguments. Keep reading…
+.ie n .IP """git subrepo clone <repository> [<subdir>] [\-b <branch>] [\-f] [\-m <msg>] [\-e] [\-\-method <merge|rebase>]""" 4
+.el .IP "\f(CWgit subrepo clone <repository> [<subdir>] [\-b <branch>] [\-f] [\-m <msg>] [\-e] [\-\-method <merge|rebase>]\fR" 4
+.IX Item "git subrepo clone <repository> [<subdir>] [-b <branch>] [-f] [-m <msg>] [-e] [--method <merge|rebase>]"
+Add a repository as a subrepo in a subdir of your repository.
+.Sp
+This is similar in feel to \f(CW\*(C`git clone\*(C'\fR. You just specify the remote repo url,
+and optionally a sub-directory and/or branch name. The repo will be fetched
+and merged into the subdir.
+.Sp
+The subrepo history is \fIsquashed\fR into a single commit that contains the
+reference information. This information is also stored in a special file
+called \f(CW\*(C`<subdir>/.gitrepo\*(C'\fR. The presence of this file indicates that the
+directory is a subrepo.
+.Sp
+All subsequent commands refer to the subrepo by the name of the
+\&\fIsubdir\fR. From the subdir, all the current information about the subrepo
+can be obtained.
+.Sp
+The \f(CW\*(C`\-\-force\*(C'\fR option will \*(L"reclone\*(R" (completely replace) an existing subdir.
+.Sp
+The \f(CW\*(C`\-\-method\*(C'\fR option will decide how the join process between branches are
+performed. The default option is merge.
+.Sp
+The \f(CW\*(C`clone\*(C'\fR command accepts the \f(CW\*(C`\-\-branch=\*(C'\fR \f(CW\*(C`\-\-edit\*(C'\fR, \f(CW\*(C`\-\-force\*(C'\fR and \f(CW\*(C`\-\-
+message=\*(C'\fR options.
+.ie n .IP """git subrepo init <subdir> [\-r <remote>] [\-b <branch>] [\-\-method <merge|rebase>]""" 4
+.el .IP "\f(CWgit subrepo init <subdir> [\-r <remote>] [\-b <branch>] [\-\-method <merge|rebase>]\fR" 4
+.IX Item "git subrepo init <subdir> [-r <remote>] [-b <branch>] [--method <merge|rebase>]"
+Turn an existing subdirectory into a subrepo.
+.Sp
+If you want to expose a subdirectory of your project as a published subrepo,
+this command will do that. It will split out the content of a normal
+subdirectory into a branch and start tracking it as a subrepo. Afterwards your
+original repo will look exactly the same except that there will be a \f(CW\*(C`<subdir>/.gitrepo\*(C'\fR file.
+.Sp
+If you specify the \f(CW\*(C`\-\-remote\*(C'\fR (and optionally the \f(CW\*(C`\-\-branch\*(C'\fR) option, the
+values will be added to the \f(CW\*(C`<subdir>/.gitrepo\*(C'\fR file. The \f(CW\*(C`\-\-remote\*(C'\fR
+option is the upstream \s-1URL,\s0 and the \f(CW\*(C`\-\-branch\*(C'\fR option is the upstream branch
+to push to. These values will be needed to do a \f(CW\*(C`git subrepo push\*(C'\fR command,
+but they can be provided later on the \f(CW\*(C`push\*(C'\fR command (and saved to \f(CW\*(C`<subdir>/.gitrepo\*(C'\fR if you also specify the \f(CW\*(C`\-\-update\*(C'\fR option).
+.Sp
+Note: You will need to create the empty upstream repo and push to it on your
+      own, using \f(CW\*(C`git subrepo push <subdir>\*(C'\fR.
+.Sp
+The \f(CW\*(C`\-\-method\*(C'\fR option will decide how the join process between branches are
+performed. The default option is merge.
+.Sp
+The \f(CW\*(C`init\*(C'\fR command accepts the \f(CW\*(C`\-\-branch=\*(C'\fR and \f(CW\*(C`\-\-remote=\*(C'\fR options.
+.ie n .IP """git subrepo pull <subdir>|\-\-all [\-M|\-R|\-f] [\-m <msg>] [\-e] [\-b <branch>] [\-r <remote>] [\-u]""" 4
+.el .IP "\f(CWgit subrepo pull <subdir>|\-\-all [\-M|\-R|\-f] [\-m <msg>] [\-e] [\-b <branch>] [\-r <remote>] [\-u]\fR" 4
+.IX Item "git subrepo pull <subdir>|--all [-M|-R|-f] [-m <msg>] [-e] [-b <branch>] [-r <remote>] [-u]"
+Update the subrepo subdir with the latest upstream changes.
+.Sp
+The \f(CW\*(C`pull\*(C'\fR command fetches the latest content from the remote branch pointed
+to by the subrepo's \f(CW\*(C`.gitrepo\*(C'\fR file, and then tries to merge the changes into
+the corresponding subdir. It does this by making a branch of the local commits
+to the subdir and then merging or rebasing (see below) it with the fetched
+upstream content. After the merge, the content of the new branch replaces your
+subdir, the \f(CW\*(C`.gitrepo\*(C'\fR file is updated and a single 'pull' commit is added to
+your mainline history.
+.Sp
+The \f(CW\*(C`pull\*(C'\fR command will attempt to do the following commands in one go:
+.Sp
+.Vb 6
+\&    git subrepo fetch <subdir>
+\&    git subrepo branch <subdir>
+\&    git merge/rebase subrepo/<subdir>/fetch subrepo/<subdir>
+\&    git subrepo commit <subdir>
+\&    # Only needed for a consequential push:
+\&    git update\-ref refs/subrepo/<subdir>/pull subrepo/<subdir>
+.Ve
+.Sp
+In other words, you could do all the above commands yourself, for the same
+effect. If any of the commands fail, subrepo will stop and tell you to finish
+this by hand. Generally a failure would be in the merge or rebase part, where
+conflicts can happen. Since Git has lots of ways to resolve conflicts to your
+personal tastes, the subrepo command defers to letting you do this by hand.
+.Sp
+When pulling new data, the method selected in clone/init is used. This has no
+effect on the final result of the pull, since it becomes a single commit. But
+it does affect the resulting \f(CW\*(C`subrepo/<subdir>\*(C'\fR branch, which is often
+used for a subrepo \f(CW\*(C`push\*(C'\fR command. See 'push' below for more information. If
+you want to change the method you can use the \f(CW\*(C`config\*(C'\fR command for this.
+.Sp
+When you pull you can assume a fast-forward strategy (default) or you can
+specify a \f(CW\*(C`\-\-rebase\*(C'\fR, \f(CW\*(C`\-\-merge\*(C'\fR or \f(CW\*(C`\-\-force\*(C'\fR strategy. The latter is the
+same as a \f(CW\*(C`clone \-\-force\*(C'\fR operation, using the current remote and branch.
+.Sp
+Like the \f(CW\*(C`clone\*(C'\fR command, \f(CW\*(C`pull\*(C'\fR will squash all the changes (since the last
+pull or clone) into one commit. This keeps your mainline history nice and
+clean. You can easily see the subrepo's history with the \f(CW\*(C`git log\*(C'\fR command:
+.Sp
+.Vb 1
+\&    git log refs/subrepo/<subdir>/fetch
+.Ve
+.Sp
+The set of commands used above are described in detail below.
+.Sp
+The \f(CW\*(C`pull\*(C'\fR command accepts the \f(CW\*(C`\-\-all\*(C'\fR, \f(CW\*(C`\-\-branch=\*(C'\fR, \f(CW\*(C`\-\-edit\*(C'\fR, \f(CW\*(C`\-\-force\*(C'\fR,
+\&\f(CW\*(C`\-\-message=\*(C'\fR, \f(CW\*(C`\-\-remote=\*(C'\fR and \f(CW\*(C`\-\-update\*(C'\fR options.
+.ie n .IP """git subrepo push <subdir>|\-\-all [<branch>] [\-r <remote>] [\-b <branch>] [\-M|\-R] [\-u] [\-f] [\-s] [\-N]""" 4
+.el .IP "\f(CWgit subrepo push <subdir>|\-\-all [<branch>] [\-r <remote>] [\-b <branch>] [\-M|\-R] [\-u] [\-f] [\-s] [\-N]\fR" 4
+.IX Item "git subrepo push <subdir>|--all [<branch>] [-r <remote>] [-b <branch>] [-M|-R] [-u] [-f] [-s] [-N]"
+Push a properly merged subrepo branch back upstream.
+.Sp
+This command takes the subrepo branch from a successful pull command and
+pushes the history back to its designated remote and branch. You can also use
+the \f(CW\*(C`branch\*(C'\fR command and merge things yourself before pushing if you want to
+(although that is probably a rare use case).
+.Sp
+The \f(CW\*(C`push\*(C'\fR command requires a branch that has been properly merged/rebased
+with the upstream \s-1HEAD\s0 (unless the upstream \s-1HEAD\s0 is empty, which is common
+when doing a first \f(CW\*(C`push\*(C'\fR after an \f(CW\*(C`init\*(C'\fR). That means the upstream \s-1HEAD\s0 is
+one of the commits in the branch.
+.Sp
+By default the branch ref \f(CW\*(C`refs/subrepo/<subdir>/pull\*(C'\fR will be pushed,
+but you can specify a (properly merged) branch to push.
+.Sp
+After that, the \f(CW\*(C`push\*(C'\fR command just checks that the branch contains the
+upstream \s-1HEAD\s0 and then pushes it upstream.
+.Sp
+The \f(CW\*(C`\-\-force\*(C'\fR option will do a force push. Force pushes are typically
+discouraged. Only use this option if you fully understand it. (The \f(CW\*(C`\-\-force\*(C'\fR
+option will \s-1NOT\s0 check for a proper merge. \s-1ANY\s0 branch will be force pushed!)
+.Sp
+The \f(CW\*(C`push\*(C'\fR command accepts the \f(CW\*(C`\-\-all\*(C'\fR, \f(CW\*(C`\-\-branch=\*(C'\fR, \f(CW\*(C`\-\-dry\-run\*(C'\fR, \f(CW\*(C`\-\-
+force\*(C'\fR, \f(CW\*(C`\-\-merge\*(C'\fR, \f(CW\*(C`\-\-rebase\*(C'\fR, \f(CW\*(C`\-\-remote=\*(C'\fR, \f(CW\*(C`\-\-squash\*(C'\fR and \f(CW\*(C`\-\-
+update\*(C'\fR options.
+.ie n .IP """git subrepo fetch <subdir>|\-\-all [\-r <remote>] [\-b <branch>]""" 4
+.el .IP "\f(CWgit subrepo fetch <subdir>|\-\-all [\-r <remote>] [\-b <branch>]\fR" 4
+.IX Item "git subrepo fetch <subdir>|--all [-r <remote>] [-b <branch>]"
+Fetch the remote/upstream content for a subrepo.
+.Sp
+It will create a Git reference called \f(CW\*(C`subrepo/<subdir>/fetch\*(C'\fR that
+points at the same commit as \f(CW\*(C`FETCH_HEAD\*(C'\fR. It will also create a remote
+called \f(CW\*(C`subrepo/<subdir>\*(C'\fR. These are temporary and you can easily remove
+them with the subrepo \f(CW\*(C`clean\*(C'\fR command.
+.Sp
+The \f(CW\*(C`fetch\*(C'\fR command accepts the \f(CW\*(C`\-\-all\*(C'\fR, \f(CW\*(C`\-\-branch=\*(C'\fR and \f(CW\*(C`\-\-
+remote=\*(C'\fR options.
+.ie n .IP """git subrepo branch <subdir>|\-\-all [\-f] [\-F]""" 4
+.el .IP "\f(CWgit subrepo branch <subdir>|\-\-all [\-f] [\-F]\fR" 4
+.IX Item "git subrepo branch <subdir>|--all [-f] [-F]"
+Create a branch with local subrepo commits.
+.Sp
+Scan the history of the mainline for all the commits that affect the \f(CW\*(C`subdir\*(C'\fR
+and create a new branch from them called \f(CW\*(C`subrepo/<subdir>\*(C'\fR.
+.Sp
+This is useful for doing \f(CW\*(C`pull\*(C'\fR and \f(CW\*(C`push\*(C'\fR commands by hand.
+.Sp
+Use the \f(CW\*(C`\-\-force\*(C'\fR option to write over an existing \f(CW\*(C`subrepo/<subdir>\*(C'\fR branch.
+.Sp
+The \f(CW\*(C`branch\*(C'\fR command accepts the \f(CW\*(C`\-\-all\*(C'\fR, \f(CW\*(C`\-\-fetch\*(C'\fR and \f(CW\*(C`\-\-force\*(C'\fR options.
+.ie n .IP """git subrepo commit <subdir> [<subrepo\-ref>] [\-m <msg>] [\-e] [\-f] [\-F]""" 4
+.el .IP "\f(CWgit subrepo commit <subdir> [<subrepo\-ref>] [\-m <msg>] [\-e] [\-f] [\-F]\fR" 4
+.IX Item "git subrepo commit <subdir> [<subrepo-ref>] [-m <msg>] [-e] [-f] [-F]"
+Add subrepo branch to current history as a single commit.
+.Sp
+This command is generally used after a hand-merge. You have done a \f(CW\*(C`subrepo
+branch\*(C'\fR and merged (rebased) it with the upstream. This command takes the \s-1HEAD\s0
+of that branch, puts its content into the subrepo subdir and adds a new commit
+for it to the top of your mainline history.
+.Sp
+This command requires that the upstream \s-1HEAD\s0 be in the \f(CW\*(C`subrepo/<subdir>\*(C'\fR
+branch history. That way the same branch can push upstream. Use the \f(CW\*(C`\-\-force\*(C'\fR
+option to commit anyway.
+.Sp
+The \f(CW\*(C`commit\*(C'\fR command accepts the \f(CW\*(C`\-\-edit\*(C'\fR, \f(CW\*(C`\-\-fetch\*(C'\fR, \f(CW\*(C`\-\-force\*(C'\fR and \f(CW\*(C`\-\-
+message=\*(C'\fR options.
+.ie n .IP """git subrepo status [<subdir>|\-\-all|\-\-ALL] [\-F] [\-q|\-v]""" 4
+.el .IP "\f(CWgit subrepo status [<subdir>|\-\-all|\-\-ALL] [\-F] [\-q|\-v]\fR" 4
+.IX Item "git subrepo status [<subdir>|--all|--ALL] [-F] [-q|-v]"
+Get the status of a subrepo. Uses the \f(CW\*(C`\-\-all\*(C'\fR option by default. If the \f(CW\*(C`\-\-
+quiet\*(C'\fR flag is used, just print the subrepo names, one per line.
+.Sp
+The \f(CW\*(C`\-\-verbose\*(C'\fR option will show all the recent local and upstream commits.
+.Sp
+Use \f(CW\*(C`\-\-ALL\*(C'\fR to show the subrepos of the subrepos (ie the
+\&\*(L"subsubrepos\*(R"), if any.
+.Sp
+The \f(CW\*(C`status\*(C'\fR command accepts the \f(CW\*(C`\-\-all\*(C'\fR, \f(CW\*(C`\-\-ALL\*(C'\fR, \f(CW\*(C`\-\-fetch\*(C'\fR, \f(CW\*(C`\-\-quiet\*(C'\fR
+and \f(CW\*(C`\-\-verbose\*(C'\fR options.
+.ie n .IP """git subrepo clean <subdir>|\-\-all|\-\-ALL [\-f]""" 4
+.el .IP "\f(CWgit subrepo clean <subdir>|\-\-all|\-\-ALL [\-f]\fR" 4
+.IX Item "git subrepo clean <subdir>|--all|--ALL [-f]"
+Remove artifacts created by \f(CW\*(C`fetch\*(C'\fR and \f(CW\*(C`branch\*(C'\fR commands.
+.Sp
+The \f(CW\*(C`fetch\*(C'\fR and \f(CW\*(C`branch\*(C'\fR operations (and other commands that call them)
+create temporary things like refs, branches and remotes. This command removes
+all those things.
+.Sp
+Use \f(CW\*(C`\-\-force\*(C'\fR to remove refs. Refs are not removed by default because they
+are sometimes needed between commands.
+.Sp
+Use \f(CW\*(C`\-\-all\*(C'\fR to clean up after all the current subrepos. Sometimes you might
+change to a branch where a subrepo doesn't exist, and then \f(CW\*(C`\-\-all\*(C'\fR won't find
+it. Use \f(CW\*(C`\-\-ALL\*(C'\fR to remove any artifacts that were ever created by subrepo.
+.Sp
+To remove \s-1ALL\s0 subrepo artifacts:
+.Sp
+.Vb 1
+\&    git subrepo clean \-\-ALL \-\-force
+.Ve
+.Sp
+The \f(CW\*(C`clean\*(C'\fR command accepts the \f(CW\*(C`\-\-all\*(C'\fR, \f(CW\*(C`\-\-ALL\*(C'\fR, and \f(CW\*(C`\-\-force\*(C'\fR options.
+.ie n .IP """git subrepo config <subdir> <option> [<value>] [\-f]""" 4
+.el .IP "\f(CWgit subrepo config <subdir> <option> [<value>] [\-f]\fR" 4
+.IX Item "git subrepo config <subdir> <option> [<value>] [-f]"
+Read or update configuration values in the subdir/.gitrepo file.
+.Sp
+Because most of the values stored in the .gitrepo file are generated you
+will need to use \f(CW\*(C`\-\-force\*(C'\fR if you want to change anything else then the
+\&\f(CW\*(C`method\*(C'\fR option.
+.Sp
+Example to update the \f(CW\*(C`method\*(C'\fR option for a subrepo:
+.Sp
+.Vb 1
+\&    git subrepo config foo method rebase
+.Ve
+.ie n .IP """git subrepo help [<command>|\-\-all]""" 4
+.el .IP "\f(CWgit subrepo help [<command>|\-\-all]\fR" 4
+.IX Item "git subrepo help [<command>|--all]"
+Same as \f(CW\*(C`git help subrepo\*(C'\fR. Will launch the manpage. For the shorter usage,
+use \f(CW\*(C`git subrepo \-h\*(C'\fR.
+.Sp
+Use \f(CW\*(C`git subrepo help <command>\*(C'\fR to get help for a specific command. Use
+\&\f(CW\*(C`\-\-all\*(C'\fR to get a summary of all commands.
+.Sp
+The \f(CW\*(C`help\*(C'\fR command accepts the \f(CW\*(C`\-\-all\*(C'\fR option.
+.ie n .IP """git subrepo version [\-q|\-v]""" 4
+.el .IP "\f(CWgit subrepo version [\-q|\-v]\fR" 4
+.IX Item "git subrepo version [-q|-v]"
+This command will display version information about git-subrepo and its
+environment. For just the version number, use \f(CW\*(C`git subrepo \-\-version\*(C'\fR. Use
+\&\f(CW\*(C`\-\-verbose\*(C'\fR for more version info, and \f(CW\*(C`\-\-quiet\*(C'\fR for less.
+.Sp
+The \f(CW\*(C`version\*(C'\fR command accepts the \f(CW\*(C`\-\-quiet\*(C'\fR and \f(CW\*(C`\-\-verbose\*(C'\fR options.
+.ie n .IP """git subrepo upgrade""" 4
+.el .IP "\f(CWgit subrepo upgrade\fR" 4
+.IX Item "git subrepo upgrade"
+Upgrade the \f(CW\*(C`git\-subrepo\*(C'\fR software itself. This simply does a \f(CW\*(C`git pull\*(C'\fR
+on the git repository that the code is running from. It only works if you
+are on the \f(CW\*(C`master\*(C'\fR branch. It won't work if you installed \f(CW\*(C`git\-subrepo\*(C'\fR
+using \f(CW\*(C`make install\*(C'\fR; in that case you'll need to \f(CW\*(C`make install\*(C'\fR from the
+latest code.
+.SH "Command Options"
+.IX Header "Command Options"
+.ie n .IP """\-h""" 4
+.el .IP "\f(CW\-h\fR" 4
+.IX Item "-h"
+Show a brief view of the commands and options.
+.ie n .IP """\-\-help""" 4
+.el .IP "\f(CW\-\-help\fR" 4
+.IX Item "--help"
+Gives an overview of the help options available for the subrepo command.
+.ie n .IP """\-\-version""" 4
+.el .IP "\f(CW\-\-version\fR" 4
+.IX Item "--version"
+Print the git-subrepo version. Just the version number. Try the \f(CW\*(C`version\*(C'\fR
+command for more version info.
+.ie n .IP """\-\-all"" (""\-a"")" 4
+.el .IP "\f(CW\-\-all\fR (\f(CW\-a\fR)" 4
+.IX Item "--all (-a)"
+If you have multiple subrepos, issue the command to all of them (if
+applicable).
+.ie n .IP """\-\-ALL"" (""\-A"")" 4
+.el .IP "\f(CW\-\-ALL\fR (\f(CW\-A\fR)" 4
+.IX Item "--ALL (-A)"
+If you have subrepos that also have subrepos themselves, issue the command to
+\&\s-1ALL\s0 of them. Note that the \f(CW\*(C`\-\-ALL\*(C'\fR option only works for a subset of the
+commands that \f(CW\*(C`\-\-all\*(C'\fR works for.
+.ie n .IP """\-\-branch=<branch\-name>"" (""\-b <branch\-name>"")" 4
+.el .IP "\f(CW\-\-branch=<branch\-name>\fR (\f(CW\-b <branch\-name>\fR)" 4
+.IX Item "--branch=<branch-name> (-b <branch-name>)"
+Use a different upstream branch-name than the remote \s-1HEAD\s0 or the one saved in
+\&\f(CW\*(C`.gitrepo\*(C'\fR locally.
+.ie n .IP """\-\-dry\-run"" (""\-N"")" 4
+.el .IP "\f(CW\-\-dry\-run\fR (\f(CW\-N\fR)" 4
+.IX Item "--dry-run (-N)"
+For the push command, do everything up until the push and then print out the
+actual \f(CW\*(C`git push\*(C'\fR command needed to finish the operation.
+.ie n .IP """\-\-edit"" (""\-e"")" 4
+.el .IP "\f(CW\-\-edit\fR (\f(CW\-e\fR)" 4
+.IX Item "--edit (-e)"
+Edit the commit message before committing.
+.ie n .IP """\-\-fetch"" (""\-F"")" 4
+.el .IP "\f(CW\-\-fetch\fR (\f(CW\-F\fR)" 4
+.IX Item "--fetch (-F)"
+Use this option to fetch the upstream commits, before running the command.
+.ie n .IP """\-\-force"" (""\-f"")" 4
+.el .IP "\f(CW\-\-force\fR (\f(CW\-f\fR)" 4
+.IX Item "--force (-f)"
+Use this option to force certain commands that fail in the general case.
+.Sp
+\&\s-1NOTE:\s0 The \f(CW\*(C`\-\-force\*(C'\fR option means different things for different commands.
+      Read the command specific doc for the exact meaning.
+.ie n .IP """\-\-merge"" (""\-M"")" 4
+.el .IP "\f(CW\-\-merge\fR (\f(CW\-M\fR)" 4
+.IX Item "--merge (-M)"
+Use a \f(CW\*(C`merge\*(C'\fR strategy to include upstream subrepo commits on a pull (or
+setup for push).
+.ie n .IP """\-\-message=<message>"" (""\-m <message>"")" 4
+.el .IP "\f(CW\-\-message=<message>\fR (\f(CW\-m <message>\fR)" 4
+.IX Item "--message=<message> (-m <message>)"
+Specify your own commit message on the command line.
+.ie n .IP """\-\-rebase"" (""\-R"")" 4
+.el .IP "\f(CW\-\-rebase\fR (\f(CW\-R\fR)" 4
+.IX Item "--rebase (-R)"
+Use a \f(CW\*(C`rebase\*(C'\fR strategy to include upstream subrepo commits on a pull (or
+setup for push).
+.ie n .IP """\-\-remote=<remote\-url>"" (""\-r <remote\-url>"")" 4
+.el .IP "\f(CW\-\-remote=<remote\-url>\fR (\f(CW\-r <remote\-url>\fR)" 4
+.IX Item "--remote=<remote-url> (-r <remote-url>)"
+Use a different remote-url than the one saved in \f(CW\*(C`.gitrepo\*(C'\fR locally.
+.ie n .IP """\-\-squash"" (""\-s"")" 4
+.el .IP "\f(CW\-\-squash\fR (\f(CW\-s\fR)" 4
+.IX Item "--squash (-s)"
+Squash all commits on a push into one new commit.
+.ie n .IP """\-\-update"" (""\-u"")" 4
+.el .IP "\f(CW\-\-update\fR (\f(CW\-u\fR)" 4
+.IX Item "--update (-u)"
+If \f(CW\*(C`\-\-branch\*(C'\fR or \f(CW\*(C`\-\-remote\*(C'\fR are used, and the command updates the
+\&\f(CW\*(C`.gitrepo\*(C'\fR file, include these values to the update.
+.SH "Output Options"
+.IX Header "Output Options"
+.ie n .IP """\-\-quiet"" (""\-q"")" 4
+.el .IP "\f(CW\-\-quiet\fR (\f(CW\-q\fR)" 4
+.IX Item "--quiet (-q)"
+Print as little info as possible. Applicable to most commands.
+.ie n .IP """\-\-verbose"" (""\-v"")" 4
+.el .IP "\f(CW\-\-verbose\fR (\f(CW\-v\fR)" 4
+.IX Item "--verbose (-v)"
+Print more information about the command execution and results. Applicable to
+most commands.
+.ie n .IP """\-\-debug"" (""\-d"")" 4
+.el .IP "\f(CW\-\-debug\fR (\f(CW\-d\fR)" 4
+.IX Item "--debug (-d)"
+Show the actual git (and other) commands being executed under the hood.
+Applicable to most commands.
+.ie n .IP """\-\-DEBUG"" (""\-x"")" 4
+.el .IP "\f(CW\-\-DEBUG\fR (\f(CW\-x\fR)" 4
+.IX Item "--DEBUG (-x)"
+Use the Bash \f(CW\*(C`set \-x\*(C'\fR option which prints every command before it is
+run. \s-1VERY\s0 noisy, but extremely useful in deep debugging. Applicable to
+all commands.
+.SH "Environment Variables"
+.IX Header "Environment Variables"
+The \f(CW\*(C`git\-subrepo\*(C'\fR command exports and honors some environment variables:
+.ie n .IP """GIT_SUBREPO_ROOT""" 4
+.el .IP "\f(CWGIT_SUBREPO_ROOT\fR" 4
+.IX Item "GIT_SUBREPO_ROOT"
+This is set by the \f(CW\*(C`.rc\*(C'\fR file, if you use that method to install / enable \f(CW\*(C`git\-
+subrepo\*(C'\fR. It contains the path of the \f(CW\*(C`git\-subrepo\*(C'\fR repository.
+.ie n .IP """GIT_SUBREPO_RUNNING""" 4
+.el .IP "\f(CWGIT_SUBREPO_RUNNING\fR" 4
+.IX Item "GIT_SUBREPO_RUNNING"
+This variable is exported when \f(CW\*(C`git\-subrepo\*(C'\fR is running. It is set to the pid
+of the \f(CW\*(C`git\-subrepo\*(C'\fR process that is running. Other processes, like git hooks
+for instance, can use this information to adjust accordingly.
+.ie n .IP """GIT_SUBREPO_COMMAND""" 4
+.el .IP "\f(CWGIT_SUBREPO_COMMAND\fR" 4
+.IX Item "GIT_SUBREPO_COMMAND"
+This variable is exported when \f(CW\*(C`git\-subrepo\*(C'\fR is running. It is set to the
+name of the \f(CW\*(C`git\-subrepo\*(C'\fR subcommand that is running.
+.ie n .IP """GIT_SUBREPO_PAGER""" 4
+.el .IP "\f(CWGIT_SUBREPO_PAGER\fR" 4
+.IX Item "GIT_SUBREPO_PAGER"
+Use this to specify the pager to use for long output commands. Defaults to
+\&\f(CW$PAGER\fR or \f(CW\*(C`less\*(C'\fR.
+.ie n .IP """GIT_SUBREPO_QUIET""" 4
+.el .IP "\f(CWGIT_SUBREPO_QUIET\fR" 4
+.IX Item "GIT_SUBREPO_QUIET"
+Set this for quiet (\f(CW\*(C`\-q\*(C'\fR) output.
+.ie n .IP """GIT_SUBREPO_VERBOSE""" 4
+.el .IP "\f(CWGIT_SUBREPO_VERBOSE\fR" 4
+.IX Item "GIT_SUBREPO_VERBOSE"
+Set this for verbose (\f(CW\*(C`\-v\*(C'\fR) output.
+.ie n .IP """GIT_SUBREPO_DEBUG""" 4
+.el .IP "\f(CWGIT_SUBREPO_DEBUG\fR" 4
+.IX Item "GIT_SUBREPO_DEBUG"
+Set this for debugging (\f(CW\*(C`\-d\*(C'\fR) output.
+.SH "Installation Instructions"
+.IX Header "Installation Instructions"
+There are currently 3 ways to install \f(CW\*(C`git\-subrepo\*(C'\fR. For all of them you need
+to get the source code from GitHub:
+.PP
+.Vb 1
+\&    git clone https://github.com/ingydotnet/git\-subrepo /path/to/git\-subrepo
+.Ve
+.PP
+The first installation method is preferred: \f(CW\*(C`source\*(C'\fR the \f(CW\*(C`.rc\*(C'\fR file. Just
+add a line like this one to your shell startup script:
+.PP
+.Vb 1
+\&    source /path/to/git\-subrepo/.rc
+.Ve
+.PP
+That will modify your \f(CW\*(C`PATH\*(C'\fR and \f(CW\*(C`MANPATH\*(C'\fR, and also enable command
+completion.
+.PP
+The second method is to do these things by hand. This might afford you more
+control of your shell environment. Simply add the \f(CW\*(C`lib\*(C'\fR and \f(CW\*(C`man\*(C'\fR
+directories to your \f(CW\*(C`PATH\*(C'\fR and \f(CW\*(C`MANPATH\*(C'\fR:
+.PP
+.Vb 3
+\&    export GIT_SUBREPO_ROOT="/path/to/git\-subrepo"
+\&    export PATH="/path/to/git\-subrepo/lib:$PATH"
+\&    export MANPATH="/path/to/git\-subrepo/man:$MANPATH"
+.Ve
+.PP
+See below for info on how to turn on Command Completion.
+.PP
+The third method is a standard system install, which puts \f(CW\*(C`git\-subrepo\*(C'\fR next
+to your other git commands:
+.PP
+.Vb 1
+\&    make install        # Possibly with \*(Aqsudo\*(Aq
+.Ve
+.PP
+This method does not account for upgrading and command completion yet.
+.SS "Windows"
+.IX Subsection "Windows"
+This command is known to work in these Windows environments:
+.IP "\(bu" 4
+Git for Windows \*(-- <https://git\-for\-windows.github.io/>
+.IP "\(bu" 4
+Babun \*(-- <http://babun.github.io/>
+.IP "\(bu" 4
+Cygwin \*(-- <https://www.cygwin.com/>
+.PP
+Let us know if there are others that it works (or doesn't work) in.
+.SH "Testing"
+.IX Header "Testing"
+The \f(CW\*(C`git\-subrepo\*(C'\fR repository comes with a extensive test suite. You can
+run it with:
+.PP
+.Vb 1
+\&    make test
+.Ve
+.PP
+or if you don't have \f(CW\*(C`make\*(C'\fR on your system:
+.PP
+.Vb 1
+\&    prove \-v test
+.Ve
+.SH "Upgrading"
+.IX Header "Upgrading"
+If you used the \f(CW\*(C`.rc\*(C'\fR or \f(CW\*(C`PATH\*(C'\fR method of installation, just run this to
+upgrade \f(CW\*(C`git\-subrepo\*(C'\fR:
+.PP
+.Vb 1
+\&    git subrepo upgrade
+.Ve
+.PP
+Or (same thing):
+.PP
+.Vb 2
+\&    cd /path/to/git\-subrepo
+\&    git pull
+.Ve
+.PP
+If you used \f(CW\*(C`make install\*(C'\fR method, then run this again (after \f(CW\*(C`git pull\*(C'\fR):
+.PP
+.Vb 1
+\&    make install        # Possibly with \*(Aqsudo\*(Aq
+.Ve
+.SH "Command Completion"
+.IX Header "Command Completion"
+The \f(CW\*(C`git subrepo\*(C'\fR command supports \f(CW\*(C`<TAB>\*(C'\fR\-based command completion. If
+you don't use the \f(CW\*(C`.rc\*(C'\fR script (see Installation, above), you'll need to
+enable this manually to use it.
+.SS "In Bash"
+.IX Subsection "In Bash"
+If your Bash setup does not already provide command completion for Git, you'll
+need to enable that first:
+.PP
+.Vb 1
+\&    source <Git completion script>
+.Ve
+.PP
+On your system, the Git completion script might be found at any of the
+following locations (or somewhere else that we don't know about):
+.IP "\(bu" 4
+\&\f(CW\*(C`/etc/bash_completion.d/git\*(C'\fR
+.IP "\(bu" 4
+\&\f(CW\*(C`/usr/share/bash\-completion/git\*(C'\fR
+.IP "\(bu" 4
+\&\f(CW\*(C`/usr/share/bash\-completion/completions/git\*(C'\fR
+.IP "\(bu" 4
+\&\f(CW\*(C`/opt/local/share/bash\-completion/completions/git\*(C'\fR
+.IP "\(bu" 4
+\&\f(CW\*(C`/usr/local/etc/bash_completion.d/git\*(C'\fR
+.IP "\(bu" 4
+\&\f(CW\*(C`~/.homebrew/etc/bash_completion.d/git\*(C'\fR
+.PP
+In case you can't find any of these, this repository contains a copy of the
+Git completion script:
+.PP
+.Vb 1
+\&    source /path/to/git\-subrepo/share/git\-completion.bash
+.Ve
+.PP
+Once Git completion is enabled (whether you needed to do that manually or
+not), you can turn on \f(CW\*(C`git\-subrepo\*(C'\fR completion with a command like this:
+.PP
+.Vb 1
+\&    source /path/to/git\-subrepo/share/completion.bash
+.Ve
+.SS "In zsh"
+.IX Subsection "In zsh"
+In the Z shell (zsh), you can manually enable \f(CW\*(C`git\-subrepo\*(C'\fR completion by
+adding the following line to your \f(CW\*(C`~/.zshrc\*(C'\fR, \fBbefore\fR the \f(CW\*(C`compinit\*(C'\fR
+function is called:
+.PP
+.Vb 1
+\&    fpath=(\*(Aq/path/to/git\-subrepo/share/zsh\-completion\*(Aq $fpath)
+.Ve
+.SH "Status"
+.IX Header "Status"
+The git-subrepo command has been in use for well over a year and seems to get
+the job done. Development is still ongoing but mostly just for fixing bugs.
+.PP
+Trying subrepo out is simple and painless (this is not \f(CW\*(C`git submodule\*(C'\fR).
+Nothing is permanent (if you do not push to shared remotes). ie You can always
+play around and reset back to the beginning without pain.
+.PP
+This command has a test suite (run \f(CW\*(C`make test\*(C'\fR), but surely has many bugs. If
+you have expertise with Git and subcommands, please review the code, and file
+issues on anything that seems wrong.
+.PP
+If you want to chat about the \f(CW\*(C`git\-subrepo\*(C'\fR command, join \f(CW\*(C`#gitcommands\*(C'\fR on
+\&\f(CW\*(C`irc.freenode.net\*(C'\fR.
+.SH "Notes"
+.IX Header "Notes"
+.IP "\(bu" 4
+Works on \s-1POSIX\s0 systems: Linux, \s-1BSD, OSX,\s0 etc.
+.IP "\(bu" 4
+Works on various Windows environments. See \*(L"Windows\*(R" section above.
+.IP "\(bu" 4
+The \f(CW\*(C`git\-subrepo\*(C'\fR repo itself has 2 subrepos under the \f(CW\*(C`ext/\*(C'\fR subdirectory.
+.IP "\(bu" 4
+Written in (very modern) Bash, with full test suite. Take a look.
+.IP "\(bu" 4
+A \f(CW\*(C`.gitrepo\*(C'\fR file never is in the top level dir (next to a \f(CW\*(C`.git/\*(C'\fR dir).
+.SH "Authors"
+.IX Header "Authors"
+.IP "\(bu" 4
+Ingy döt Net <ingy@ingy.net>
+.IP "\(bu" 4
+Magnus Carlsson <grimmymail@gmail.com>
+.SH "License and Copyright"
+.IX Header "License and Copyright"
+The \s-1MIT\s0 License (\s-1MIT\s0)
+.PP
+Copyright (c) 2013\-2020 Ingy döt Net