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

[Stephen & Linda Smith <ischis2@cox.net>]

On Monday, December 28, 2015 02:57:47 PM 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>
> > ---
> >
> >  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 had thought about putting in warnings in the user's manual (and even wrote up a 
paragraph) but then decided to remove it.  My rationale was that there are 
warnings/restrictions elsewhere in the documentation but I wasn't finding any 
in the user manual.  Thanks for changing my mind.

> 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
> 
That seems like better wording.    

Until I started working on this I wasn't really aware of the term shallow repository.   
Everything I had seen was shallow clone.

> --
> To unsubscribe from this list: send the line "unsubscribe git" in
> the body of a message to majordomo@vger.kernel.org
> More majordomo info at  http://vger.kernel.org/majordomo-info.html