Re: git clone --depth: shallow clone problems

[Duy Nguyen <pclouds@gmail.com>]

On Thu, Apr 23, 2015 at 04:53:04PM +0200, Michal Pomorski wrote:
> tl: skip to the second paragraph
> 
> So here is what I just experienced:
> We had an emergency error in an application at work and as the
> responsible developer was unavailable, I was asked to check it out and
> look into it.
> We are a small branch of a bigger company and our connection to the
> company's source servers is really slow, so just to quickly start it
> up, I decided to take a shallow clone (that's what it is for, right?).
> After a while we realized, the clone I have made was not sufficient
> and was missing some newest work done on the project.
> I did "git fetch --unshallow" which finished surprisingly quickly, and
> it did not bring any newer commits.
> Unaware of the fine print hiding in the documentation of git clone, I
> blamed the repo (and in extension the person who provided me the
> address to it). After coming to a realization, a process which cost me
> time and embarrassment, I understood what is supposed to be the
> "correct" behaviour:
> "--single-branch
> Clone only the history leading to the tip of a single branch, either
> specified by the --branch option or the primary branch remote's HEAD
> points at. When creating a shallow 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."
> Of course, the new commits were put on a custom branch, and I knew
> that all the time, but I expected the branch to show up eventually, at
> least after git fetch --unshallow.
> 
>
> I hope you can see the faults in the usability of the commands I was
> exposed to:
> 1) git clone --depth  should:
>    -warn about only fetching the current HEAD (name it by a real name
> if applicable)
> and/or
>    -require the --branch option so that it is not left to chance
> (current HEAD could be anything; is it really meaningful to talk about
> the current HEAD on a server?)
> and/or
>    -make the --no-single-branch the default...
> and maybe
>    -have the option to clone the most recent commits.

--single-branch being the default was because we (at least I, stilll)
believed it was the common case, so I don't think we should revert
it. But I can see --unshallow documentation is misleading. How about
this? I think it's better than what we have.

-- 8< --
Subject: [PATCH] fetch-options.txt: clarify what --unshallow does

Signed-off-by: Nguyễn Thái Ngọc Duy <pclouds@gmail.com>
---
 Documentation/fetch-options.txt | 11 ++++++++---
 1 file changed, 8 insertions(+), 3 deletions(-)

diff --git a/Documentation/fetch-options.txt b/Documentation/fetch-options.txt
index 45583d8..63d3452 100644
--- a/Documentation/fetch-options.txt
+++ b/Documentation/fetch-options.txt
@@ -14,12 +14,17 @@
 	branch history. Tags for the deepened commits are not fetched.
 
 --unshallow::
-	If the source repository is complete, convert a shallow
-	repository to a complete one, removing all the limitations
+	If the source repository is complete, convert all shallow
+	refs to complete ones, removing all the limitations
 	imposed by shallow repositories.
 +
 If the source repository is shallow, fetch as much as possible so that
-the current repository has the same history as the source repository.
+the all existing refs of current repository have the same history as in
+the source repository.
++
+Note that if the repository is created with --single-branch, which is
+default for a shallow clone, only one ref is completed. `--unshallow`
+does not fetch all remaining refs from source repository.
 
 --update-shallow::
 	By default when fetching from a shallow repository,
-- 
2.3.0.rc1.137.g477eb31
-- 8< --

> 2) git fetch --unshallow should convert the clone into an actual
> equivalent of a normal, not shallow clone.

I was thinking of some way to undo --single-branch too. I don't think
it should be the job of --unshallow, maybe a new option, but I can't
think of a name better than --really-unshallow :P

It's been a while and no one responds to this, perhaps people are not
interested in such an option?

> 3) The documentation should be improved. The behaviour of --shallow is
> described partly in the description of --no-single-branch. This is the
> documentation equivalent of the infamous "come from" control flow
> structure.

Yes. Like this?

-- 8< --
Subject: [PATCH] clone.txt: mention --single-branch in --depth

Signed-off-by: Nguyễn Thái Ngọc Duy <pclouds@gmail.com>
---
 Documentation/git-clone.txt | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/Documentation/git-clone.txt b/Documentation/git-clone.txt
index f1f2a3f..9c320da 100644
--- a/Documentation/git-clone.txt
+++ b/Documentation/git-clone.txt
@@ -185,7 +185,9 @@ objects from the source repository into a pack in the cloned repository.
 
 --depth <depth>::
 	Create a 'shallow' clone with a history truncated to the
-	specified number of revisions.
+	specified number of revisions. --single-branch is
+	automatically specified unless the user overrides it with
+	--no-single-branch
 
 --[no-]single-branch::
 	Clone only the history leading to the tip of a single branch,
-- 
2.3.0.rc1.137.g477eb31

-- 8< --