Name

git-subrepo - Git Submodule Alternative

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 merge-base <branch1> <branch2>

git subrepo status [<subdir>]
git subrepo clean <subdir>

git subrepo help [<command>]
git subrepo version

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.

Benefits

This command is an improvement from git-submodule and git-subtree; two other git commands with similar goals, but various problems.

It assumes there are 3 main roles of people interacting with a repo, and attempts to serve them all well:

owner - The person who authors/owns/maintains a repo.
users - People who are just using/installing the repo.
collaborators - People who commit code to the repo and subrepos.

The git-subrepo command benefits these roles in the following ways:

Simple and intuitive commandline usage.
Users get your repo and all your subrepos just by cloning your repo.
Users do not need to install git-subrepo, ever.
Collaborators do not need to install unless they want to push/pull.
Collaborators know when a subdir is a subrepo (it has a .gitrepo file).
Well named branches and remotes are generated for manual operations.
Owners do not deal with the complications of keeping submodules in sync.
Subrepo repositories can contain subrepos themselves.
Branching with subrepos JustWorksâ„¢.
Different branches can have different subrepos in different states, etc.
Moving/renaming/deleting a subrepo subdir JustWorksâ„¢.
You can init an existing subdirectory into a subrepo.
Your git history is kept squeaky clean.
Upstream history (clone/pull) is condensed into a single commit.
You can see the subrepo history with git log subrepo/<subdir>/fetch.
Commits pushed back upstream are not condensed.
Trivial to try any subrepo operations and then reset back.
No configuration required.
Does not introduce history that messes up other git commands.
Fixes known rebase failures with git-subtree.

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.

Commands

All the subrepo 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.

Please note that the commands are not exact equivalents, and do not take all the same arguments. Keep readingâ€¦

git subrepo clone <repository> [<subdir>] [-b <upstream-branch>] [-f]

Add a repository as a subrepo in a subdir of your repository.

This is similar in feel to git clone. 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.

The subrepo history is squashed into a single commit that contains the reference information. This information is also stored in a special file called <subdir>/.gitrepo. The presence of this file indicates that the directory is a subrepo.

All subsequent commands refer to the subrepo by the name of the subdir. From the subdir, all the current information about the subrepo can be obtained.

The --force option will "reclone" (completely replace) an existing subdir.

The clone command accepts the --branch= and --force options.

git subrepo init <subdir> [-r <remote>] [-b <branch>]

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 <subdir>/.gitrepo file.

If you specify the --remote (and optionally the --branch) option, the values will be added to the <subdir>/.gitrepo file. The --remote option is the upstream URL, and the --branch option is the upstream branch to push to. These values will be needed to do a git subrepo push command, but they can be provided later on the push command (and saved to <subdir>/.gitrepo if you also specify the --update option).

Note: You will need to create the empty upstream repo and push to it on your own, using git subrepo push <subdir>.

The init command accepts the --branch= and --remote= options.

git subrepo pull <subdir>|--all [-b <branch>] [-r <remote>] [-u]

Update the subrepo subdir with the latest upstream changes.

The pull command will attempt to do the following commands in one go:

git subrepo fetch <subdir>
git subrepo branch <subdir>
git subrepo merge-base subrepo/<subdir>/fetch subrepo/<subdir>
git rebase --onto <new_parent> <old_parent> subrepo/<subdir>
git rebase subrepo/<subdir>/fetch subrepo/<subdir>
git checkout ORIG_HEAD
git subrepo commit <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 rebase, 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.

Like the clone command, pull 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 git log command:

git log refs/subrepo/<subdir>/fetch

The set of commands used above are described in detail below.

The pull command accepts the --all, --branch=, --remote= and -- update options.

git subrepo push <subdir>|--all [<branch>] [-r <remote>] [-b <branch>] [-u]

Push a properly merged subrepo branch back upstream.

