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

[Stephen P. Smith]

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 
---
 Documentation/user-manual.txt | 21 ++---
 1 file changed, 18 insertions(+), 3 deletions(-)

diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
index 1c790ac..bdfe984 100644
--- 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 <> is useful when the recent
+history of a project is needed and getting real history recorded in
+the upstream is expensive. The resultant cloned <>
+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.
+
+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.  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.
+
 [[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 majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

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

[Eric Sunshine]

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

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 <> 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 <>
> +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 <>, 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 <> 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 <> 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 majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html