Re: [PATCH 2/2] Add a section to the users manual documenting shallow clones.

[Eric Sunshine <sunshine@sunshineco.com>]

On Mon, Dec 21, 2015 at 9:09 PM, Stephen P. Smith <ischis2@cox.net> wrote:
> Add a section to the users manual documenting shallow clones.

For the subject, prefix by section/module you're touching; drop
capitalization; drop full-stop (period).

> The todo section previously noted that documentation of shallow clones
> was not in the manual and had references to the 1.5.0 release notes.
>
> The patch adds a section to the manual and removes the entry in the
> ToDo list.

You might want to switch these two sentences around and drop
unnecessary "the patch" and "previously", etc. In fact, you don't even
need to mention removing the entry from the to-do list since that's a
natural byproduct of the change. Also write in imperative mood. So,
the full commit message might say something like this:

    user-manual: document shallow clones

    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>
> ---
> diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
> @@ -39,7 +39,6 @@ without any explanation.
>  Finally, see <<todo>> for ways that you can help make this manual more
>  complete.
>
> -

You typically should avoid sneaking in changes unrelated to the stated
purpose of the patch, even minor whitespace changes like this one
since such changes are distracting noise. If this was the only such
double-spaced line anomaly, then perhaps it would be okay, however,
there are a number of other such double-spaced line anomalies
throughout the file, so it doesn't make sense to fix only this one. If
*might*, however, make sense to fix all of them as a preparatory
cleanup patch which does only cleanups, and nothing else.

>  [[repositories-and-branches]]
>  Repositories and Branches
>  =========================
> @@ -72,6 +71,25 @@ called the <<def_working_tree,working tree>>, together with a special
>  top-level directory named `.git`, which contains all the information
>  about the history of the project.
>
> +[[how-to-get-a-git-repository-with-minimal-history]]
> +How to get a Git repository with minimal history
> +------------------------------------------------

Is this a good placement for this topic? Shallow repositories are not
heavily used, yet this placement amidst the very early and important
topics of cloning and checking out branches assigns potentially
significant (and perhaps unwarranted) weight to something used so
rarely.

> +Sometimes there is a need to view recent history or send email patches
> +for a project with lots of history.

This justification reads weakly since you can view recent history or
send patches even with full history. Perhaps you meant to say that
that there are times when one has an interest in *only* recent
history, and downloading and storing the full history would be
*wasteful* or *painful* or something.

> In such cases a <<def_shallow_clone,shallow
> +clone>> can be used to create a <<def_shallow_repository,shallow
> +repository>>.

This reads a bit oddly, as if "shallow clone" is some sort of entity
from which a "shallow repository" can be derived, rather than "shallow
clone" being a particular invocation of the git-clone command.

It also might be helpful to borrow some of the terminology from the
1.5.0 release notes when describing a shallow clone/repository. In
particular, its mention of "truncated history" may be valuable for
people to understand the concept.

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

Backquote the switch: `--depth`. Ditto below.

> The depth can later be changed
> +by using the linkgit:git-fetch[1] --depth switch.

Does the --unshallow switch also merit mention?

> +------------------------------------------------
> +       # the Linux kernel:
> +$ git clone --depth=20 git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
> +------------------------------------------------

I realize that you copied the indentation of the comment line from the
very first example block in the file, however, none of the other
examples follow suit. In other cases, the comment is flush-left.

More importantly, however, this comment adds no useful information to
the example, thus probably ought to be dropped.

>  [[how-to-check-out]]
>  How to check out a different version of a project
>  -------------------------------------------------
> @@ -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