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

[Stephen & Linda Smith]

On Monday, December 21, 2015 10:47:16 PM Eric Sunshine wrote:
> On Mon, Dec 21, 2015 at 9:09 PM, Stephen P. Smith  wrote:
> >  [[repositories-and-branches]]
> >  Repositories and Branches
> >  =
> > @@ -72,6 +71,25 @@ called the <>, 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.

After some thought I think that the section should be moved near the bottom of 
"Sharing development with others" since 1) that would reduce the significance 
and 2) it seems that a shallow clone would normally be used for contributing to 
a 
large project when downloading the entire history is expensive.
Should it be placed just above the Tony Luk example?

sps
--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

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

[Stephen P. Smith]

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.

Signed-off-by: Stephen P. Smith 
---

Notes:
I considered adding a paragraph to each of several sections noting the
issues with regard to clone, fetch, merge and push.

After looking for other such notes and finding none in the
manual I chose to not add the paragraphs.

 Documentation/user-manual.txt | 23 +++
 1 file changed, 19 insertions(+), 4 deletions(-)

diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
index 1c790ac..15825e0 100644
--- a/Documentation/user-manual.txt
+++ b/Documentation/user-manual.txt
@@ -39,7 +39,6 @@ without any explanation.
 Finally, see <> for ways that you can help make this manual more
 complete.
 
-
 [[repositories-and-branches]]
 Repositories and Branches
 =
@@ -72,6 +71,25 @@ called the <>, 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
+
+
+Sometimes there is a need to view recent history or send email patches
+for a project with lots of history. In such cases a <> can be used to create a <>.
+
+A <> 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.
+
+
+   # the Linux kernel:
+$ git clone --depth=20 
git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
+
+
 [[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

--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

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

[Eric Sunshine]

On Mon, Dec 21, 2015 at 9:09 PM, Stephen P. Smith  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 
> ---
> diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
> @@ -39,7 +39,6 @@ without any explanation.
>  Finally, see <> 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 <>, 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 < +clone>> can be used to create a < +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 <> 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
--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message