=pod
=for comment DO NOT EDIT. This Pod was generated by Swim v0.1.48. See http://github.com/ingydotnet/swim-pm#readme
=encoding utf8
=head1 Name
git-subrepo - Git Submodule Alternative
=head1 Synopsis
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
=head1 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.
=head1 Benefits
This command is an improvement from C
It assumes there are 3 main roles of people interacting with a repo, and attempts to serve them all well:
=over
=item * B
=item * B
=item * B
=back
The C
=over
=item * Simple and intuitive commandline usage (with tab completion).
=item * Users get your repo and all your subrepos just by cloning your repo.
=item * Users do not need to install C
=item * Collaborators do not need to install unless they want to push/pull.
=item * Collaborators know when a subdir is a subrepo (it has a C<.gitrepo> file).
=item * The C<.gitrepo> file never gets pushed back to the subrepo upstream.
=item * Well named branches and remotes are generated for manual operations.
=item * Owners do not deal with the complications of keeping submodules in sync.
=item * Subrepo repositories can contain subrepos themselves.
=item * Branching with subrepos JustWorks™.
=item * Different branches can have different subrepos in different states, etc.
=item * Moving/renaming/deleting a subrepo subdir JustWorks™.
=item * You can C
=item * Your git history is kept squeaky clean.
=item * Upstream history (clone/pull) is condensed into a single commit.
=item * Pulls can use a C
=item * You can see the subrepo history with C<< git log subrepo/
=item * Commits pushed back upstream are B
=item * Trivial to try any subrepo operations and then reset back.
=item * No configuration required.
=item * Does not introduce history that messes up other git commands.
=item * Fixes known rebase failures with C
=back
=head1 Installation
The best short answer is:
git clone https://github.com/ingydotnet/git-subrepo /path/to/git-subrepo
echo 'source /path/to/git-subrepo/.rc' >> ~/.bashrc
The complete "Installation Instructions" can be found below.
Note: git-subrepo needs a git version (> 2.7) that supports worktree:s.
=head1 Commands
All the B
Please note that the commands are I
=over
=item C<< git subrepo clone
Add a repository as a subrepo in a subdir of your repository.
This is similar in feel to C
The subrepo history is I
All subsequent commands refer to the subrepo by the name of the
I
The C<--force> option will "reclone" (completely replace) an existing subdir.
The C<--method> option will decide how the join process between branches are performed. The default option is merge.
The C
=item C<< git subrepo init
Turn an existing subdirectory into a subrepo.
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 C<<
If you specify the C<--remote> (and optionally the C<--branch>) option, the
values will be added to the C<<
Note: You will need to create the empty upstream repo and push to it on your
own, using C<< git subrepo push
The C<--method> option will decide how the join process between branches are performed. The default option is merge.
The C
=item C<< git subrepo pull
Update the subrepo subdir with the latest upstream changes.
The C
The C
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>
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.
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 C<< subrepo/
When you pull you can assume a fast-forward strategy (default) or you can specify a C<--rebase>, C<--merge> or C<--force> strategy. The latter is the same as a C<clone --force> operation, using the current remote and branch.
Like the C
git log refs/subrepo/<subdir>/fetch
The set of commands used above are described in detail below.
The C
=item C<< git subrepo push
Push a properly merged subrepo branch back upstream.
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 C
The C
By default the branch ref C<< refs/subrepo/
After that, the C
The C<--force> option will do a force push. Force pushes are typically discouraged. Only use this option if you fully understand it. (The C<--force> option will NOT check for a proper merge. ANY branch will be force pushed!)
The C
=item C<< git subrepo fetch
Fetch the remote/upstream content for a subrepo.
It will create a Git reference called C<< subrepo/
The C
=item C<< git subrepo branch
Create a branch with local subrepo commits.
Scan the history of the mainline for all the commits that affect the C
This is useful for doing C
Use the C<--force> option to write over an existing C<< subrepo/
branch.
The C
=item C<< git subrepo commit
Add subrepo branch to current history as a single commit.
This command is generally used after a hand-merge. You have done a C
This command requires that the upstream HEAD be in the C<< subrepo/
The C
=item C<< git subrepo status [
Get the status of a subrepo. Uses the C<--all> option by default. If the C<--quiet> flag is used, just print the subrepo names, one per line.
The C<--verbose> option will show all the recent local and upstream commits.
Use C<--ALL> to show the subrepos of the subrepos (ie the "subsubrepos"), if any.
The C
=item C<< git subrepo clean
Remove artifacts created by C
The C
Use C<--force> to remove refs. Refs are not removed by default because they are sometimes needed between commands.
Use C<--all> to clean up after all the current subrepos. Sometimes you might change to a branch where a subrepo doesn't exist, and then C<--all> won't find it. Use C<--ALL> to remove any artifacts that were ever created by subrepo.
To remove ALL subrepo artifacts:
git subrepo clean --ALL --force
The C
=item C<< git subrepo config
Read or update configuration values in the subdir/.gitrepo file.
Because most of the values stored in the .gitrepo file are generated you
will need to use C<--force> if you want to change anything else then the
C
Example to update the C
git subrepo config foo method rebase
=item C<< git subrepo help [
Same as C
Use C<< git subrepo help
The C
=item C<git subrepo version [-q|-v]>
This command will display version information about git-subrepo and its environment. For just the version number, use C<git subrepo --version>. Use C<--verbose> for more version info, and C<--quiet> for less.
The C
=item C
Upgrade the C
=back
=head1 Command Options
=over
=item C<-h>
Show a brief view of the commands and options.
=item C<--help>
Gives an overview of the help options available for the subrepo command.
=item C<--version>
Print the git-subrepo version. Just the version number. Try the C
=item C<--all> (C<-a>)
If you have multiple subrepos, issue the command to all of them (if applicable).
=item C<--ALL> (C<-A>)
If you have subrepos that also have subrepos themselves, issue the command to ALL of them. Note that the C<--ALL> option only works for a subset of the commands that C<--all> works for.
=item C<< --branch=
Use a different upstream branch-name than the remote HEAD or the one saved in C<.gitrepo> locally.
=item C<--dry-run> (C<-N>)
For the push command, do everything up until the push and then print out the
actual C
=item C<--edit> (C<-e>)
Edit the commit message before committing.
=item C<--fetch> (C<-F>)
Use this option to fetch the upstream commits, before running the command.
=item C<< --file=
Supply your own commit message from a file
=item C<--force> (C<-f>)
Use this option to force certain commands that fail in the general case.
NOTE: The C<--force> option means different things for different commands. Read the command specific doc for the exact meaning.
=item C<--merge> (C<-M>)
Use a C
=item C<< --message=
Specify your own commit message on the command line.
=item C<--rebase> (C<-R>)
Use a C
=item C<< --remote=
Use a different remote-url than the one saved in C<.gitrepo> locally.
=item C<--squash> (C<-s>)
Squash all commits on a push into one new commit.
=item C<--update> (C<-u>)
If C<--branch> or C<--remote> are used, and the command updates the C<.gitrepo> file, include these values to the update.
=back
=head1 Output Options
=over
=item C<--quiet> (C<-q>)
Print as little info as possible. Applicable to most commands.
=item C<--verbose> (C<-v>)
Print more information about the command execution and results. Applicable to most commands.
=item C<--debug> (C<-d>)
Show the actual git (and other) commands being executed under the hood. Applicable to most commands.
=item C<--DEBUG> (C<-x>)
Use the Bash C<set -x> option which prints every command before it is run. VERY noisy, but extremely useful in deep debugging. Applicable to all commands.
=back
=head1 Environment Variables
The C
=over
=item C
This is set by the C<.rc> file, if you use that method to install / enable C
=item C
This variable is exported when C
=item C
This variable is exported when C
=item C
Use this to specify the pager to use for long output commands. Defaults to
C<$PAGER> or C
=item C
Set this for quiet (C<-q>) output.
=item C
Set this for verbose (C<-v>) output.
=item C
Set this for debugging (C<-d>) output.
=back
=head1 Installation Instructions
There are currently 3 ways to install C
git clone https://github.com/ingydotnet/git-subrepo /path/to/git-subrepo
The first installation method is preferred: C
source /path/to/git-subrepo/.rc
That will modify your C
The second method is to do these things by hand. This might afford you more
control of your shell environment. Simply add the C
export GIT_SUBREPO_ROOT="/path/to/git-subrepo"
export PATH="/path/to/git-subrepo/lib:$PATH"
export MANPATH="/path/to/git-subrepo/man:$MANPATH"
See below for info on how to turn on Command Completion.
The third method is a standard system install, which puts C
make install # Possibly with 'sudo'
This method does not account for upgrading and command completion yet.
=head2 Windows
This command is known to work in these Windows environments:
=over
=item * Git for Windows -- Lhttps://git-for-windows.github.io/
=item * Babun -- Lhttp://babun.github.io/
=item * Cygwin -- Lhttps://www.cygwin.com/
=back
Let us know if there are others that it works (or doesn't work) in.
=head1 Testing
The C
make test
or if you don't have C
prove -v test
=head1 Upgrading
If you used the C<.rc> or C
git subrepo upgrade
Or (same thing):
cd /path/to/git-subrepo
git pull
If you used C
make install # Possibly with 'sudo'
=head1 Command Completion
The C
=head2 In Bash
If your Bash setup does not already provide command completion for Git, you'll need to enable that first:
source <Git completion script>
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):
=over
=item * C</etc/bash_completion.d/git>
=item * C</usr/share/bash-completion/git>
=item * C</usr/share/bash-completion/completions/git>
=item * C</opt/local/share/bash-completion/completions/git>
=item * C</usr/local/etc/bash_completion.d/git>
=item * C<~/.homebrew/etc/bash_completion.d/git>
=back
In case you can't find any of these, this repository contains a copy of the Git completion script:
source /path/to/git-subrepo/share/git-completion.bash
Once Git completion is enabled (whether you needed to do that manually or
not), you can turn on C
source /path/to/git-subrepo/share/completion.bash
=head2 In zsh
In the Z shell (zsh), you can manually enable C
fpath=('/path/to/git-subrepo/share/zsh-completion' $fpath)
=head1 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.
Trying subrepo out is simple and painless (this is not C
This command has a test suite (run C
If you want to chat about the C
=head1 Notes
=over
=item * Works on POSIX systems: Linux, BSD, OSX, etc.
=item * Works on various Windows environments. See "Windows" section above.
=item * The C
=item * Written in (very modern) Bash, with full test suite. Take a look.
=item * A C<.gitrepo> file never is in the top level dir (next to a C<.git/> dir).
=back
=head1 Authors
=over
=item * Ingy döt Net ingy@ingy.net
=item * Magnus Carlsson grimmymail@gmail.com
=item * Austin Morgan admorgan@morgancomputers.net
=back
=head1 License and Copyright
The MIT License (MIT)
Copyright (c) 2013-2020 Ingy döt Net
=cut