HowTo: Use Android 'repo' with a GitHub Repository

Android 'repo' documentation available? - Stack Overflow
Git Book - Submodules

Repo Documentation Problem: You don't  get the full repo command until you use repo to initialize a build tree that is described by a Manifest file, that is located in a URL to a Git repository -- You don't get documentation and help until you already know how to do everything you needed to know in the first place.

Git Partial Checkout Problem: You can't check out part of a source tree from Git as you can in SVN/CVS. Large projects are often composed of smaller, self-contained modules. In Git, you cannot checkout small pieces, it is all or nothing. So large Git projects must be divided into multiple smaller Git repositories that need to be pieced back together and kept in sync with each other. Git Submodule was created to checkout multiple Git Repositories into a single source tree.

Repo is a tool created by Google for Android to resolve Git Partial Checkout Problem. Repo allows you to checkout and update multiple Git repositories to a single build tree. Where Git Submodules require changes to a repository to define submodules, Repo does not require changes in any of the Git Repositories.

For a quick example, the LLVM.org project builds a C compiler by adding the CLANG and Compiler-RT projects. The manifest combines the git repo's into a build area.

# Repo stub in /usr/bin
[ -d "${HOME}/usr/bin" ] || mkdir -p ${HOME}/usr/bin
[ "$(grep ${HOME}/usr/bin <<< ${PATH})" ] || export PATH="${PATH}:${HOME}/usr/bin"
[ -f "${HOME}/usr/bin/repo" ] || wget --no-check-certificate https://github.com/downloads/rickfoosusa/manifest/repo -O ${HOME}/usr/bin/repo
chmod +x ${HOME}/usr/bin/repo
# repo creates a .repo directory each time.
mkdir -p llvm-repo
cd llvm-repo
repo init -u git://github.com/rickfoosusa/manifest.git -m llvm.xml
repo sync
make

In a read only use, Repo is easier than Git Submodules where you have to change one of the repositories to define the Submodules. So I might define a tree with everything read-only links, and one writeable to the Git repository that I am working with.

Both Repo and Git Submodules involve different ways to push changes back to external repositories than a single Git clone. There is no clear answer on which is better. All we are going to do here is to use Repo to check out build trees from multiple Git repositories.

If you just want to put together a build tree, develop one part of it keeping it all up to date, or QA a large build tree --  Repo is the answer.

The first step is to download the repo stub script, and place it in your path. The repo on your system is a stub which downloads the current version of Repo, and loads a Manifest file from a Git repository.

The standard repo stub for Android may not be available, or slow to download, or slow to update. Having a repo stub that downloads from a mirror site has proven to be better. The following repo stub downloads from 'git://codeaurora.org/tools/repo.git' from branch 'repo'.

At this point "repo help" points you to "repo help init" which says you need a URL to a manifest repository location. The URL points to a Git repository that contains a "default.xml" file that (nothing has told you this yet) describes the Git repositories making up a source tree. You can define your own manifests, but they need to be pushed to a Git repository before repo can use them.
I have found that it is nice to have one git repository called manifest.git, that contains several manifests. So "repo init" needs the -u option to the manifest.git repo, and the -n option for the name of the manifest.xml file.