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

From: Eric Sunshine <sunshine@sunshineco.com>
Date: Dec 23, 2015, 07:47 UTC
Message-ID: <CAPig+cRMdpJ-k9L33jE01ubfK6MOWNGwuoUULuQqOv8C0we+DQ@mail.gmail.com>
In-Reply-To: <1450842827-14115-1-git-send-email-ischis2@cox.net>

On Tue, Dec 22, 2015 at 10:53 PM, Stephen P. Smith <ischis2@cox.net> 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@cox.net>
> ---

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

Show 14 quoted lines

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

Show 7 quoted lines

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

Show 15 quoted lines

>  [[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