The Most Helpful Repo Command for Android Development

Article has been moved to my blog at OhYongHao.com
I must lament for a bit what I see to be a great lack of foresight when dealing with Android.  From the official documentation to any site that I have tried to visit there seems to be one thing which is not discussed.  There is an unwritten rule taken nearly religiously: Those that use 'repo' don't talk about 'repo'.

Repo is this all powerful super tool built on top of git, another all powerful super tool, which allows for the concurrent management of multiple projects that are used to form one super project.  There is just one catch, nothing but the most simplistic of usage examples are available.

As it turns out the entire documentation is hidden in the program itself.  As not to be too obvious, when you type the standard 'repo --help' you get a fairly unuseful help message:

Usage: repo [-p|--paginate|--no-pager] COMMAND [ARGS]
Options:
  -h, --help      show this help message and exit
  -p, --paginate  display command output in the pager
  --no-pager      disable the pager
  --trace         trace git command execution
  --time          time repo command execution
  --version       display this version of repo

Nothing in here is very useful.  What are the available commands that are referred to here?  Nothing there would point you to the most helpful repo command.  Try typing 'repo help', note the missing double dash, and here is what you get:

usage: repo COMMAND [ARGS]
The most commonly used repo commands are:
  abandon            Permanently abandon a development branch
  branch             View current topic branches
  branches           View current topic branches
  checkout           Checkout a branch for development
  checkout-manifest  for every project in a manifest tag file check out the sha1 listed in the file
  cherry-pick        Cherry-pick a change.
  diff               Show changes between commit and working tree
  download           Download and checkout a change
  format-patch       build patch sets for each project common to a manifest baseline
  grep               Print lines matching a pattern
  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
  push               Push the local branch
  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
  tag-manifest       for every project in a manifest tag use the sha1 listed in the file set the tagname to it
  upload             Upload changes for code review
See 'repo help ' for more information on a specific command.
See 'repo help --all' for a complete list of recognized commands.

Wait, what is this?  A list of every nearly every command available along with useful information at the end telling you how to find EVERY command that repo uses?  Why the bloody hell was this not put in the first help message?  Was it too troublesome to add a line at the end like "See 'repo help' for a list of commands."?  Even the official documentation, at most, lists using 'repo help COMMAND' but gives no indication that leaving off 'COMMAND' would then show you all the possible commands.

Hopefully someone finds this post useful, I know it has taken me a long time to find this bit of information, I now put it out here in hope that others aren't as lost as I was for so long.  I will now be perusing and learning more about this powerful tool.