The push 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 push after an init). That means the upstream HEAD is one of the commits in the branch. If you don't specify a branch to push, one will be created for you using the same techniques as a pull (except it won't be committed locally). Otherwise you can name a properly merged branch to push. Often times you can use the branch commit from the last pull, which is saved as refs/subrepo/<subdir>/pull.

After that, the push command just checks that the branch contains the upstream HEAD and then pushes it upstream.

The --force option will do a force push. Force pushes are typically discouraged. Only use this option if you fully understand it. (The --force option will NOT check for a proper merge. ANY branch will be force pushed!)

The push command accepts the --all, --branch=, --force, -- remote= and --update options.

git subrepo fetch <subdir>|--all

Fetch the remote/upstream content for a subrepo.

It will create a Git reference called subrepo/<subdir>/fetch that points at the same commit as FETCH_HEAD. It will also create a remote called subrepo/<subdir>. These are temporary and you can remove them easily with the subrepo clean command.

The fetch command accepts the --all, --branch= and -- remote= options.

git subrepo branch <subdir>|--all

Create a branch with local subrepo commits.

Scan the history of the mainline for all the commits that affect the subdir and create a new branch from them called subrepo/<subdir>.

This is useful for doing pull and push commands by hand.

Use the --force option to write over an existing subrepo/<subdir> branch.

The branch command accepts the --all and --force options.

git subrepo commit <subdir> [<subrepo-ref>]

Add subrepo branch to current history as a single commit.

This command is generally used after a hand-merge. You have done a subrepo branch 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.

This command requires that the upstream HEAD be in the subrepo/<subdir> branch history. That way the same branch can push upstream. Use the --force option to commit anyway.

The commit command accepts the --force option.

git subrepo merge-base <branch1> <branch2>

This "plumbing" command finds a common ancestor between two branches. It will look at the referenced tree hash in the commits to see if it can locate a common one.

This is used for pull and push before the rebase step. In this case we look at all the local commits and then try to find a tree hash that is available in the subrepo.

Note: This is different from the git merge-base command which looks at the object structure.

Use the --all option to list all possible common ancestors. (This differs from other commands which use --all to apply the same command to all subrepos).

The merge-base command accepts the --all option.

git subrepo status [<subdir>]

Get the status of a subrepo. Uses the --all option by default. If the -- quiet flag is used, just print the subrepo names, one per line.

The --verbose option will show all the recent local and upstream commits.

The status command accepts the --ALL, --all, and --fetch option.

git subrepo clean <subdir>|--ALL|--all

Remove artifacts created by fetch and branch commands.

The fetch and branch operations (and other commands that call them) create temporary things like refs, branches and remotes. This command removes all those things.

Use --force to remove refs. Refs are not removed by default because they are sometimes needed between commands. To remove all subrepo artifacts:

git subrepo clean --all --force

The clean command accepts the --ALL, --all, and --force options.

git subrepo help

Same as git help subrepo. Will launch the manpage. For the shorter usage, use git subrepo -h.

git subrepo version [--verbose] [--quiet]

This command will display version information about git-subrepo and its environment. For just the version number, use git subrepo --version. Use --verbose for more version info, and --quiet for less.

Command Options

-h: Show a brief view of the commands and options.
--help: Gives an overview of the help options available for the subrepo command.
--version: Print the git-subrepo version. Just the version number. Try the version command for more version info.
--all (-a): If you have multiple subrepos, issue the command to all of them (if applicable).
--ALL (-A): If you have subrepos that also have subrepos themselves, issue the command to ALL of them. Note that the --ALL option only works for a subset of the commands that --all works for.
--branch=<branch-name> (-b <branch-name>): Use a different branch-name than the remote HEAD or the one saved in .gitrepo locally.
--force (-f): Use this option to force certain commands that fail in the general case.
--fetch (-F): Use this option to fetch the upstream commits, before running the command.
--remote=<remote-url> (-r <remote-url>): Use a different remote-url than the one saved in .gitrepo locally.
--update (-u): If -b or -r are used, and the command updates the .gitrepo file, include these values to the update.

Output Options

