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

From: Stephen & Linda Smith <[email-masked]>
Date: Tue, 29 Dec 2015 14:47:17 -0700

On Tuesday, December 29, 2015 11:24:00 AM Junio C Hamano wrote:
> "Stephen P. Smith" <[email-masked]> 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 <[email-masked]>
> > ---
> 
> 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
> 
> > +[[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?

I had that fixed and then managed to corrupt my working branch losing the change.

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

OK

> 
> > +
> >  [[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.
> --
> To unsubscribe from this list: send the line "unsubscribe git" in
> the body of a message to [email-masked]
> More majordomo info at  http://vger.kernel.org/majordomo-info.html