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@xxxxxxxxx> --- 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@xxxxxxxxx> --- 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< -- -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html