.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
.\"
.\" 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
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    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 2024-07-22 "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 "clones" 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 "Installation Instructions" 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>] [\-\-file=<msg file>] [\-e] [\-\-method <merge|rebase>]""" 4
.el .IP "\f(CWgit subrepo clone <repository> [<subdir>] [\-b <branch>] [\-f] [\-m <msg>] [\-\-file=<msg file>] [\-e] [\-\-method <merge|rebase>]\fR" 4
.IX Item "git subrepo clone <repository> [<subdir>] [-b <branch>] [-f] [-m <msg>] [--file=<msg file>] [-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 "reclone" (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`\-\-file\*(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\*(C'\fR/.gitrepo >> 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 URL, 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\*(C'\fR/.gitrepo >> 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>] [\-\-file=<msg file>] [\-e] [\-b <branch>] [\-r <remote>] [\-u]""" 4
.el .IP "\f(CWgit subrepo pull <subdir>|\-\-all [\-M|\-R|\-f] [\-m <msg>] [\-\-file=<msg file>] [\-e] [\-b <branch>] [\-r <remote>] [\-u]\fR" 4
.IX Item "git subrepo pull <subdir>|--all [-M|-R|-f] [-m <msg>] [--file=<msg file>] [-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`\-\-file\*(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>] [\-m msg] [\-\-file=<msg file>] [\-r <remote>] [\-b <branch>] [\-M|\-R] [\-u] [\-f] [\-s] [\-N]""" 4
.el .IP "\f(CWgit subrepo push <subdir>|\-\-all [<branch>] [\-m msg] [\-\-file=<msg file>] [\-r <remote>] [\-b <branch>] [\-M|\-R] [\-u] [\-f] [\-s] [\-N]\fR" 4
.IX Item "git subrepo push <subdir>|--all [<branch>] [-m msg] [--file=<msg file>] [-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 HEAD (unless the upstream HEAD 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 HEAD 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 HEAD 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 NOT check for a proper merge. ANY 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`\-\-file\*(C'\fR, \f(CW\*(C`\-\-force\*(C'\fR, \f(CW\*(C`\-\-merge\*(C'\fR, \f(CW\*(C`\-\-message\*(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>|\-\-force \-\-all [\-r <remote>] [\-b <branch>]""" 4
.el .IP "\f(CWgit subrepo fetch <subdir>|\-\-force \-\-all [\-r <remote>] [\-b <branch>]\fR" 4
.IX Item "git subrepo fetch <subdir>|--force --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`\-\-force\*(C'\fR, \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>] [\-\-file=<msg file>] [\-e] [\-f] [\-F]""" 4
.el .IP "\f(CWgit subrepo commit <subdir> [<subrepo\-ref>] [\-m <msg>] [\-\-file=<msg file>] [\-e] [\-f] [\-F]\fR" 4
.IX Item "git subrepo commit <subdir> [<subrepo-ref>] [-m <msg>] [--file=<msg file>] [-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`subrepobranch\*(C'\fR and merged (rebased) it with the upstream. This command takes the HEAD
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 HEAD 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`\-\-file\*(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
"subsubrepos"), 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 ALL 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
ALL 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 HEAD 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 """\-\-file=<commit msg file>""" 4
.el .IP "\f(CW\-\-file=<commit msg file>\fR" 4
.IX Item "--file=<commit msg file>"
Supply your own commit message from a file
.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
NOTE: 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. VERY 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 used in production 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 POSIX systems: Linux, BSD, OSX, etc.
.IP \(bu 4
Works on various Windows environments. See "Windows" 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>
.IP \(bu 4
Austin Morgan <admorgan@morgancomputers.net>
.SH "License and Copyright"
.IX Header "License and Copyright"
The MIT License (MIT)
.PP
Copyright (c) 2013\-2020 Ingy döt Net