Re: [PATCH V4 2/2] user-manual: add section documenting shallow clones

From: Junio C Hamano <gitster@pobox.com>
Date: Dec 28, 2015, 22:57 UTC
Message-ID: <xmqqfuymji50.fsf@gitster.mtv.corp.google.com>
In-Reply-To: <1450902961-1528-1-git-send-email-ischis2@cox.net>

"Stephen P. Smith" <ischis2@cox.net> writes:

Show 41 quoted lines

> Rather than merely pointing readers at the 1.5 release notes to
> learn about shallow clones, document them formally.
>
> Signed-off-by: Stephen P. Smith <ischis2@cox.net>
> ---
>
>  I replaced the paragraphs that I wrote with Eric Shunshine's since it
>  was cleaner.
>
>  I like the idea of linking to the preceeding effort, but gmane.org is
>  currently undergoing maintance and therefore giving me errors when I
>  attempt to access it.
>
>  Documentation/user-manual.txt | 17 ++++++++++++++---
>  1 file changed, 14 insertions(+), 3 deletions(-)
>
> diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
> index 1c790ac..5c13683 100644
> --- a/Documentation/user-manual.txt
> +++ b/Documentation/user-manual.txt
> @@ -2128,6 +2128,20 @@ The gitweb cgi script provides users an easy way to browse your
>  project's files and history without having to install Git; see the file
>  gitweb/INSTALL in the Git source tree for instructions on setting it up.
>  
> +[[how-to-get-a-git-repository-with-minimal-history]]
> +How to get a Git repository with minimal history
> +------------------------------------------------
> +
> +A <<def_shallow_clone,shallow clone>>, with its truncated
> +history, is useful when one is interested only in recent history
> +of a project and getting full history from the upstream is
> +expensive.
> +
> +A <<def_shallow_clone,shallow clone>> is created by specifying
> +the linkgit:git-clone[1] `--depth` switch. The depth can later be
> +changed with the linkgit:git-fetch[1] `--depth` switch, or full
> +history restored with `--unshallow`.
> +
>  [[sharing-development-examples]]
>  Examples
>  --------

OK.

Show 7 quoted lines

> @@ -4645,9 +4659,6 @@ standard end-of-chapter section?
>  
>  Include cross-references to the glossary, where appropriate.
>  
> -Document shallow clones?  See draft 1.5.0 release notes for some
> -documentation.
> -

The 1.5.0 release notes describe three limitations that was present back in the day. I think the first two have been lifted (I am not sure if it is throughly tested and shown to be bulletproof, though), but the third limitation is fundamental and not something that will ever be "fixed". It probably is a good idea to add it here to avoid hurting unsuspecting new users.

I notice that this section uses "a shallow clone" as a noun that refers to a repository that has incomplete history--it is a synonym to "a shallow repository", but more explicitly conveys the fact that its cauterised history was obtained originally from elsewhere.

And I think that is a good use of the word, but I am not sure if the phrasing used in your [1/2] is consistent with it:

+[[def_shallow_clone]]shallow clone:: + A clone of a <<def_repository,repository>> which creates a + <<def_shallow_repository,shallow_repository>>. +

I read this sentence, especially the part "A clone ... which creates" as referring to "an act of running the 'git clone' command", not "the (shallow) repository that results from such an act", and found it a bit strange.

Right now, I do not think we have a canned way to create a shallow repository locally without running "git clone --depth", but there is no fundamental reason you shouldn't be able to do so (we can even today create a shallow repository manually using lower-level tools without running "clone --depth" from elsewhere). And for somebody who has seen such a repository, "a shallow clone" and "a shallow repository" would have a slight difference. The former is a shallow repository that was created using "clone --depth"; the latter may or may not ahve been created with "clone --depth", it just says the repository does not have full history without hinting how it was made so.

Perhaps replace 1/2 with something like this?

    [[def_shallow_clone]]shallow clone::
            Mostly a synonym to <<def_shallow_repository,shallow repository>>
            but the phrase makes it more explicit that it was created by
            running `git clone --depth=...` command.

    [[def_shallow_repository]]shallow repository::
            A shallow <<def_repository,repository>> has an incomplete
            history some of whose <<def_commit,commits>> have
            <<def_parent,parents>> cauter

I dunno.