[PATCH 1/2] Define the term shallow clone.

[PATCH 1/2] Define the term shallow clone.

[Stephen P. Smith]

There are several places in the documentation that
the term shallow clone is used. Defining the term
enables its use elsewhere with a known definition.

Signed-off-by: Stephen P. Smith <ischis2@cox.net>
---
 Documentation/glossary-content.txt | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/Documentation/glossary-content.txt b/Documentation/glossary-content.txt
index e225974..d384aed 100644
--- a/Documentation/glossary-content.txt
+++ b/Documentation/glossary-content.txt
@@ -531,6 +531,10 @@ The most notable example is `HEAD`.
 	"Secure Hash Algorithm 1"; a cryptographic hash function.
 	In the context of Git used as a synonym for <<def_object_name,object name>>.
 
+[[def_shallow_clone]]shallow clone::
+	A clone of a <<def_repository,repository>> which creates a
+    <<def_shallow_repository,shallow_repository>>.
+
 [[def_shallow_repository]]shallow repository::
 	A shallow <<def_repository,repository>> has an incomplete
 	history some of whose <<def_commit,commits>> have <<def_parent,parents>> cauterized away (in other
-- 
2.6.3.368.gf34be46

[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 <ischis2@cox.net>
---

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 <<todo>> for ways that you can help make this manual more
 complete.
 
-
 [[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
+------------------------------------------------
+
+Sometimes there is a need to view recent history or send email patches
+for a project with lots of history. In such cases a <<def_shallow_clone,shallow
+clone>> can be used to create a <<def_shallow_repository,shallow
+repository>>.
+
+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.
+
+------------------------------------------------
+	# 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

Re: [PATCH 1/2] Define the term shallow clone.

[Eric Sunshine]

On Mon, Dec 21, 2015 at 9:09 PM, Stephen P. Smith <ischis2@cox.net> wrote:
> There are several places in the documentation that
> the term shallow clone is used. Defining the term
> enables its use elsewhere with a known definition.
>
> Signed-off-by: Stephen P. Smith <ischis2@cox.net>
> ---
> diff --git a/Documentation/glossary-content.txt b/Documentation/glossary-content.txt
> @@ -531,6 +531,10 @@ The most notable example is `HEAD`.
>         "Secure Hash Algorithm 1"; a cryptographic hash function.
>         In the context of Git used as a synonym for <<def_object_name,object name>>.
>
> +[[def_shallow_clone]]shallow clone::
> +       A clone of a <<def_repository,repository>> which creates a
> +    <<def_shallow_repository,shallow_repository>>.

Botched indentation on second line of definition. Use tab rather than spaces.

>  [[def_shallow_repository]]shallow repository::
>         A shallow <<def_repository,repository>> has an incomplete
>         history some of whose <<def_commit,commits>> have <<def_parent,parents>> cauterized away (in other
> --
> 2.6.3.368.gf34be46

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

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 <ischis2@cox.net> wrote:
> >  [[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.

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

[PATCH V2 1/2] glossary: define the term shallow clone

[Stephen P. Smith]

There are several places in the documentation that
the term shallow clone is used. Defining the term
enables its use elsewhere with a known definition.
---
 Documentation/glossary-content.txt | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/Documentation/glossary-content.txt b/Documentation/glossary-content.txt
index e225974..cecc83d 100644
--- a/Documentation/glossary-content.txt
+++ b/Documentation/glossary-content.txt
@@ -531,6 +531,10 @@ The most notable example is `HEAD`.
 	"Secure Hash Algorithm 1"; a cryptographic hash function.
 	In the context of Git used as a synonym for <<def_object_name,object name>>.
 
+[[def_shallow_clone]]shallow clone::
+	A clone of a <<def_repository,repository>> which creates a
+	<<def_shallow_repository,shallow_repository>>.
+
 [[def_shallow_repository]]shallow repository::
 	A shallow <<def_repository,repository>> has an incomplete
 	history some of whose <<def_commit,commits>> have <<def_parent,parents>> cauterized away (in other
-- 
2.6.3.368.gf34be46

[PATCH V2 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.
---
 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 <<def_shallow_clone,shallow clone>> is useful when the recent
+history of a project is needed and getting real history recorded in
+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.
+
+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.
+
 [[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

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

[Stephen & Linda Smith]

I just realized that the two patches I sent earlier were missing the Signed by lines.   I will be resending them.

sps

[PATCH V3 1/2] glossary: define the term shallow clone

[Stephen P. Smith]

There are several places in the documentation that
the term shallow clone is used. Defining the term
enables its use elsewhere with a known definition.

Signed-off-by: Stephen P. Smith <ischis2@cox.net>
---
 Documentation/glossary-content.txt | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/Documentation/glossary-content.txt b/Documentation/glossary-content.txt
index e225974..cecc83d 100644
--- a/Documentation/glossary-content.txt
+++ b/Documentation/glossary-content.txt
@@ -531,6 +531,10 @@ The most notable example is `HEAD`.
 	"Secure Hash Algorithm 1"; a cryptographic hash function.
 	In the context of Git used as a synonym for <<def_object_name,object name>>.
 
+[[def_shallow_clone]]shallow clone::
+	A clone of a <<def_repository,repository>> which creates a
+	<<def_shallow_repository,shallow_repository>>.
+
 [[def_shallow_repository]]shallow repository::
 	A shallow <<def_repository,repository>> has an incomplete
 	history some of whose <<def_commit,commits>> have <<def_parent,parents>> cauterized away (in other
-- 
2.6.3.368.gf34be46

[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 <ischis2@cox.net>
---
 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 <<def_shallow_clone,shallow clone>> is useful when the recent
+history of a project is needed and getting real history recorded in
+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.
+
+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.
+
 [[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

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

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

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

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

[PATCH V4 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 <ischis2@cox.net>
---

 I replaced the paragraphs that I wrote with Eric Shunshine's since it
 was cleaner.

 I like the idea of linking to the preceeding effort, but gmane.org is
 currently undergoing maintance and therefore giving me errors when I
 attempt to access it.

 Documentation/user-manual.txt | 17 ++++++++++++++---
 1 file changed, 14 insertions(+), 3 deletions(-)

diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
index 1c790ac..5c13683 100644
--- a/Documentation/user-manual.txt
+++ b/Documentation/user-manual.txt
@@ -2128,6 +2128,20 @@ 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>>, 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 <<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`.
+
 [[sharing-development-examples]]
 Examples
 --------
@@ -4645,9 +4659,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

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

[Junio C Hamano]

"Stephen P. Smith" <ischis2@cox.net> writes:

> 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>
> ---
>
>  I replaced the paragraphs that I wrote with Eric Shunshine's since it
>  was cleaner.
>
>  I like the idea of linking to the preceeding effort, but gmane.org is
>  currently undergoing maintance and therefore giving me errors when I
>  attempt to access it.
>
>  Documentation/user-manual.txt | 17 ++++++++++++++---
>  1 file changed, 14 insertions(+), 3 deletions(-)
>
> diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
> index 1c790ac..5c13683 100644
> --- a/Documentation/user-manual.txt
> +++ b/Documentation/user-manual.txt
> @@ -2128,6 +2128,20 @@ 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>>, 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 <<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`.
> +
>  [[sharing-development-examples]]
>  Examples
>  --------

OK.

> @@ -4645,9 +4659,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.
> -

The 1.5.0 release notes describe three limitations that was present
back in the day.  I think the first two have been lifted (I am not
sure if it is throughly tested and shown to be bulletproof, though),
but the third limitation is fundamental and not something that will
ever be "fixed".  It probably is a good idea to add it here to avoid
hurting unsuspecting new users.

I notice that this section uses "a shallow clone" as a noun that
refers to a repository that has incomplete history--it is a synonym
to "a shallow repository", but more explicitly conveys the fact that
its cauterised history was obtained originally from elsewhere.

And I think that is a good use of the word, but I am not sure if
the phrasing used in your [1/2] is consistent with it:

+[[def_shallow_clone]]shallow clone::
+	A clone of a <<def_repository,repository>> which creates a
+	<<def_shallow_repository,shallow_repository>>.
+

I read this sentence, especially the part "A clone ... which creates"
as referring to "an act of running the 'git clone' command", not
"the (shallow) repository that results from such an act", and found
it a bit strange.

Right now, I do not think we have a canned way to create a shallow
repository locally without running "git clone --depth", but there is
no fundamental reason you shouldn't be able to do so (we can even
today create a shallow repository manually using lower-level tools
without running "clone --depth" from elsewhere).  And for somebody
who has seen such a repository, "a shallow clone" and "a shallow
repository" would have a slight difference.  The former is a shallow
repository that was created using "clone --depth"; the latter may or
may not ahve been created with "clone --depth", it just says the
repository does not have full history without hinting how it was
made so.

Perhaps replace 1/2 with something like this?

    [[def_shallow_clone]]shallow clone::
            Mostly a synonym to <<def_shallow_repository,shallow repository>>
            but the phrase makes it more explicit that it was created by
            running `git clone --depth=...` command.

    [[def_shallow_repository]]shallow repository::
            A shallow <<def_repository,repository>> has an incomplete
            history some of whose <<def_commit,commits>> have
            <<def_parent,parents>> cauter

I dunno.

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

[Stephen & Linda Smith]

On Monday, December 28, 2015 02:57:47 PM Junio C Hamano wrote:
> "Stephen P. Smith" <ischis2@cox.net> writes:
> 
> > 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>
> > ---
> >
> >  I replaced the paragraphs that I wrote with Eric Shunshine's since it
> >  was cleaner.
> >
> >  I like the idea of linking to the preceeding effort, but gmane.org is
> >  currently undergoing maintance and therefore giving me errors when I
> >  attempt to access it.
> >
> >  Documentation/user-manual.txt | 17 ++++++++++++++---
> >  1 file changed, 14 insertions(+), 3 deletions(-)
> >
> > diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
> > index 1c790ac..5c13683 100644
> > --- a/Documentation/user-manual.txt
> > +++ b/Documentation/user-manual.txt
> > @@ -2128,6 +2128,20 @@ 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>>, 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 <<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`.
> > +
> >  [[sharing-development-examples]]
> >  Examples
> >  --------
> 
> OK.
> 
> > @@ -4645,9 +4659,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.
> > -
> 
> The 1.5.0 release notes describe three limitations that was present
> back in the day.  I think the first two have been lifted (I am not
> sure if it is throughly tested and shown to be bulletproof, though),
> but the third limitation is fundamental and not something that will
> ever be "fixed".  It probably is a good idea to add it here to avoid
> hurting unsuspecting new users.
> 

I had thought about putting in warnings in the user's manual (and even wrote up a 
paragraph) but then decided to remove it.  My rationale was that there are 
warnings/restrictions elsewhere in the documentation but I wasn't finding any 
in the user manual.  Thanks for changing my mind.

> I notice that this section uses "a shallow clone" as a noun that
> refers to a repository that has incomplete history--it is a synonym
> to "a shallow repository", but more explicitly conveys the fact that
> its cauterised history was obtained originally from elsewhere.
> 
> And I think that is a good use of the word, but I am not sure if
> the phrasing used in your [1/2] is consistent with it:
> 
> +[[def_shallow_clone]]shallow clone::
> +	A clone of a <<def_repository,repository>> which creates a
> +	<<def_shallow_repository,shallow_repository>>.
> +
> 
> I read this sentence, especially the part "A clone ... which creates"
> as referring to "an act of running the 'git clone' command", not
> "the (shallow) repository that results from such an act", and found
> it a bit strange.
> 
> Right now, I do not think we have a canned way to create a shallow
> repository locally without running "git clone --depth", but there is
> no fundamental reason you shouldn't be able to do so (we can even
> today create a shallow repository manually using lower-level tools
> without running "clone --depth" from elsewhere).  And for somebody
> who has seen such a repository, "a shallow clone" and "a shallow
> repository" would have a slight difference.  The former is a shallow
> repository that was created using "clone --depth"; the latter may or
> may not ahve been created with "clone --depth", it just says the
> repository does not have full history without hinting how it was
> made so.
> 
> Perhaps replace 1/2 with something like this?
> 
>     [[def_shallow_clone]]shallow clone::
>             Mostly a synonym to <<def_shallow_repository,shallow repository>>
>             but the phrase makes it more explicit that it was created by
>             running `git clone --depth=...` command.
> 
>     [[def_shallow_repository]]shallow repository::
>             A shallow <<def_repository,repository>> has an incomplete
>             history some of whose <<def_commit,commits>> have
>             <<def_parent,parents>> cauter
> 
That seems like better wording.    

Until I started working on this I wasn't really aware of the term shallow repository.   
Everything I had seen was shallow clone.

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

[PATCH V4 1/2] glossary: define the term shallow clone

[Stephen P. Smith]

There are several places in the documentation that
the term shallow clone is used. Defining the term
enables its use elsewhere with a known definition.

Signed-off-by: Stephen P. Smith <ischis2@cox.net>
---

Notes:
    The review comments for the user guide update[1] suggested a change
    in the definition of a shallow clone to:
       - note differences between a shallow clone and a shallow repository and
       - define it as a noun (which is the way the user guide update
         patch uses the term)
    
    [1] http://article.gmane.org/gmane.comp.version-control.git/283052

 Documentation/glossary-content.txt | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/Documentation/glossary-content.txt b/Documentation/glossary-content.txt
index e225974..cafc284 100644
--- a/Documentation/glossary-content.txt
+++ b/Documentation/glossary-content.txt
@@ -531,6 +531,11 @@ The most notable example is `HEAD`.
 	"Secure Hash Algorithm 1"; a cryptographic hash function.
 	In the context of Git used as a synonym for <<def_object_name,object name>>.
 
+[[def_shallow_clone]]shallow clone::
+	Mostly a synonym to <<def_shallow_repository,shallow repository>>
+	but the phrase makes it more explicit that it was created by
+	running `git clone --depth=...` command.
+
 [[def_shallow_repository]]shallow repository::
 	A shallow <<def_repository,repository>> has an incomplete
 	history some of whose <<def_commit,commits>> have <<def_parent,parents>> cauterized away (in other
-- 
2.7.0-rc2

[PATCH V5 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 <ischis2@cox.net>
---

Notes:
    Added a paragraph about the fundamental limitation with merging
    histories that do not have a merge base in the shallow repository.
    
    The review comment implied that since the first two limitations have
    been lifted they would not need to be noted [1].
    
    [1] http://article.gmane.org/gmane.comp.version-control.git/283052

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

diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
index 1c790ac..78f878d 100644
--- a/Documentation/user-manual.txt
+++ b/Documentation/user-manual.txt
@@ -2128,6 +2128,25 @@ 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>>, 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 <<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`.
+
+Merging inside a <<def_shallow_clone,shallow clone>> will work as long
+as the merge base is in the resent history.  If the merge base is not
+present then the merge would be of un-related histories.  This
+limitaion is fundamental and will not be removed.
+
 [[sharing-development-examples]]
 Examples
 --------
@@ -4645,9 +4664,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.7.0-rc2

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

[Junio C Hamano]

"Stephen P. Smith" <ischis2@cox.net> writes:

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

Thanks.  I do not think the reference to RelNotes were meant for the
end-user readers, though.  That was a hint for whoever is working to
clear the "todo" items from that list i.e. you ;-).

> +[[how-to-get-a-git-repository-with-minimal-history]]
> +How to get a Git repository with minimal history
> +------------------------------------------------
> +
> +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.
> +
> +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`.
> +
> +Merging inside a <<def_shallow_clone,shallow clone>> will work as long
> +as the merge base is in the resent history.  If the merge base is not

recent?

> +present then the merge would be of un-related histories.  This
> +limitaion is fundamental and will not be removed.

I think "fundamental and will not change" is much less important
than the "huge conflicts, making the result of 'clone --depth=<n>'
not very useful to perform merges in", which is what the users would
need to know before deciding to use this feature.

> +
>  [[sharing-development-examples]]
>  Examples
>  --------
> @@ -4645,9 +4664,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.

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

[Stephen & Linda Smith]

On Tuesday, December 29, 2015 11:24:00 AM Junio C Hamano wrote:
> "Stephen P. Smith" <ischis2@cox.net> writes:
> 
> > 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>
> > ---
> 
> Thanks.  I do not think the reference to RelNotes were meant for the
> end-user readers, though.  That was a hint for whoever is working to
> clear the "todo" items from that list i.e. you ;-> ).

Actually that was a suggested update[1].   Do you still think I should replace it?

[1] http://article.gmane.org/gmane.comp.version-control.git/282831
> 
> > +[[how-to-get-a-git-repository-with-minimal-history]]
> > +How to get a Git repository with minimal history
> > +------------------------------------------------
> > +
> > +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.
> > +
> > +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`.
> > +
> > +Merging inside a <<def_shallow_clone,shallow clone>> will work as long
> > +as the merge base is in the resent history.  If the merge base is not
> 
> recent?

I had that fixed and then managed to corrupt my working branch losing the change.

> 
> > +present then the merge would be of un-related histories.  This
> > +limitaion is fundamental and will not be removed.
> 
> I think "fundamental and will not change" is much less important
> than the "huge conflicts, making the result of 'clone --depth=<n>'
> not very useful to perform merges in", which is what the users would
> need to know before deciding to use this feature.

OK

> 
> > +
> >  [[sharing-development-examples]]
> >  Examples
> >  --------
> > @@ -4645,9 +4664,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.
> --
> To unsubscribe from this list: send the line "unsubscribe git" in
> the body of a message to majordomo@vger.kernel.org
> More majordomo info at  http://vger.kernel.org/majordomo-info.html

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

[Junio C Hamano]

Stephen & Linda Smith <ischis2@cox.net> writes:

> On Tuesday, December 29, 2015 11:24:00 AM Junio C Hamano wrote:
>> "Stephen P. Smith" <ischis2@cox.net> writes:
>> 
>> > 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>
>> > ---
>> 
>> Thanks.  I do not think the reference to RelNotes were meant for the
>> end-user readers, though.  That was a hint for whoever is working to
>> clear the "todo" items from that list i.e. you ;-> ).
>
> Actually that was a suggested update[1].   Do you still think I should replace it?
>
> [1] http://article.gmane.org/gmane.comp.version-control.git/282831

Sorry, but I am not sure what you mean by "it".

If you mean "replace the proposed log message", yes, I do.  The way
I read "Document X?  See Y" in the "todo" section is that it is a
hint for later contributors that X might be worth documenting, and
whoever wants to do so should look at Y while working on it.  It is
not at all telling the readers of the docuement to go read Y.

This commit follows through a "todo" item and what it did is
sufficiently described by its title.  I did not think there is
anything to add in the body of the message, and I found what was
there more confusing than enlightening, because the document wasn't
even pointing readers at the 1.5 Release Notes.

Thanks for working on this.  Perhaps the last paragraph can be like
this?

    Merging inside a <<def_shallow_clone,shallow clone>> will work
    as long as a merge base is found in the resent history.
    Otherwise, it will be like merging unrelated histories and may
    have to result in huge conflicts.  This limitation may make such
    a repository unsuitable to be used in merge based workflows.

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

[Stephen P. Smith]

Signed-off-by: Stephen P. Smith <ischis2@cox.net>
---
 Documentation/user-manual.txt | 23 ++++++++++++++++++++---
 1 file changed, 20 insertions(+), 3 deletions(-)

diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
index 1c790ac..15e97d3 100644
--- a/Documentation/user-manual.txt
+++ b/Documentation/user-manual.txt
@@ -2128,6 +2128,26 @@ 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>>, 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 <<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`.
+
+Merging inside a <<def_shallow_clone,shallow clone>> will work as long
+as the merge base is in the recent history.
+Otherwise, it will be like merging unrelated histories and may
+have to result in huge conflicts.  This limitation may make such
+a repository unsuitable to be used in merge based workflows.
+
 [[sharing-development-examples]]
 Examples
 --------
@@ -4645,9 +4665,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.7.0-rc2

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

[Junio C Hamano]

Junio C Hamano <gitster@pobox.com> writes:

> Thanks for working on this.  Perhaps the last paragraph can be like
> this?
>
>     Merging inside a <<def_shallow_clone,shallow clone>> will work
>     as long as a merge base is found in the resent history.
>     Otherwise, it will be like merging unrelated histories and may
>     have to result in huge conflicts.  This limitation may make such
>     a repository unsuitable to be used in merge based workflows.

I forgot to say this, but "a" merge base above is very much
deliberate.  There can be (and indeed are in real life projects)
multiple merge bases between two commits being merged, and an
automatic merge wouldn't "be like merging unrelated histories" as
long as one of them exists in the shallowed history.

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

[Stephen P. Smith]

Signed-off-by: Stephen P. Smith <ischis2@cox.net>
---
 Documentation/user-manual.txt | 23 ++++++++++++++++++++---
 1 file changed, 20 insertions(+), 3 deletions(-)

diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
index 1c790ac..ce347ff 100644
--- a/Documentation/user-manual.txt
+++ b/Documentation/user-manual.txt
@@ -2128,6 +2128,26 @@ 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>>, 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 <<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`.
+
+Merging inside a <<def_shallow_clone,shallow clone>> will work as long
+as a merge base is in the recent history.
+Otherwise, it will be like merging unrelated histories and may
+have to result in huge conflicts.  This limitation may make such
+a repository unsuitable to be used in merge based workflows.
+
 [[sharing-development-examples]]
 Examples
 --------
@@ -4645,9 +4665,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.7.0-rc2