Re: [PATCHv6] clone --single: limit the fetch refspec to fetched branch

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

Ralf Thielow <ralf.thielow@gmail.com> writes:

> After running "git clone --single", the resulting repository has the
> usual default "+refs/heads/*:refs/remotes/origin/*" wildcard fetch
> refspec installed, which means that a subsequent "git fetch" will
> end up grabbing all the other branches.
>
> Update the fetch refspec to cover only the singly cloned ref instead
> to correct this.
>
> That means:
> If "--single" is used without "--branch" or "--mirror", the
> fetch refspec covers the branch on which remote's HEAD points to.
> If "--single" is used with "--branch", it'll cover only the branch
> specified in the "--branch" option.
> If "--single" is combined with "--mirror", then it'll cover all
> refs of the cloned repository.
> If "--single" is used with "--branch" that specifies a tag, then
> it'll cover only the ref for this tag.
>
> Signed-off-by: Ralf Thielow <ralf.thielow@gmail.com>
> ---
>
> changes in v6
> - remove initial created tests (they tested in a too deep level)
> - add tests for "--mirror" option
> - add tests for the case of cloning a tag
> - update commit message
>
> I've tried to update "Documentation/git-clone.txt", but I don't
> know in which way this patch changes already described behaviour.
> The resulting refspec seems only be covered in the last part of
> the "--single-branch" section by describing "--no-single-branch",
> but this hasn't changed. Or did I miss something?

I do not think we are changing anything.  The whole "--single-branch"
was an half-baked afterthought hack that nobody anticipated the user
to later issue "git fetch" in the resulting repository, and everybody
involved in the series (the maintainer included) were just happy to
see the resulting code only transferred objects needed for the branch
without wasting bandwidth for objects needed for other branches, and
stopped thinking beyond that X-<.

If anything, we need to _add_ the description of what happens when
further fetches are done.  The second and the third paragraph in
the DESCRIPTION section talks only about the normal case, so at
least at the end of the second paragraph we should say "But if you
use --single-branch, all of this is different".  And what happens
when you do use --single-branch should be described in the part that
describes that option, e.g.

 Documentation/git-clone.txt | 15 ++++++++++++---
 1 file changed, 12 insertions(+), 3 deletions(-)

diff --git c/Documentation/git-clone.txt w/Documentation/git-clone.txt
index c1ddd4c..f59bc49 100644
--- c/Documentation/git-clone.txt
+++ w/Documentation/git-clone.txt
@@ -29,7 +29,8 @@ currently active branch.
 After the clone, a plain `git fetch` without arguments will update
 all the remote-tracking branches, and a `git pull` without
 arguments will in addition merge the remote master branch into the
-current master branch, if any.
+current master branch, if any (this is untrue when "--single-branch"
+is given; see below).
 
 This default configuration is achieved by creating references to
 the remote branch heads under `refs/remotes/origin` and
@@ -152,9 +153,11 @@ objects from the source repository into a pack in the cloned repository.
 -b <name>::
 	Instead of pointing the newly created HEAD to the branch pointed
 	to by the cloned repository's HEAD, point to `<name>` branch
-	instead. `--branch` can also take tags and treat them like
-	detached HEAD. In a non-bare repository, this is the branch
+	instead. In a non-bare repository, this is the branch
 	that will be checked out.
++
+`--branch` can also take tags and detaches the HEAD
+at that commit in the resulting repository. 
 
 --upload-pack <upload-pack>::
 -u <upload-pack>::
@@ -193,6 +196,12 @@ objects from the source repository into a pack in the cloned repository.
 	clone with the `--depth` option, this is the default, unless
 	`--no-single-branch` is given to fetch the histories near the
 	tips of all branches.
++
+Further fetches into the resulting repository will only update the
+remote tracking branch for the branch this option was used for the
+initial cloning.  If the HEAD at the remote did not point at any
+branch when `--single-branch` clone was made, no remote tracking
+branch is created.
 
 --recursive::
 --recurse-submodules::