Re: [PATCH V5 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>
> ---

Thanks.  I do not think the reference to RelNotes were meant for the
end-user readers, though.  That was a hint for whoever is working to
clear the "todo" items from that list i.e. you ;-).

> +[[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`.
> +
> +Merging inside a <<def_shallow_clone,shallow clone>> will work as long
> +as the merge base is in the resent history.  If the merge base is not

recent?

> +present then the merge would be of un-related histories.  This
> +limitaion is fundamental and will not be removed.

I think "fundamental and will not change" is much less important
than the "huge conflicts, making the result of 'clone --depth=<n>'
not very useful to perform merges in", which is what the users would
need to know before deciding to use this feature.

> +
>  [[sharing-development-examples]]
>  Examples
>  --------
> @@ -4645,9 +4664,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.
> -
>  Add a section on working with other version control systems, including
>  CVS, Subversion, and just imports of series of release tarballs.