Re: git clone --depth: shallow clone problems

[Duy Nguyen <pclouds@gmail.com>]

On Tue, May 26, 2015 at 9:54 PM, Junio C Hamano <gitster@pobox.com> wrote:
> Duy Nguyen <pclouds@gmail.com> writes:
>
>>  --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
>
> Define "shallow ref", or better yet explain without introducing such
> a new term (I do not think shallow-ness is a property of a ref, by
> the way---I think you meant all refs that can reach the points the
> history is cauterised by .git/shallow, but we shouldn't assume that
> the target audience of this paragraph to know Git as well as I do).

OK maybe

Make sure all existing refs have the same history as the ones from the
source repository. If the source repository is complete, this removes
all limitations imposed by shallow repositories.

?

>>       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.
>
> Makes sense, modulo "so that the all existing refs" sounds strange
> to my ears ("all the existing refs" perhaps).

Will fix. Although I think the new paragraph above already covers this case too.

>> ++
>> +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.
>
> I do not think this "Note" is being as helpful as it could be.
>
>  - If the repository was created with --single-branch but if the
>    user later fetched and started tracking other branches, the
>    statement "only one ref is completed" is untrue; the true version
>    is "only the existing refs are completed", which leads to a more
>    important point.  It says the same thing as "all existing refs"
>    above and does not add any useful information.
>
>  - The last sentence is less than useful but merely frustrating---it
>    says what you cannot do with this option, strongly hints that the
>    writer of the sentence knows what the reader wants to achieve,
>    but without saying what other way the reader go to achieve it.
>
> Perhaps replace that Note paragraph with something along this line?
>
>     +
>     By fetching and tracking refs that you haven't been tracking,
>     you can add these new refs to "all refs" to be unshallowed.

It was meant to emphasize --unshallow would not create a true clone,
if people miss the keywords "all existing" refs.. Maybe..

You may need to fetch and track other refs from the source repository
if you want to make full clone.

?

>
>>> 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
>
> Isn't that just the matter of updating remote.origin.fetch?  I do
> not think it belongs to "clone" (or "fetch").  Perhaps it belongs to
> "remote", where it already shows with "git remote -v" what is
> fetched and pushed.

Yeah, perhaps showing an advice about git-remote is enough if the
current ref spec does not fetch everything.

>>  --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
>
> Yeah, something like that would be a definite improvement.
>
> By the way, while composing this message, I scratched my head after
> typing
>
>     $ git clone --shallow=4 --no-local ./git.git ./playpen
>
> Is it just me or do we want to add such a synonym?

I have a series to define shallow boundaries by tags or dates, in
addition to history depth. It may take a few more months until I'm
finished with my ongoing topics. Then you could think about what
--shallow means exactly ;-)
-- 
Duy