=pod =for comment DO NOT EDIT. This Pod was generated by Swim v0.1.38. See http://github.com/ingydotnet/swim-pm#readme =encoding utf8 =head1 Name git-subrepo(1) - Git Submodule Alternative =for html <a href="https://travis-ci.org/ingydotnet/git-subrepo"><img src="https://travis-ci.org/ingydotnet/git-subrepo.png" alt="git-subrepo"></a> =head1 Synopsis git subrepo -h # Help Overview git subrepo clone <remote-url> [<subdir>] git subrepo pull <subdir> git subrepo push <subdir> git subrepo fetch <subdir> git subrepo branch <subdir> git subrepo commit <subdir> git subrepo status [<subdir>] git subrepo clean <subdir> git subrepo help [<command>] git subrepo version =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<git-submodule> and C<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: =over =item * B<owner> - The person who authorsI<owns>maintains a repo. =item * B<users> - People who are just using/installing the repo. =item * B<collaborators> - People who commit code to the repo and subrepos. =back The C<git-subrepo> command benefits these roles in the following ways: =over =item * Simple and intuitive commandline usage. =item * Users get your repo and all your subrepos just by cloning your repo. =item * Users do not need to install C<git-subrepo>, ever. =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 * 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 * MovingI<renaming>deleting a subrepo subdir JustWorks™. =item * Your git history is kept squeaky clean. =item * Upstream history (clone/pull) is condensed into a single commit. =item * You can see the subrepo history with C<< git log subrepo/<subdir>/upstream >>. =item * Commits pushed back upstream are B<not> condensed. =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<git-subtree>. =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/init' >> ~/.bashrc The complete "Installation Instructions" can be found below. =head1 Commands All the B<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 I<not> exact equivalents, and do not take all the same arguments. Keep reading… =over =item C<< 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 C<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 I<squashed> into a single commit that contains the reference information. This information is also stored in a special file called C<< <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 I<subdir>. From the subdir, all the current information about the subrepo can be obtained. The C<--force> option will "reclone" (completely replace) an existing subdir. The C<clone> command accepts the C<--branch=> and C<--force> options. =item C<< git subrepo pull <subdir>|--all [-b <branch>] [-r <remote>] [-u] >> Update the subrepo subdir with the latest upstream changes. The C<pull> command will attempt to do the following commands in one go: git subrepo fetch <subdir> git subrepo branch <subdir> git rebase subrepo/<subdir>{/upstream,} 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 C<clone> command, C<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 C<git log> command: git log refs/subrepo/<subdir>/upstream The set of commands used above are described in detail below. The C<pull> command accepts the C<--all>, C<--branch=>, C<--remote=> and C<-- update> options. =item C<< git subrepo push <subdir>|--all [<branch>] [-r <remote>] [-b <branch>] >> Push a properly merged subrepo branch back upstream. The C<push> command requires a branch that has been properly merged/rebased with the upstream HEAD. 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. Often times you can use the branch commit from the last pull, which is saved as C<< refs/subrepo/<subdir>/pull >>. After that, the C<push> command just checks that the branch contains the upstream HEAD and then pushes it upstream. 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<push> command accepts the C<--all>, C<--branch=>, C<--force>, C<-- remote=> and C<--update> options. =item C<< git subrepo fetch <subdir>|--all >> Fetch the remote/upstream content for a subrepo. It will create a Git reference called C<< subrepo/<subdir>/upstream >> that points at the same commit as C<FETCH_HEAD>. It will also create a remote called C<< subrepo/<subdir> >>. These are temporary and you can remove them easily with the subrepo C<clean> command. The C<fetch> command accepts the C<--all>, C<--branch=> and C<-- remote=> options. =item C<< git subrepo branch <subdir>|--all >> Create a branch with local subrepo commits since last pull. Scan the history of the mainline for all the commits that affect the C<subdir> (since the last subrepo pull or clone) and create a new branch from them called C<< subrepo/<subdir> >>. This is useful for doing C<pull> and C<push> commands by hand. Use the C<--force> option to write over an existing C<< subrepo/<subdir> >> branch. Note: if no commits have been made to the subdir since the last C<pull>/C<clone> then the C<branch> command will fail. The C<branch> command accepts the C<--all> and C<--force> options. =item C<< 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 C<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 C<< subrepo/<subdir> >> branch history. That way the same branch can push upstream. Use the C<--force> option to commit anyway. The C<commit> command accepts the C<--force> option. =item C<< git subrepo status [<subdir>] >> Get the status of a subrepo. Show the status of all subrepos 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. The C<status> command accepts the C<--fetch> option. =item C<< git subrepo clean <subdir>|--all >> Remove artifacts created by C<fetch> and C<branch> commands. The C<fetch> and C<branch> operations (and other commands that call them) create temporary things like refs, branches and remotes. This command removes all those things. Use C<--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 C<clean> command takes the C<--all> and C<--force> options. =item C<git subrepo help> Same as C<git help subrepo>. Will launch the manpage. For the shorter usage, use C<git subrepo -h>. =item C<git subrepo version [--verbose] [--quiet]> 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. =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<version> command for more version info. =item C<--all> (C<-a>) If you have multiple subrepos, issue the command to all of them (if applicable). =item C<< --branch=<branch-name> >> (C<< -b <branch-name> >>) Use a different branch-name than the remote HEAD or the one saved in C<.gitrepo> locally. =item C<--force> (C<-f>) Use this option to force certain commands that fail in the general case. =item C<--fetch> (C<-F>) Use this option to fetch the upstream commits, before running the command. =item C<< --remote=<remote-url> >> (C<< -r <remote-url> >>) Use a different remote-url than the one saved in C<.gitrepo> locally. =item C<--update> (C<-u>) If C<-b> or C<-r> 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 Installation Instructions There are currently 3 ways to install C<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: C<source> the C<init> file. Just add a line like this one to your shell startup script: source /path/to/git-subrepo/init That will modify your C<PATH> and C<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 C<lib> and C<man> directories to your C<PATH> and C<MANPATH>: 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<git-subrepo> next to your other git commands: make install # Possibly with 'sudo' This method does not account for upgrading and command completion yet. =head1 Upgrading If you used the C<PATH> method of installation, just run this to upgrade C<git-subrepo>: git subrepo upgrade Or (same thing): cd /path/to/git-subrepo git pull If you used C<make install> method, then run this again (after C<git pull>): make install # Possibly with 'sudo' =head1 Command Completion The C<git subrepo> command supports C<< <TAB> >>-based command completion. If you don't use the C<init> script (see Installation, above), you'll need to enable this manually to use it. =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<git-subrepo> completion with a command like this: source /path/to/git-subrepo/share/completion.bash =head2 In zsh In the Z shell (zsh), you can manually enable C<git-subrepo> completion by adding the following line to your C<~/.zshrc>, B<before> the C<compinit> function is called: fpath=('/path/to/git-subrepo/share/zsh-completion' $fpath) =head1 Status The git-subrepo command is coming together nicely, but some details are still being ironed out. I would not use it for important things yet, but playing around with it is cheap (this is not C<git submodule>), and not permanent (if you do not push to public remotes). ie You can always play around and reset back to the beginning without pain. This command has a test suite (run C<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 C<git-subrepo> command, join C<#git-commands> on C<irc.freenode.net>. =head1 Notes =over =item * This command currently only works on POSIX systems. =item * The C<git-subrepo> repo itself has 2 subrepos under the C<ext/> subdirectory. =item * Written in (very modern) Bash, with full test suite. Take a look. =back =head1 Author Written by Ingy döt Net <ingy@ingy.net> =head1 License and Copyright The MIT License (MIT) Copyright (c) 2013-2015 Ingy döt Net =cut