===== Overview =====

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

  * [[https://www.automotivelinux.org/|AGL home page]]
    * [[https://wiki.automotivelinux.org/start|AGL wiki]]

===== TO DO =====

  * Discuss cloning just manifest repo.

===== Commands =====

==== repo help ====

<code>
  abandon        Permanently abandon a development branch
  branch         View current topic branches
  branches       View current topic branches
  checkout       Checkout a branch for development
  cherry-pick    Cherry-pick a change.
  diff           Show changes between commit and working tree
  diffmanifests  Manifest diff utility
  download       Download and checkout a change
  gitc-delete    Delete a GITC Client.
  gitc-init      Initialize a GITC Client.
  grep           Print lines matching a pattern
  info           Get info on the manifest branch, current branch or unmerged branches
  init           Initialize repo in the current directory
  list           List projects and their associated directories
  overview       Display overview of unmerged project branches
  prune          Prune (delete) already merged topics
  rebase         Rebase local branches on upstream branch
  smartsync      Update working tree to the latest known good revision
  stage          Stage file(s) for commit
  start          Start a new branch for development
  status         Show the working tree status
  sync           Update working tree to the latest revision
  upload         Upload changes for code review
</code>



===== The two versions of "repo" =====

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.

===== Installing "repo" launcher tool =====

As explained above, install the launcher tool version of ''repo'' in any directory that is on your search path, such as:

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

Once again, this is not the full version of the command; its job is to simply initialize new repositories when you run ''repo init'', then in each of those repositories install the //full// version of the command, which will be used from then on.

===== Initializing a repo repository =====

After creating a new directory:

<code>
$ mkdir agl_dir
$ cd agl_dir
</code>

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

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

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:

<code>
$ ls -AF
.repo/
$
</code>

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:

<code>
$ 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*
</code>