Re: git clone --depth: shallow clone problems

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

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).

>  	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).

> ++
> +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.

>> 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.

>  --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?

Thanks.