Re: [PATCHv2 1/8] Doc: Bundle file usage

[Junio C Hamano <gitster@pobox.com>]

Philip Oakley <philipoakley@iee.org> writes:

> Git URLs can accept bundle files for fetch, pull and clone, include
> in that section. Include git clone in the bundle usage description.
> Correct the quoting of <git-rev-list-args>.
> Detail the <git-rev-list-args> '--all' option for cloning.
>
> Signed-off-by: Philip Oakley <philipoakley@iee.org>
>
> diff --git a/Documentation/git-bundle.txt b/Documentation/git-bundle.txt
> index 16a6b0a..be6a5f1 100644
> --- a/Documentation/git-bundle.txt
> +++ b/Documentation/git-bundle.txt
> @@ -21,12 +21,12 @@ Some workflows require that one or more branches of development on one
>  machine be replicated on another machine, but the two machines cannot
>  be directly connected, and therefore the interactive git protocols (git,
>  ssh, rsync, http) cannot be used.  This command provides support for
> -'git fetch' and 'git pull' to operate by packaging objects and references
> -in an archive at the originating machine, then importing those into
> -another repository using 'git fetch' and 'git pull'
> -after moving the archive by some means (e.g., by sneakernet).  As no
> -direct connection between the repositories exists, the user must specify a
> -basis for the bundle that is held by the destination repository: the
> +'git fetch', 'git pull' and 'git clone', to operate by packaging
> +objects and references in an archive at the originating machine, then
> +importing those into another repository using 'git fetch', 'git pull',
> +or 'git clone', after moving the archive by some means (e.g., by sneakernet).
> +As no direct connection between the repositories exists, the user must
> +specify a basis for the bundle that is held by the destination repository: the
>  bundle assumes that all objects in the basis are already in the
>  destination repository.
>  
> @@ -35,7 +35,7 @@ OPTIONS
>  
>  create <file>::
>  	Used to create a bundle named 'file'.  This requires the
> -	'git-rev-list-args' arguments to define the bundle contents.
> +	<git-rev-list-args> arguments to define the bundle contents.
>  
>  verify <file>::
>  	Used to check that a bundle file is valid and will apply
> @@ -92,6 +92,8 @@ It is okay to err on the side of caution, causing the bundle file
>  to contain objects already in the destination, as these are ignored
>  when unpacking at the destination.
>  
> +To create a bundle for 'git clone', use `--all` for the <git-rev-list-args>.
> +

Hmm, what does this mean?  Specifically, it is not clear what "for
'git clone'" exactly means.  It is not "for use of 'git clone'",
because you should be able to create a bundle that has 'master'
branch without 'maint', 'next', and 'pu' and clone from it, no?

	git checkout maint
        git bundle create /var/tmp/1.bndl HEAD refs/heads/maint
        cd /var/tmp && git clone 1.bndl xprm

I also think "--all" is a bad advice for another reason.  Doesn't it
shove refs from refs/remotes/* hierarchy in the resulting bundle?
It is fine for archiving purposes, but it does not seem to be a good
advice to create a bundle to clone from.

>  EXAMPLE
>  -------
>  
> diff --git a/Documentation/urls.txt b/Documentation/urls.txt
> index 2890194..2d75cce 100644
> --- a/Documentation/urls.txt
> +++ b/Documentation/urls.txt
> @@ -42,6 +42,9 @@ These two syntaxes are mostly equivalent, except the former implies
>  --local option.
>  endif::git-clone[]
>  
> +'git clone', 'git fetch' and 'git pull', but not 'git push', will also
> +accept a suitable bundle file. See linkgit:git-bundle[1].
> +
>  When git doesn't know how to handle a certain transport protocol, it
>  attempts to use the 'remote-<transport>' remote helper, if one
>  exists. To explicitly request a remote helper, the following syntax