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

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

Stephen & Linda Smith <ischis2@cox.net> writes:

> On Tuesday, December 29, 2015 11:24:00 AM Junio C Hamano wrote:
>> "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 ;-> ).
>
> Actually that was a suggested update[1].   Do you still think I should replace it?
>
> [1] http://article.gmane.org/gmane.comp.version-control.git/282831

Sorry, but I am not sure what you mean by "it".

If you mean "replace the proposed log message", yes, I do.  The way
I read "Document X?  See Y" in the "todo" section is that it is a
hint for later contributors that X might be worth documenting, and
whoever wants to do so should look at Y while working on it.  It is
not at all telling the readers of the docuement to go read Y.

This commit follows through a "todo" item and what it did is
sufficiently described by its title.  I did not think there is
anything to add in the body of the message, and I found what was
there more confusing than enlightening, because the document wasn't
even pointing readers at the 1.5 Release Notes.

Thanks for working on this.  Perhaps the last paragraph can be like
this?

    Merging inside a <<def_shallow_clone,shallow clone>> will work
    as long as a merge base is found in the resent history.
    Otherwise, it will be like merging unrelated histories and may
    have to result in huge conflicts.  This limitation may make such
    a repository unsuitable to be used in merge based workflows.