This is a tutorial on how to use Google's repo version control tool, as many people seem to have trouble getting a handle on its proper operation, and most of the documentation doesn't seem all that helpful in terms of clarification. For this tutorial, we'll be using AGL (Automotive Grade Linux) as an example.

Links for AGL

• AGL home page
  • AGL wiki

Perhaps the most confusing property of repo is that there are, conceptually, two types of repo command.

The first kind of repo is not the full command; rather, it is a simplified version called the tool launcher; this is the single-executable command you download initially, and make sure is part of your search path so that when you invoke repo, that is the command that is located and executed. It's common to install that in your personal ~/bin directory, which is almost always already part of your search path.

Once you start working with repo and start initializing repositories, each and every repository will, as part of being initialized, have installed within it the full version of repo, which supports all of the subcommands. However, even as you're working with repo, you always, always, always invoke the initial tool launcher which, as soon as it realizes it's being run in the context of an actual repository, will hand off control to that repo's full version.

In other words, even though every single repo repository you initialize gets its own copy of the full version of the command, you should never run that full version directly – you always invoke the simpler, tool launcher version, which will take it from there.

Install the repo launcher tool in your personal ~/bin directory:

$ curl https://storage.googleapis.com/git-repo-downloads/repo > ~/bin/repo
$ chmod +x ~/bin/repo

Note well that this is not the repo command itself; rather, it is the launcher tool that will, every time you initialize a new repo directory, copy the actual repo command into that new directory.

Do not confuse these two things; that is a common misunderstanding.

After creating a new directory:

$ mkdir repo_dir
$ cd repo_dir

initialize a new (in this case, AGL) repo directory:

$ repo init -u https://gerrit.automotivelinux.org/gerrit/AGL/AGL-repo

and note carefully what that accomplished.

The repo command you ran in the above command was the launcher tool in your home directory, and the end result is to populate your current directory with, well:

$ ls -AF
.repo/
$

If you examine that .repo directory, you'll see simply manifest files and directories for AGL, as well as a repo directory which contains, among other things, the repo command that will be used for subsequent operations:

$ ls -F repo
color.py        git_config.py  MANIFEST.in              __pycache__/   setup.py*
command.py      gitc_utils.py  manifest_xml.py          pyversion.py   subcmds/
docs/           git_refs.py    pager.py                 README.md      SUBMITTING_PATCHES.md
editor.py       git_ssh*       platform_utils.py        release/       tests/
error.py        hooks/         platform_utils_win32.py  repo*          tox.ini
event_log.py    LICENSE        progress.py              repo_trace.py  wrapper.py
git_command.py  main.py*       project.py               run_tests*