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

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

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

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

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