Re: [PATCH 2/2] Add a section to the users manual documenting shallow clones.
- From
Eric Sunshine <sunshine@sunshineco.com>
- Date
- Dec 22, 2015, 03:47 UTC
- Message-ID
- <CAPig+cQOAGzQMj5oNMEsD0u7Wqj80kyyYcOwi-Y0q1yHtX4s4A@mail.gmail.com>
- In-Reply-To
- <1450750180-1811-2-git-send-email-ischis2@cox.net>
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).
Show 5 quoted lines
> 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.Show 8 quoted lines
> 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.
Show 10 quoted lines
> [[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.
Show 15 quoted lines
> [[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