On Monday, December 28, 2015 02:57:47 PM Junio C Hamano wrote: > "Stephen P. Smith" <ischis2@xxxxxxx> 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@xxxxxxx> > > --- > > > > 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@xxxxxxxxxxxxxxx > More majordomo info at http://vger.kernel.org/majordomo-info.html -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html