On Tue, Dec 22, 2015 at 10:53 PM, Stephen P. Smith <ischis2@xxxxxxx> wrote: > Rather than merely pointing readers at the 1.5 release notes to > learn about shallow clones, document them formally. Thanks, this version looks better. A few comment below... > Signed-off-by: Stephen P. Smith <ischis2@xxxxxxx> > --- Right here, below the "---" line is a good place to describe what changed since the previous version. It's also reviewer-friendly to include a link to the last attempt, like this [1]. [1]: http://thread.gmane.org/gmane.comp.version-control.git/282828 > Documentation/user-manual.txt | 21 ++++++++++++++++++--- > 1 file changed, 18 insertions(+), 3 deletions(-) > > diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt > @@ -2128,6 +2128,24 @@ 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>> is useful when the recent > +history of a project is needed and getting real history recorded in Saying "full history" rather than "real history" might read better and be more meaningful. Also, perhaps say "from the upstream" rather than "recorded in the upstream". > +the upstream is expensive. The resultant cloned <<def_repository,repository>> > +has truncated history. This clone could be used to look at history > +near the tip of a branch and contribute email patches to the project. The final sentence pretty much just repeats what the first sentence said, thus doesn't really add any value, thus perhaps ought to be dropped. A possible rewrite of the above paragraph: 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 > +depth when creating a clone of a repository using the > +linkgit:git-clone[1] `--depth` switch. The depth can later be changed > +by using the linkgit:git-fetch[1] `--depth` switch. If there is later > +a need to fetch the entire history and if the source repository is > +complete, the linkgit:git-fetch[1] `--unshallow` switch can be used to > +convert a shallow repository to a complete one. Taken together, the last two sentences are a bit wordy. I wonder if combining them and being somewhat more laconic would help: 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 > -------- > @@ -4645,9 +4663,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. > > -- > 2.6.3.368.gf34be46 -- 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