git-subrepo

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 config <subdir> git subrepo status [<subdir>] git subrepo clean <subdir> git subrepo help [<command> | --all] git subrepo version git subrepo upgrade 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 (with tab completion). 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). The .gitrepo file never gets pushed back to the subrepo upstream. 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. Pulls can use a merge, rebase or force strategies. You can see the subrepo history with git log subrepo/<subdir>/fetch. Commits pushed back upstream are not condensed (by default). 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. Note: git-subrepo needs a git version >= 2.23) due to changes in --is-ancestor. 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 <branch>] [-f] [-m <msg>] [--file=<msg file>] [-e] [--method <merge|rebase>] 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 --method option will decide how the join process between branches are performed. The default option is merge. The clone command accepts the --branch= --edit, --file, --force and --message= options. git subrepo init <subdir> [-r <remote>] [-b <branch>] [--method <merge|rebase>] 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 --method option will decide how the join process between branches are performed. The default option is merge. The init command accepts the --branch= and --remote= options. 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. The pull command fetches the latest content from the remote branch pointed to by the subrepo's .gitrepo 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 .gitrepo file is updated and a single 'pull' commit is added to yo