--quiet (-q): Print as little info as possible. Applicable to most commands.
--verbose (-v): Print more information about the command execution and results. Applicable to most commands.
--debug (-d): Show the actual git (and other) commands being executed under the hood. Applicable to most commands.
--DEBUG (-x): Use the Bash set -x option which prints every command before it is run. VERY noisy, but extremely useful in deep debugging. Applicable to all commands.

Environment Variables

The git-subrepo command exports and honors some environment variables:

GIT_SUBREPO_ROOT: This is set by the .rc file, if you use that method to install / enable git- subrepo. It contains the path of the git-subrepo repository.
GIT_SUBREPO_RUNNING: This variable is exported when git-subrepo is running. It is set to the pid of the git-subrepo process that is running. Other processes, like git hooks for instance, can use this information to adjust accordingly.
GIT_SUBREPO_COMMAND: This variable is exported when git-subrepo is running. It is set to the name of the git-subrepo subcommand that is running.
GIT_SUBREPO_PAGER: Use this to specify the pager to use for long output commands. Defaults to $PAGER or less.
GIT_SUBREPO_QUIET: Set this for quiet (-q) output.
GIT_SUBREPO_VERBOSE: Set this for verbose (-v) output.
GIT_SUBREPO_DEBUG: Set this for really debugging (-d) output.

Installation Instructions

There are currently 3 ways to install git-subrepo. For all of them you need to get the source code from GitHub:

git clone https://github.com/ingydotnet/git-subrepo /path/to/git-subrepo

The first installation method is preferred: source the .rc file. Just add a line like this one to your shell startup script:

source /path/to/git-subrepo/.rc

That will modify your PATH and MANPATH, and also enable command completion.

The second method is to do these things by hand. This might afford you more control of your shell environment. Simply add the lib and man directories to your PATH and MANPATH:

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 git-subrepo next to your other git commands:

make install        # Possibly with 'sudo'

This method does not account for upgrading and command completion yet.

Windows

This command is known to work in these Windows environments:

Git for Windows -- https://git-for-windows.github.io/
Babun -- http://babun.github.io/
Cygwin -- https://www.cygwin.com/

Let us know if there are others that it works (or doesn't work) in.

Testing

The git-subrepo repository comes with a extensive test suite. You can run it with:

make test

or if you don't have make on your system:

prove -v test

Upgrading

If you used the PATH method of installation, just run this to upgrade git-subrepo:

git subrepo upgrade

Or (same thing):

cd /path/to/git-subrepo
git pull

If you used make install method, then run this again (after git pull):

make install        # Possibly with 'sudo'

Command Completion

The git subrepo command supports <TAB>-based command completion. If you don't use the .rc script (see Installation, above), you'll need to enable this manually to use it.

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):

/etc/bash_completion.d/git
/usr/share/bash-completion/git
/usr/share/bash-completion/completions/git
/opt/local/share/bash-completion/completions/git
/usr/local/etc/bash_completion.d/git
~/.homebrew/etc/bash_completion.d/git

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 git-subrepo completion with a command like this:

source /path/to/git-subrepo/share/completion.bash

In zsh

In the Z shell (zsh), you can manually enable git-subrepo completion by adding the following line to your ~/.zshrc, before the compinit function is called:

fpath=('/path/to/git-subrepo/share/zsh-completion' $fpath)

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.

Trying subrepo out is simple and painless (this is not git submodule). 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.

This command has a test suite (run make test), 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.

If you want to chat about the git-subrepo command, join #gitcommands on irc.freenode.net.

Notes

Works on POSIX systems: Linux, BSD, OSX, etc.
Works on various Windows environments. See "Windows" section above.
The git-subrepo repo itself has 2 subrepos under the ext/ subdirectory.
Written in (very modern) Bash, with full test suite. Take a look.
A .gitrepo file never is in the top level dir (next to a .git/ dir).

Author

Written by Ingy döt Net <ingy@ingy.net>

License and Copyright

The MIT License (MIT)

mickael-guene / git-subrepo