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

"Stephen P. Smith" [off-list ref] 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 <redacted>
---

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.