builtin/clone: teach git-clone(1) the --revision= option

The git-clone(1) command has the option --branch that allows the user to select the branch they want HEAD to point to. In a non-bare repository this also checks out that branch.

Option --branch also accepts a tag. When a tag name is provided, the commit this tag points to is checked out and HEAD is detached. Thus --branch can be used to clone a repository and check out a ref kept under refs/heads or refs/tags. But some other refs might be in use as well. For example Git forges might use refs like refs/pull/<id> and refs/merge-requests/<id> to track pull/merge requests. These refs cannot selected upon git-clone(1).

Add option --revision to git-clone(1). This option accepts a fully qualified reference, or a raw commit hash. This enables the user to clone and checkout any revision they want. --revision can be used in conjunction with --depth to do a minimal clone that only contains the sources for a single revision. This can be useful for automated tests.

This type of shallow clone could also be achieved with the following set of commands:

git init the-repo
cd ./the-repo
git remote add origin <url>
git fetch --depth=1 origin <commit-id>
git checkout <commit-id>

Unfortunately, this approach uses git-fetch(1) instead of git-clone(1), and only on git-clone(1) the bundle URIs advertised by the server are used. By adding this option --revision to git-clone(1) allows us to get the same end result, while benefiting from bundle URIs if advertised by the server.

Issue: #371 (closed)