[PATCH] clone: document partial clone section

[PATCH] clone: document partial clone section

[Teng Long via GitGitGadget]

From: Dyrone Teng <dyroneteng@gmail.com>

Partial clones are created using 'git clone', but there is no related
help information in the git-clone documentation during a period. Add
a relevant section to help users understand what partial clones are
and how they differ from normal clones.

The section briefly introduces the applicable scenarios and some
precautions of partial clone. If users want to know more about its
technical design and other details, users can view the link of
git-partial-clone(7) according to the guidelines in the section.

Signed-off-by: Teng Long <dyroneteng@gmail.com>
---
    clone: document partial clone section
    
    Partial clones are created using 'git clone', but there is no related
    help information in the git-clone documentation during a period. Add a
    relevant section to help users understand what partial clones are and
    how they differ from normal clones.
    
    The section briefly introduces the applicable scenarios and some
    precautions of partial clone. If users want to know more about its
    technical design and other details, users can view the link of
    git-partial-clone(7) according to the guidelines in the section.

Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-745%2Fdyrone%2Fmaster-v1
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-745/dyrone/master-v1
Pull-Request: https://github.com/git/git/pull/745

 Documentation/git-clone.txt | 69 +++++++++++++++++++++++++++++++++++++
 1 file changed, 69 insertions(+)

diff --git a/Documentation/git-clone.txt b/Documentation/git-clone.txt
index bf24f1813ad..dd92d153535 100644
--- a/Documentation/git-clone.txt
+++ b/Documentation/git-clone.txt
@@ -297,6 +297,75 @@ or `--mirror` is given)
 	for `host.xz:foo/.git`).  Cloning into an existing directory
 	is only allowed if the directory is empty.
 
+Partial Clone
+-------------
+
+By default, `git clone` will download every reachable object, including
+every version of every file in the history of the repository. The **partial clone**
+feature allows Git to transfer fewer objects and request them from the
+remote only when they are needed, so some reachable objects can be
+omitted from the initial `git clone` and subsequent `git fetch`
+operations. In this way, a partial clone can reduce the network traffic
+costs and disk space usage when git is working under a large repository.
+
+To use the partial clone feature, you can run `git clone` with the 
+`--filter=<filter-spec>` option. If the repository has a deep history
+and you don't want to download any blobs, the form `filter=blob:none`
+will omit all the blobs. If the repository has some large blobs and you
+want to prevent some large blobs being downloaded by an appropriate
+threshold, the form `--filter=blob:limit=<n>[kmg]` omits blobs larger
+than n bytes or units (see linkgit:git-rev-list[1]).
+
+When using a partial clone, Git will request missing objects from the
+remote(s) when necessary. Several commands that do not involve a request
+over a network may now trigger these requests.
+
+For example, The <repository> contains two branches which names 'master'
+and 'topic. Then, we clone the repository by
+
+    $ git clone --filter=blob:none --no-checkout <repository>
+
+With the `--filter=blob:none` option Git will omit all the blobs and
+the `--no-checkout` option Git will not perform a checkout of HEAD
+after the clone is complete. Then, we check out the remote tracking
+'topic' branch by
+
+    $ git checkout -b topic origin/topic 
+
+The output looks like
+
+------------
+    remote: Enumerating objects: 1, done.
+    remote: Counting objects: 100% (1/1), done.
+    remote: Total 1 (delta 0), reused 0 (delta 0), pack-reused 0
+    Receiving objects: 100% (1/1), 43 bytes | 43.00 KiB/s, done.
+    Branch 'topic' set up to track remote branch 'topic' from 'origin'.
+    Switched to a new branch 'topic'
+------------
+
+The output is a bit surprising but it shows how partial clone works.
+When we check out the branch 'topic' Git will request the missing blobs
+because they are needed. Then, We can switch back to branch 'master' by
+
+    $ git checkout master
+
+This time the output looks like
+
+------------
+    Switched to branch 'master'
+    Your branch is up to date with 'origin/master'.
+------------
+
+It shows that when we switch back to the previous location, the checkout
+is done without a download because the repository has all the blobs that
+were downloaded previously.
+
+`git log` may also make a surprise with partial clones. `git log
+--<path>` will not cause downloads with the blob filters, because it's
+only reading commits. `git log -p -- <path>` will download blobs to
+generate the patch output and git log --raw will download all blobs
+that changed at recent commits in order to compute renames.
+
 :git-clone: 1
 include::urls.txt[]
 

base-commit: 9fadedd637b312089337d73c3ed8447e9f0aa775
-- 
gitgitgadget

Re: [PATCH] clone: document partial clone section

[Derrick Stolee]

On 4/1/2020 10:02 PM, Teng Long via GitGitGadget wrote:
> From: Dyrone Teng <dyroneteng@gmail.com>
> 
> Partial clones are created using 'git clone', but there is no related
> help information in the git-clone documentation during a period. Add
> a relevant section to help users understand what partial clones are
> and how they differ from normal clones.
> 
> The section briefly introduces the applicable scenarios and some
> precautions of partial clone. If users want to know more about its
> technical design and other details, users can view the link of
> git-partial-clone(7) according to the guidelines in the section.
Everyone, meet Dyrone! Dyrone volunteered to work on the partial
clone documentation after I reached out on Twitter. We did one
round of internal review before this submission.

Dyrone, do you want to introduce yourself a bit more to the
community?

> From: Dyrone Teng <dyroneteng@gmail.com>
> Signed-off-by: Teng Long <dyroneteng@gmail.com>

And a small thing: we prefer the sign-off to match the author
information at the top. These are at least the same email
address, so that's good.

Thanks,
-Stolee

Re: [PATCH] clone: document partial clone section

[Junio C Hamano]

"Teng Long via GitGitGadget" <gitgitgadget@gmail.com> writes:

> From: Dyrone Teng <dyroneteng@gmail.com>
>
> Partial clones are created using 'git clone', but there is no related
> help information in the git-clone documentation during a period. Add
> a relevant section to help users understand what partial clones are
> and how they differ from normal clones.

I am not sure what "during a period" means there; perhaps we can
simplydrop these three words to make the sentence clearer without
changing what you wanted to say?

> The section briefly introduces the applicable scenarios and some
> precautions of partial clone. If users want to know more about its
> technical design and other details, users can view the link of
> git-partial-clone(7) according to the guidelines in the section.

Otherwise, the above is a nice and clearly written summary.

> Signed-off-by: Teng Long <dyroneteng@gmail.com>

As Derrick pointed out, we want to see the authors sign their
patches using the same authors' name on this line.

> diff --git a/Documentation/git-clone.txt b/Documentation/git-clone.txt
> index bf24f1813ad..dd92d153535 100644
> --- a/Documentation/git-clone.txt
> +++ b/Documentation/git-clone.txt
> @@ -297,6 +297,75 @@ or `--mirror` is given)
>  	for `host.xz:foo/.git`).  Cloning into an existing directory
>  	is only allowed if the directory is empty.
>  
> +Partial Clone
> +-------------
> +
> +By default, `git clone` will download every reachable object, including
> +every version of every file in the history of the repository. The **partial clone**

Please avoid overly long lines.

> +... omitted from the initial `git clone` and subsequent `git fetch`
> +operations. In this way, a partial clone can reduce the network traffic
> +costs and disk space usage when git is working under a large repository.

Perhaps "can reduce the initial network traffic costs...", as you'd
end up paying the cost for the part of the repository you'd actually
use.

And there is traffic and disk usage reduction that comes but not "in
this way (i.e. initial clone does not have to transfer)", which is
that parts of the trees and histories you never touch may not have
to be transferred and stored at all.  If you meant to cover benefits
coming from both reasons, perhaps omit "In this way, " and then
we do not have to say "the initial network traffic costs...".  Or
you may want to spell out both a bit more explicitly.

> +To use the partial clone feature, you can run `git clone` with the 
> +`--filter=<filter-spec>` option. If the repository has a deep history
> +and you don't want to download any blobs, the form `filter=blob:none`
> +will omit all the blobs.

If the repository of a young project simply has a large collection
of files, blob:none would still omit all the blobs, so I am not sure
if "the repository has a deep history and" is a good thing to say.

> +When using a partial clone, Git will request missing objects from the
> +remote(s) when necessary. Several commands that do not involve a request
> +over a network may now trigger these requests.

We may want to phrase this a bit stronger, if you are listing these
as pros-and-cons?  E.g. "Some 'local' commands may fail without a
network connection to the remote repository."

> +For example, The <repository> contains two branches which names 'master'
> +and 'topic. Then, we clone the repository by
> +
> +    $ git clone --filter=blob:none --no-checkout <repository>
> +
> +With the `--filter=blob:none` option Git will omit all the blobs and
> +the `--no-checkout` option Git will not perform a checkout of HEAD
> +after the clone is complete. Then, we check out the remote tracking
> +'topic' branch by
> +
> +    $ git checkout -b topic origin/topic 
> +
> +The output looks like
> +
> +------------
> +    remote: Enumerating objects: 1, done.
> +    remote: Counting objects: 100% (1/1), done.
> +    remote: Total 1 (delta 0), reused 0 (delta 0), pack-reused 0
> +    Receiving objects: 100% (1/1), 43 bytes | 43.00 KiB/s, done.
> +    Branch 'topic' set up to track remote branch 'topic' from 'origin'.
> +    Switched to a new branch 'topic'
> +------------
> +
> +The output is a bit surprising but it shows how partial clone works.
> +When we check out the branch 'topic' Git will request the missing blobs
> +because they are needed. Then, We can switch back to branch 'master' by
> +
> +    $ git checkout master
> +
> +This time the output looks like
> +
> +------------
> +    Switched to branch 'master'
> +    Your branch is up to date with 'origin/master'.
> +------------
> +
> +It shows that when we switch back to the previous location, the checkout
> +is done without a download because the repository has all the blobs that
> +were downloaded previously.

Good illusration.  Nicely done.

> +`git log` may also make a surprise with partial clones. `git log
> +--<path>` will not cause downloads with the blob filters, because it's

You meant to leave a SP between double-dash and <pathspec> (these
things are called <pathspec> and not necessarily a <path>, so use
the right word) here.

> +only reading commits.

This is incorrect.  A pathspec limited "log" reads both commits and
trees.  Luckily, that does not change the conclusion---a blob-less
partial clone already has all tree objects in addition to commit
objects, so there is no need for lazy/on-demand fetching.

> `git log -p -- <path>` will download blobs to
> +generate the patch output and git log --raw will download all blobs
> +that changed at recent commits in order to compute renames.

I do not know anybody sane uses '--raw' these days, but a better
way to describe this may be

    In addition to any options that require git to look at the
    contents of blobs, like "-p" and "--stat", options that cause
    git to report pathnames, like "--summary" and "--raw", will
    trigger lazy/on-demand fetching of blobs, as they are needed to
    detect inexact renames.

Thanks.

Re: [PATCH] clone: document partial clone section

[Derrick Stolee]

On 4/2/2020 1:37 PM, Junio C Hamano wrote:
>> `git log -p -- <path>` will download blobs to
>> +generate the patch output and git log --raw will download all blobs
>> +that changed at recent commits in order to compute renames.
> I do not know anybody sane uses '--raw' these days, but a better
> way to describe this may be

Ha. This was my fault for recommending it. The point was that some
diff options require blob contents even if it doesn't seem obvious.
Yes, "-p" will get contents to show the in-file diff, but --raw
will calculate renames so it can show the rename in the output.

When I use '--raw' what I really care about is '--name-only' but
does that compute renames?

As you mention, '--summary' would suffice for the point as it
checks for renames.

Thanks,
-Stolee

[PATCH v2 0/3] clone: document partial clone section

[Teng Long via GitGitGadget]

Partial clones are created using 'git clone', but there is no related help
information in the git-clone documentation during a period. Add a relevant
section to help users understand what partial clones are and how they differ
from normal clones.

The section briefly introduces the applicable scenarios and some precautions
of partial clone. If users want to know more about its technical design and
other details, users can view the link of git-partial-clone(7) according to
the guidelines in the section.

Derrick Stolee (2):
  partial-clone: set default filter with --partial
  clone: document --partial and --filter options

Dyrone Teng (1):
  clone: document partial clone section

 Documentation/git-clone.txt   | 87 ++++++++++++++++++++++++++++++++++-
 list-objects-filter-options.c | 18 ++++++++
 list-objects-filter-options.h |  8 +++-
 t/t5616-partial-clone.sh      | 42 +++++++++++++----
 4 files changed, 143 insertions(+), 12 deletions(-)


base-commit: 6c85aac65fb455af85745130ce35ddae4678db84
Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-745%2Fdyrone%2Fmaster-v2
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-745/dyrone/master-v2
Pull-Request: https://github.com/git/git/pull/745

Range-diff vs v1:

 -:  ----------- > 1:  6f340d9aadf partial-clone: set default filter with --partial
 -:  ----------- > 2:  9baf4c8ba38 clone: document --partial and --filter options
 1:  f063efa545b ! 3:  c1a44a35095 clone: document partial clone section
     @@ Commit message
          clone: document partial clone section
      
          Partial clones are created using 'git clone', but there is no related
     -    help information in the git-clone documentation during a period. Add
     -    a relevant section to help users understand what partial clones are
     -    and how they differ from normal clones.
     +    help information in the git-clone documentation. Add a relevant section
     +    to help users understand what partial clones are and how they differ
     +    from normal clones.
      
          The section briefly introduces the applicable scenarios and some
          precautions of partial clone. If users want to know more about its
          technical design and other details, users can view the link of
          git-partial-clone(7) according to the guidelines in the section.
      
     -    Signed-off-by: Teng Long <dyroneteng@gmail.com>
     +    Signed-off-by: Dyrone Teng <dyroneteng@gmail.com>
      
       ## Documentation/git-clone.txt ##
      @@ Documentation/git-clone.txt: or `--mirror` is given)
     @@ Documentation/git-clone.txt: or `--mirror` is given)
      +-------------
      +
      +By default, `git clone` will download every reachable object, including
     -+every version of every file in the history of the repository. The **partial clone**
     -+feature allows Git to transfer fewer objects and request them from the
     -+remote only when they are needed, so some reachable objects can be
     -+omitted from the initial `git clone` and subsequent `git fetch`
     -+operations. In this way, a partial clone can reduce the network traffic
     -+costs and disk space usage when git is working under a large repository.
     ++every version of every file in the history of the repository. The
     ++**partial clone** feature allows Git to transfer fewer objects and
     ++request them from the remote only when they are needed, so some
     ++reachable objects can be omitted from the initial `git clone` and
     ++subsequent `git fetch` operations.
      +
      +To use the partial clone feature, you can run `git clone` with the 
     -+`--filter=<filter-spec>` option. If the repository has a deep history
     -+and you don't want to download any blobs, the form `filter=blob:none`
     -+will omit all the blobs. If the repository has some large blobs and you
     -+want to prevent some large blobs being downloaded by an appropriate
     -+threshold, the form `--filter=blob:limit=<n>[kmg]` omits blobs larger
     -+than n bytes or units (see linkgit:git-rev-list[1]).
     ++`--filter=<filter-spec>` option. If you want to clone a repository
     ++without download any blobs, the form `filter=blob:none` will omit all
     ++the blobs. If the repository has some large blobs and you want to
     ++prevent some large blobs being downloaded by an appropriate threshold,
     ++the form `--filter=blob:limit=<n>[kmg]`omits blobs larger than n bytes
     ++or units (see linkgit:git-rev-list[1]).
      +
     -+When using a partial clone, Git will request missing objects from the
     -+remote(s) when necessary. Several commands that do not involve a request
     -+over a network may now trigger these requests.
     ++As mentioned before, a partially cloned repository may have to request
     ++the missing objects when they are needed. So some 'local' commands may
     ++fail without a network connection to the remote repository.
      +
      +For example, The <repository> contains two branches which names 'master'
      +and 'topic. Then, we clone the repository by
     @@ Documentation/git-clone.txt: or `--mirror` is given)
      +were downloaded previously.
      +
      +`git log` may also make a surprise with partial clones. `git log
     -+--<path>` will not cause downloads with the blob filters, because it's
     -+only reading commits. `git log -p -- <path>` will download blobs to
     -+generate the patch output and git log --raw will download all blobs
     -+that changed at recent commits in order to compute renames.
     ++-- <pathspec>` will not cause downloads with the blob filters, because
     ++it's only reading commits and trees. In addition to any options that
     ++require git to look at the contents of blobs, like "-p" and "--stat"
     ++, options that cause git to report pathnames, like "--summary" and
     ++"--raw", will trigger lazy/on-demand fetching of blobs, as they are
     ++needed to detect inexact renames.
     ++
     ++linkgit:partial-clone[1]
      +
       :git-clone: 1
       include::urls.txt[]

-- 
gitgitgadget

[PATCH v2 1/3] partial-clone: set default filter with --partial

[Derrick Stolee via GitGitGadget]

From: Derrick Stolee <dstolee@microsoft.com>

Partial clone means a lot of different things, including filtering
out all blobs, large blobs, or objects along a certain pathspec.
The pathspec option has limited uses, in particular due to the
performance challenges in serving with such filters. The blob size
option can be helpful for repositories with a small number of large
binaries, but otherwise it is difficult to find a meaningful split
between "small" and "large" blobs.

When I think of or recommend partial clone, I specifically mention
the case of filtering out all blobs, and downloading those blobs
only as needed.

This case is extremely useful, since it takes the best part of
shallow clone (a very small initial download) without any of the
downsides of restricted history.

However, the command-line interface can be confusing:

	git clone --filter=blob:none <url>

Add a simpler "--partial" option that defaults to this case:

	git clone --partial <url>

This should make the feature more discoverable. However, there is
a significant interest in the size-limited filters as that behaves
very similarly to Git LFS. For those cases, the following is
available:

	git clone --partial=<size> <url>

There are quite a few commands using OPT_PARSE_LIST_OBJECTS_FILTER,
includeing clone, fetch, and pack-objects. Augment this macro to
include the "--partial[=<size>]" mode for free.

Modify the first partial clone test that checks --filter=blob:none
to also check --partial with the same expected conditions after
clone. The diff is much simpler to see when ignoring whitespace,
since several lines added a leading tab. This test is essentially
copied to include the two ways to specify a blob size limit of
one byte.

Signed-off-by: Derrick Stolee <dstolee@microsoft.com>
---
 list-objects-filter-options.c | 18 +++++++++++++++
 list-objects-filter-options.h |  8 ++++++-
 t/t5616-partial-clone.sh      | 42 ++++++++++++++++++++++++++---------
 3 files changed, 57 insertions(+), 11 deletions(-)

diff --git a/list-objects-filter-options.c b/list-objects-filter-options.c
index 256bcfbdfe6..a71716ef75e 100644
--- a/list-objects-filter-options.c
+++ b/list-objects-filter-options.c
@@ -270,6 +270,24 @@ int opt_parse_list_objects_filter(const struct option *opt,
 	return 0;
 }
 
+int opt_set_blob_none_filter(const struct option *opt,
+			     const char *arg, int unset)
+{
+	struct strbuf filter_arg = STRBUF_INIT;
+	struct list_objects_filter_options *filter_options = opt->value;
+	
+	if (unset || !arg || !strcmp(arg, "0")) {
+		parse_list_objects_filter(filter_options, "blob:none");
+		return 0;
+	}
+	
+	strbuf_addf(&filter_arg, "blob:limit=%s", arg);
+	parse_list_objects_filter(filter_options, filter_arg.buf);
+	strbuf_release(&filter_arg);
+
+	return 0;
+}
+
 const char *list_objects_filter_spec(struct list_objects_filter_options *filter)
 {
 	if (!filter->filter_spec.nr)
diff --git a/list-objects-filter-options.h b/list-objects-filter-options.h
index 2ffb39222c4..ac38ffcbe86 100644
--- a/list-objects-filter-options.h
+++ b/list-objects-filter-options.h
@@ -62,6 +62,7 @@ struct list_objects_filter_options {
 
 /* Normalized command line arguments */
 #define CL_ARG__FILTER "filter"
+#define CL_ARG__PARTIAL "partial"
 
 void list_objects_filter_die_if_populated(
 	struct list_objects_filter_options *filter_options);
@@ -80,11 +81,16 @@ void parse_list_objects_filter(
 
 int opt_parse_list_objects_filter(const struct option *opt,
 				  const char *arg, int unset);
+int opt_set_blob_none_filter(const struct option *opt,
+			     const char *arg, int unset);
 
 #define OPT_PARSE_LIST_OBJECTS_FILTER(fo) \
 	{ OPTION_CALLBACK, 0, CL_ARG__FILTER, fo, N_("args"), \
 	  N_("object filtering"), 0, \
-	  opt_parse_list_objects_filter }
+	  opt_parse_list_objects_filter }, \
+	{ OPTION_CALLBACK, 0, CL_ARG__PARTIAL, fo, N_("size"), \
+	  N_("partial clone with blob filter"), \
+	  PARSE_OPT_OPTARG | PARSE_OPT_NONEG , opt_set_blob_none_filter }
 
 /*
  * Translates abbreviated numbers in the filter's filter_spec into their
diff --git a/t/t5616-partial-clone.sh b/t/t5616-partial-clone.sh
index 77bb91e9769..c42cef61296 100755
--- a/t/t5616-partial-clone.sh
+++ b/t/t5616-partial-clone.sh
@@ -33,17 +33,39 @@ test_expect_success 'setup bare clone for server' '
 # confirm we are missing all of the known blobs.
 # confirm partial clone was registered in the local config.
 test_expect_success 'do partial clone 1' '
-	git clone --no-checkout --filter=blob:none "file://$(pwd)/srv.bare" pc1 &&
-
-	git -C pc1 rev-list --quiet --objects --missing=print HEAD >revs &&
-	awk -f print_1.awk revs |
-	sed "s/?//" |
-	sort >observed.oids &&
+	for option in "--filter=blob:none" "--partial"
+	do
+		rm -rf pc1 &&
+		git clone --no-checkout "$option" "file://$(pwd)/srv.bare" pc1 &&
+
+		git -C pc1 rev-list --quiet --objects --missing=print HEAD >revs &&
+		awk -f print_1.awk revs |
+		sed "s/?//" |
+		sort >observed.oids &&
+
+		test_cmp expect_1.oids observed.oids &&
+		test "$(git -C pc1 config --local core.repositoryformatversion)" = "1" &&
+		test "$(git -C pc1 config --local remote.origin.promisor)" = "true" &&
+		test "$(git -C pc1 config --local remote.origin.partialclonefilter)" = "blob:none"
+	done
+'
 
-	test_cmp expect_1.oids observed.oids &&
-	test "$(git -C pc1 config --local core.repositoryformatversion)" = "1" &&
-	test "$(git -C pc1 config --local remote.origin.promisor)" = "true" &&
-	test "$(git -C pc1 config --local remote.origin.partialclonefilter)" = "blob:none"
+test_expect_success 'do partial clone with size limit' '
+	for option in "--filter=blob:limit=1" "--partial=1"
+	do
+		rm -rf pc-limit &&
+		git clone --no-checkout "$option" "file://$(pwd)/srv.bare" pc-limit &&
+
+		git -C pc-limit rev-list --quiet --objects --missing=print HEAD >revs &&
+		awk -f print_1.awk revs |
+		sed "s/?//" |
+		sort >observed.oids &&
+
+		test_cmp expect_1.oids observed.oids &&
+		test "$(git -C pc-limit config --local core.repositoryformatversion)" = "1" &&
+		test "$(git -C pc-limit config --local remote.origin.promisor)" = "true" &&
+		test "$(git -C pc-limit config --local remote.origin.partialclonefilter)" = "blob:limit=1"
+	done
 '
 
 test_expect_success 'verify that .promisor file contains refs fetched' '
-- 
gitgitgadget

[PATCH v2 2/3] clone: document --partial and --filter options

[Derrick Stolee via GitGitGadget]

From: Derrick Stolee <dstolee@microsoft.com>

The previous change added the "--partial[=<size>]" option to
"git clone" equivalent to "--filter=blob:none" or
"--filter=blob:limit=<size>" but did not document that addition.
It turns out that the "--filter=<filter-spec>" option was not
documented anywhere in the "git clone" page, and instead is
detailed carefully in "git rev-list" where it serves a
different purpose.

Add a small bit about these options in the documentation. It
would be worth some time to create a subsection in the "git clone"
documentation about partial clone as a concept and how it can be
a surprising experience. For example, "git checkout" will likely
trigger a pack download.

Signed-off-by: Derrick Stolee <dstolee@microsoft.com>
---
 Documentation/git-clone.txt | 15 ++++++++++++++-
 1 file changed, 14 insertions(+), 1 deletion(-)

diff --git a/Documentation/git-clone.txt b/Documentation/git-clone.txt
index bf24f1813ad..eafa1c39927 100644
--- a/Documentation/git-clone.txt
+++ b/Documentation/git-clone.txt
@@ -15,7 +15,8 @@ SYNOPSIS
 	  [--dissociate] [--separate-git-dir <git dir>]
 	  [--depth <depth>] [--[no-]single-branch] [--no-tags]
 	  [--recurse-submodules[=<pathspec>]] [--[no-]shallow-submodules]
-	  [--[no-]remote-submodules] [--jobs <n>] [--sparse] [--] <repository>
+	  [--[no-]remote-submodules] [--jobs <n>] [--sparse]
+	  [--partial[=<size>]|--filter=<filter>] [--] <repository>
 	  [<directory>]
 
 DESCRIPTION
@@ -162,6 +163,18 @@ objects from the source repository into a pack in the cloned repository.
 	of the repository. The sparse-checkout file can be
 	modified to grow the working directory as needed.
 
+--partial[=<size>]::
+--filter=<filter-spec>::
+	Use the partial clone feature and request that the server sends
+	a subset of reachable objects according to a given object filter.
+	When using `--filter`, the supplied `<filter-spec>` is used for
+	the partial clone filter. When using `--partial` with no `<size>`,
+	the `blob:none` filter is applied to filter all blobs. When using
+	`--partial=<size>` the `blob:limit=<size>` filter is applied to
+	filter all blobs with size larger than `<size>`. For more details
+	on filter specifications, see the `--filter` option in
+	linkgit:git-rev-list[1].
+
 --mirror::
 	Set up a mirror of the source repository.  This implies `--bare`.
 	Compared to `--bare`, `--mirror` not only maps local branches of the
-- 
gitgitgadget

[PATCH v2 3/3] clone: document partial clone section

[Dyrone Teng via GitGitGadget]

From: Dyrone Teng <dyroneteng@gmail.com>

Partial clones are created using 'git clone', but there is no related
help information in the git-clone documentation. Add a relevant section
to help users understand what partial clones are and how they differ
from normal clones.

The section briefly introduces the applicable scenarios and some
precautions of partial clone. If users want to know more about its
technical design and other details, users can view the link of
git-partial-clone(7) according to the guidelines in the section.

Signed-off-by: Dyrone Teng <dyroneteng@gmail.com>
---
 Documentation/git-clone.txt | 72 +++++++++++++++++++++++++++++++++++++
 1 file changed, 72 insertions(+)

diff --git a/Documentation/git-clone.txt b/Documentation/git-clone.txt
index eafa1c39927..a6e13666ea1 100644
--- a/Documentation/git-clone.txt
+++ b/Documentation/git-clone.txt
@@ -310,6 +310,78 @@ or `--mirror` is given)
 	for `host.xz:foo/.git`).  Cloning into an existing directory
 	is only allowed if the directory is empty.
 
+Partial Clone
+-------------
+
+By default, `git clone` will download every reachable object, including
+every version of every file in the history of the repository. The
+**partial clone** feature allows Git to transfer fewer objects and
+request them from the remote only when they are needed, so some
+reachable objects can be omitted from the initial `git clone` and
+subsequent `git fetch` operations.
+
+To use the partial clone feature, you can run `git clone` with the 
+`--filter=<filter-spec>` option. If you want to clone a repository
+without download any blobs, the form `filter=blob:none` will omit all
+the blobs. If the repository has some large blobs and you want to
+prevent some large blobs being downloaded by an appropriate threshold,
+the form `--filter=blob:limit=<n>[kmg]`omits blobs larger than n bytes
+or units (see linkgit:git-rev-list[1]).
+
+As mentioned before, a partially cloned repository may have to request
+the missing objects when they are needed. So some 'local' commands may
+fail without a network connection to the remote repository.
+
+For example, The <repository> contains two branches which names 'master'
+and 'topic. Then, we clone the repository by
+
+    $ git clone --filter=blob:none --no-checkout <repository>
+
+With the `--filter=blob:none` option Git will omit all the blobs and
+the `--no-checkout` option Git will not perform a checkout of HEAD
+after the clone is complete. Then, we check out the remote tracking
+'topic' branch by
+
+    $ git checkout -b topic origin/topic 
+
+The output looks like
+
+------------
+    remote: Enumerating objects: 1, done.
+    remote: Counting objects: 100% (1/1), done.
+    remote: Total 1 (delta 0), reused 0 (delta 0), pack-reused 0
+    Receiving objects: 100% (1/1), 43 bytes | 43.00 KiB/s, done.
+    Branch 'topic' set up to track remote branch 'topic' from 'origin'.
+    Switched to a new branch 'topic'
+------------
+
+The output is a bit surprising but it shows how partial clone works.
+When we check out the branch 'topic' Git will request the missing blobs
+because they are needed. Then, We can switch back to branch 'master' by
+
+    $ git checkout master
+
+This time the output looks like
+
+------------
+    Switched to branch 'master'
+    Your branch is up to date with 'origin/master'.
+------------
+
+It shows that when we switch back to the previous location, the checkout
+is done without a download because the repository has all the blobs that
+were downloaded previously.
+
+`git log` may also make a surprise with partial clones. `git log
+-- <pathspec>` will not cause downloads with the blob filters, because
+it's only reading commits and trees. In addition to any options that
+require git to look at the contents of blobs, like "-p" and "--stat"
+, options that cause git to report pathnames, like "--summary" and
+"--raw", will trigger lazy/on-demand fetching of blobs, as they are
+needed to detect inexact renames.
+
+linkgit:partial-clone[1]
+
 :git-clone: 1
 include::urls.txt[]
 
-- 
gitgitgadget

Re: [PATCH v2 0/3] clone: document partial clone section

[Junio C Hamano]

"Teng Long via GitGitGadget" <gitgitgadget@gmail.com> writes:

> Partial clones are created using 'git clone', but there is no related help
> information in the git-clone documentation during a period. Add a relevant
> section to help users understand what partial clones are and how they differ
> from normal clones.
>
> The section briefly introduces the applicable scenarios and some precautions
> of partial clone. If users want to know more about its technical design and
> other details, users can view the link of git-partial-clone(7) according to
> the guidelines in the section.
>
> Derrick Stolee (2):
>   partial-clone: set default filter with --partial
>   clone: document --partial and --filter options
>
> Dyrone Teng (1):
>   clone: document partial clone section

> base-commit: 6c85aac65fb455af85745130ce35ddae4678db84
> Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-745%2Fdyrone%2Fmaster-v2
> Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-745/dyrone/master-v2
> Pull-Request: https://github.com/git/git/pull/745
>
> Range-diff vs v1:

Can you remind readers which thread was the v1?  Hopefully it is not
this one, right?

  https://lore.kernel.org/git/20200322192234.GC671552@coredump.intra.peff.net/

it concluded that it is not a great idea to set default filter with
"--partial", and the discussion led to a v2 with a reduced scope at

  https://lore.kernel.org/git/pull.586.v2.git.1584906606469.gitgitgadget@gmail.com/

and that one is already cooking.

>  -:  ----------- > 1:  6f340d9aadf partial-clone: set default filter with --partial
>  -:  ----------- > 2:  9baf4c8ba38 clone: document --partial and --filter options
>  1:  f063efa545b ! 3:  c1a44a35095 clone: document partial clone section

Thanks.

Re: [PATCH v2 0/3] clone: document partial clone section

[Derrick Stolee]

On 4/13/2020 11:25 AM, Teng Long via GitGitGadget wrote:
> Derrick Stolee (2):
>   partial-clone: set default filter with --partial
>   clone: document --partial and --filter options

I believe these two commits got submitted by accident, as they were in my branch before and then were removed based on feedback from the list [1].

Dyrone: before sending your next version, please eject these two commits. You can do this with "git rebase --onto HEAD~3 HEAD~1 <branchname>".

Thanks,
-Stolee

[1] https://lore.kernel.org/git/pull.586.v2.git.1584906606469.gitgitgadget@gmail.com/

Re: [PATCH v2 0/3] clone: document partial clone section

[Derrick Stolee]

On 4/13/2020 6:45 PM, Junio C Hamano wrote:
> "Teng Long via GitGitGadget" <gitgitgadget@gmail.com> writes:
> 
>> Partial clones are created using 'git clone', but there is no related help
>> information in the git-clone documentation during a period. Add a relevant
>> section to help users understand what partial clones are and how they differ
>> from normal clones.
>>
>> The section briefly introduces the applicable scenarios and some precautions
>> of partial clone. If users want to know more about its technical design and
>> other details, users can view the link of git-partial-clone(7) according to
>> the guidelines in the section.
>>
>> Derrick Stolee (2):
>>   partial-clone: set default filter with --partial
>>   clone: document --partial and --filter options
>>
>> Dyrone Teng (1):
>>   clone: document partial clone section
> 
>> base-commit: 6c85aac65fb455af85745130ce35ddae4678db84
>> Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-745%2Fdyrone%2Fmaster-v2
>> Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-745/dyrone/master-v2
>> Pull-Request: https://github.com/git/git/pull/745
>>
>> Range-diff vs v1:
> 
> Can you remind readers which thread was the v1?  Hopefully it is not
> this one, right?
> 
>   https://lore.kernel.org/git/20200322192234.GC671552@coredump.intra.peff.net/
> 
> it concluded that it is not a great idea to set default filter with
> "--partial", and the discussion led to a v2 with a reduced scope at
> 
>   https://lore.kernel.org/git/pull.586.v2.git.1584906606469.gitgitgadget@gmail.com/
> 
> and that one is already cooking.

Yes, sorry about that. I started working with Dyrone on this
when my v1 was still being reviewed, so his commits are based
on that branch. Then when I force-pushed my branch his GGG PR
"grew" with the old commits.

Thanks,
-Stolee

Re: [PATCH v2 0/3] clone: document partial clone section

[Junio C Hamano]

Derrick Stolee <stolee@gmail.com> writes:

> ... Then when I force-pushed my branch his GGG PR
> "grew" with the old commits.

Ah, so we only need to review [3/3], treating it as a single patch
series?

Thanks.

Re: [PATCH v2 0/3] clone: document partial clone section

[Derrick Stolee]

On 4/14/2020 12:25 PM, Junio C Hamano wrote:
> Derrick Stolee <stolee@gmail.com> writes:
> 
>> ... Then when I force-pushed my branch his GGG PR
>> "grew" with the old commits.
> 
> Ah, so we only need to review [3/3], treating it as a single patch
> series?

Correct. Thanks.

-Stolee

[PATCH v3] clone: document partial clone section

[Teng Long via GitGitGadget]

From: Dyrone Teng <dyroneteng@gmail.com>

Partial clones are created using 'git clone', but there is no related
help information in the git-clone documentation during a period. Add
a relevant section to help users understand what partial clones are
and how they differ from normal clones.

The section briefly introduces the applicable scenarios and some
precautions of partial clone. If users want to know more about its
technical design and other details, users can view the link of
git-partial-clone(7) according to the guidelines in the section.

Signed-off-by: Teng Long <dyroneteng@gmail.com>
---
    clone: document partial clone section
    
    Partial clones are created using 'git clone', but there is no related
    help information in the git-clone documentation during a period. Add a
    relevant section to help users understand what partial clones are and
    how they differ from normal clones.
    
    The section briefly introduces the applicable scenarios and some
    precautions of partial clone. If users want to know more about its
    technical design and other details, users can view the link of
    git-partial-clone(7) according to the guidelines in the section.

Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-745%2Fdyrone%2Fmaster-v3
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-745/dyrone/master-v3
Pull-Request: https://github.com/git/git/pull/745

Range-diff vs v2:

 1:  6f340d9aad < -:  ---------- partial-clone: set default filter with --partial
 2:  9baf4c8ba3 < -:  ---------- clone: document --partial and --filter options
 3:  c1a44a3509 ! 1:  681c5dcb79 clone: document partial clone section
     @@ Commit message
          clone: document partial clone section
      
          Partial clones are created using 'git clone', but there is no related
     -    help information in the git-clone documentation. Add a relevant section
     -    to help users understand what partial clones are and how they differ
     -    from normal clones.
     +    help information in the git-clone documentation during a period. Add
     +    a relevant section to help users understand what partial clones are
     +    and how they differ from normal clones.
      
          The section briefly introduces the applicable scenarios and some
          precautions of partial clone. If users want to know more about its
          technical design and other details, users can view the link of
          git-partial-clone(7) according to the guidelines in the section.
      
     -    Signed-off-by: Dyrone Teng <dyroneteng@gmail.com>
     +    Signed-off-by: Teng Long <dyroneteng@gmail.com>
      
       ## Documentation/git-clone.txt ##
      @@ Documentation/git-clone.txt: or `--mirror` is given)
     @@ Documentation/git-clone.txt: or `--mirror` is given)
      +-------------
      +
      +By default, `git clone` will download every reachable object, including
     -+every version of every file in the history of the repository. The
     -+**partial clone** feature allows Git to transfer fewer objects and
     -+request them from the remote only when they are needed, so some
     -+reachable objects can be omitted from the initial `git clone` and
     -+subsequent `git fetch` operations.
     ++every version of every file in the history of the repository. The **partial clone**
     ++feature allows Git to transfer fewer objects and request them from the
     ++remote only when they are needed, so some reachable objects can be
     ++omitted from the initial `git clone` and subsequent `git fetch`
     ++operations. In this way, a partial clone can reduce the network traffic
     ++costs and disk space usage when git is working under a large repository.
      +
      +To use the partial clone feature, you can run `git clone` with the 
     -+`--filter=<filter-spec>` option. If you want to clone a repository
     -+without download any blobs, the form `filter=blob:none` will omit all
     -+the blobs. If the repository has some large blobs and you want to
     -+prevent some large blobs being downloaded by an appropriate threshold,
     -+the form `--filter=blob:limit=<n>[kmg]`omits blobs larger than n bytes
     -+or units (see linkgit:git-rev-list[1]).
     ++`--filter=<filter-spec>` option. If the repository has a deep history
     ++and you don't want to download any blobs, the form `filter=blob:none`
     ++will omit all the blobs. If the repository has some large blobs and you
     ++want to prevent some large blobs being downloaded by an appropriate
     ++threshold, the form `--filter=blob:limit=<n>[kmg]` omits blobs larger
     ++than n bytes or units (see linkgit:git-rev-list[1]).
      +
     -+As mentioned before, a partially cloned repository may have to request
     -+the missing objects when they are needed. So some 'local' commands may
     -+fail without a network connection to the remote repository.
     ++When using a partial clone, Git will request missing objects from the
     ++remote(s) when necessary. Several commands that do not involve a request
     ++over a network may now trigger these requests.
      +
      +For example, The <repository> contains two branches which names 'master'
      +and 'topic. Then, we clone the repository by
     @@ Documentation/git-clone.txt: or `--mirror` is given)
      +were downloaded previously.
      +
      +`git log` may also make a surprise with partial clones. `git log
     -+-- <pathspec>` will not cause downloads with the blob filters, because
     -+it's only reading commits and trees. In addition to any options that
     -+require git to look at the contents of blobs, like "-p" and "--stat"
     -+, options that cause git to report pathnames, like "--summary" and
     -+"--raw", will trigger lazy/on-demand fetching of blobs, as they are
     -+needed to detect inexact renames.
     -+
     -+linkgit:partial-clone[1]
     ++--<path>` will not cause downloads with the blob filters, because it's
     ++only reading commits. `git log -p -- <path>` will download blobs to
     ++generate the patch output and git log --raw will download all blobs
     ++that changed at recent commits in order to compute renames.
      +
       :git-clone: 1
       include::urls.txt[]


 Documentation/git-clone.txt | 69 +++++++++++++++++++++++++++++++++++++
 1 file changed, 69 insertions(+)

diff --git a/Documentation/git-clone.txt b/Documentation/git-clone.txt
index c898310099..15495675a8 100644
--- a/Documentation/git-clone.txt
+++ b/Documentation/git-clone.txt
@@ -308,6 +308,75 @@ or `--mirror` is given)
 	for `host.xz:foo/.git`).  Cloning into an existing directory
 	is only allowed if the directory is empty.
 
+Partial Clone
+-------------
+
+By default, `git clone` will download every reachable object, including
+every version of every file in the history of the repository. The **partial clone**
+feature allows Git to transfer fewer objects and request them from the
+remote only when they are needed, so some reachable objects can be
+omitted from the initial `git clone` and subsequent `git fetch`
+operations. In this way, a partial clone can reduce the network traffic
+costs and disk space usage when git is working under a large repository.
+
+To use the partial clone feature, you can run `git clone` with the 
+`--filter=<filter-spec>` option. If the repository has a deep history
+and you don't want to download any blobs, the form `filter=blob:none`
+will omit all the blobs. If the repository has some large blobs and you
+want to prevent some large blobs being downloaded by an appropriate
+threshold, the form `--filter=blob:limit=<n>[kmg]` omits blobs larger
+than n bytes or units (see linkgit:git-rev-list[1]).
+
+When using a partial clone, Git will request missing objects from the
+remote(s) when necessary. Several commands that do not involve a request
+over a network may now trigger these requests.
+
+For example, The <repository> contains two branches which names 'master'
+and 'topic. Then, we clone the repository by
+
+    $ git clone --filter=blob:none --no-checkout <repository>
+
+With the `--filter=blob:none` option Git will omit all the blobs and
+the `--no-checkout` option Git will not perform a checkout of HEAD
+after the clone is complete. Then, we check out the remote tracking
+'topic' branch by
+
+    $ git checkout -b topic origin/topic 
+
+The output looks like
+
+------------
+    remote: Enumerating objects: 1, done.
+    remote: Counting objects: 100% (1/1), done.
+    remote: Total 1 (delta 0), reused 0 (delta 0), pack-reused 0
+    Receiving objects: 100% (1/1), 43 bytes | 43.00 KiB/s, done.
+    Branch 'topic' set up to track remote branch 'topic' from 'origin'.
+    Switched to a new branch 'topic'
+------------
+
+The output is a bit surprising but it shows how partial clone works.
+When we check out the branch 'topic' Git will request the missing blobs
+because they are needed. Then, We can switch back to branch 'master' by
+
+    $ git checkout master
+
+This time the output looks like
+
+------------
+    Switched to branch 'master'
+    Your branch is up to date with 'origin/master'.
+------------
+
+It shows that when we switch back to the previous location, the checkout
+is done without a download because the repository has all the blobs that
+were downloaded previously.
+
+`git log` may also make a surprise with partial clones. `git log
+--<path>` will not cause downloads with the blob filters, because it's
+only reading commits. `git log -p -- <path>` will download blobs to
+generate the patch output and git log --raw will download all blobs
+that changed at recent commits in order to compute renames.
+
 :git-clone: 1
 include::urls.txt[]
 

base-commit: e1cfff676549cdcd702cbac105468723ef2722f4
-- 
gitgitgadget

Re: [PATCH v3] clone: document partial clone section

[Philippe Blain]

Hi Dyrone,

> Le 26 oct. 2020 à 23:12, Teng Long via GitGitGadget <gitgitgadget@gmail.com> a écrit :
> 
> From: Dyrone Teng <dyroneteng@gmail.com>
> 
> Partial clones are created using 'git clone', but there is no related
> help information in the git-clone documentation during a period. Add
> a relevant section to help users understand what partial clones are
> and how they differ from normal clones.
> 
> The section briefly introduces the applicable scenarios and some
> precautions of partial clone. If users want to know more about its
> technical design and other details, users can view the link of
> git-partial-clone(7) according to the guidelines in the section.
> 
> Signed-off-by: Teng Long <dyroneteng@gmail.com>
> ---
>    clone: document partial clone section
> 
>    Partial clones are created using 'git clone', but there is no related
>    help information in the git-clone documentation during a period. Add a
>    relevant section to help users understand what partial clones are and
>    how they differ from normal clones.
> 
>    The section briefly introduces the applicable scenarios and some
>    precautions of partial clone. If users want to know more about its
>    technical design and other details, users can view the link of
>    git-partial-clone(7) according to the guidelines in the section.

Since your series has just the one patch now, you don't need to add a description
in your GitGitGadget (GGG) PR. That's why it appears two times here:
the text above the '---' is the commit message, and the text below is the PR description.
In the context of a one-patch series, you can use this space to add additional info that 
do not fit into the commit message, for example questions about your patch, etc.
It is also a good idea (and viewed positively by reviewers) to use it to add a summary of what changed
in your series since the last version you sent. I encourage you to read MyFirstContribution [1]
for a good tutorial on the contribution process. Also, GGG understands that if you end your
PR description with a line starting with "CC:" and an email address, further iterations of your 
series will be sent to those email addresses. So it would have been good to add Stolee in there, like this:

CC: Derrick Stolee <stolee@gmail.com>

(Junio prefers not to be directly CC'ed).

> Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-745%2Fdyrone%2Fmaster-v3
> Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-745/dyrone/master-v3
> Pull-Request: https://github.com/git/git/pull/745
> 
> Range-diff vs v2:
> 
> 1:  6f340d9aad < -:  ---------- partial-clone: set default filter with --partial
> 2:  9baf4c8ba3 < -:  ---------- clone: document --partial and --filter options
> 3:  c1a44a3509 ! 1:  681c5dcb79 clone: document partial clone section
>     @@ Commit message
>          clone: document partial clone section
> 
>          Partial clones are created using 'git clone', but there is no related
>     -    help information in the git-clone documentation. Add a relevant section
>     -    to help users understand what partial clones are and how they differ
>     -    from normal clones.
>     +    help information in the git-clone documentation during a period. Add
>     +    a relevant section to help users understand what partial clones are
>     +    and how they differ from normal clones.

It appears that you sent the same version of the patch as in v1, instead
of the one you sent in v2 ? You had removed "during a period"  for v2, 
but here it pops up again. You should check that you've sent the more 
up to date version of your patch, before sending v4.

I will not comment on the patch below, since it's not the more up-to-date.
I will send comments shortly on the v2 version by replying to [2] (the v2 version 
of your patch).

Cheers,

Philippe.

[1] https://git-scm.com/docs/MyFirstContribution
[2] https://lore.kernel.org/git/c1a44a35095e7d681c312ecaa07c46e49f2fae67.1586791560.git.gitgitgadget@gmail.com/

Re: [PATCH v2 3/3] clone: document partial clone section

[Philippe Blain]

Hi Dyrone, 

> Le 13 avr. 2020 à 11:26, Dyrone Teng via GitGitGadget <gitgitgadget@gmail.com> a écrit :
> 
> From: Dyrone Teng <dyroneteng@gmail.com>
> 
> Partial clones are created using 'git clone', but there is no related
> help information in the git-clone documentation. Add a relevant section
> to help users understand what partial clones are and how they differ
> from normal clones.
> 
> The section briefly introduces the applicable scenarios and some
> precautions of partial clone.

"some precautions users should take when using partial clone" 
would read better, I think.

> If users want to know more about its
> technical design and other details, users can view the link of
> git-partial-clone(7) according to the guidelines in the section.

Note: git-partial-clone(7) does not exist, i.e., there is document
named 'gitpartial-clone.txt' in 'Documentation/ 'that is listed in the 'MAN7_TXT'
variable of the documentation Makefile. What exists is a document called
'partial-clone.txt' in the 'technical' folder of the documentation.
You can do `git grep 'technical/' in 'Documentation/' to see how these pages
are referred to in the rest of the documentation.

Also, the wording could be better:

"In case users want to know more about the technical design of the partial clone
feature, add a link to 'technical/partial-clone.txt'."

would be sufficient.

> 
> Signed-off-by: Dyrone Teng <dyroneteng@gmail.com>
> ---
> Documentation/git-clone.txt | 72 +++++++++++++++++++++++++++++++++++++
> 1 file changed, 72 insertions(+)
> 
> diff --git a/Documentation/git-clone.txt b/Documentation/git-clone.txt
> index eafa1c39927..a6e13666ea1 100644
> --- a/Documentation/git-clone.txt
> +++ b/Documentation/git-clone.txt
> @@ -310,6 +310,78 @@ or `--mirror` is given)
> 	for `host.xz:foo/.git`).  Cloning into an existing directory
> 	is only allowed if the directory is empty.
> 
> +Partial Clone
> +-------------
> +
> +By default, `git clone` will download every reachable object, including
> +every version of every file in the history of the repository. The
> +**partial clone** feature allows Git to transfer fewer objects and
> +request them from the remote only when they are needed, so some
> +reachable objects can be omitted from the initial `git clone` and
> +subsequent `git fetch` operations.
> +
> +To use the partial clone feature, you can run `git clone` with the 
> +`--filter=<filter-spec>` option. If you want to clone a repository
> +without download

s/download/downloading/

> any blobs, the form `filter=blob:none` will omit all
> +the blobs. If the repository has some large blobs and you want to
> +prevent some large blobs being downloaded by an appropriate threshold,

repeating "some large blobs" two times here feels a little awkward. Maybe:

"If the repository has some large blobs and you want to prevent them from
being downloaded"

> +the form `--filter=blob:limit=<n>[kmg]`omits blobs larger than n bytes
> +or units (see linkgit:git-rev-list[1]).

I think you could give an example here, and refer to git-rev-list[1] for the full syntax
(also "or units" is a little unclear here). So maybe something like that:

"the form `--filter=blob:limit=1m` would prevent downloading objects bigger than 1 MiB 
(see the description of the `--filter=<filter-spec>` option in linkgit:git-rev-list[1] for the 
full filter syntax)".

> +
> +As mentioned before, a partially cloned repository may have to request
> +the missing objects when they are needed. So some 'local' commands may
> +fail without a network connection to the remote repository.
> +
> +For example, The <repository> contains two branches which names 'master'
> +and 'topic. Then, we clone the repository by

wording, and formatting:

For example, let's say a remote repository contains two branches named 'master'
and 'topic'. We clone the repository with

> +
> +    $ git clone --filter=blob:none --no-checkout <repository>
> +
> +With the `--filter=blob:none` option Git will omit all the blobs and
> +the `--no-checkout` option Git will not perform a checkout of HEAD

some punctuation would help:

With the  `--filter=blob:none` option, Git will omit all the blobs, and
with `--no-checkout`, Git will not checkout `HEAD`

> +after the clone is complete. Then, we check out the remote tracking
> +'topic' branch by

Here you are not checking ou the remote-tracking 'topic' branch,
you are creating a local branch 'topic' that tracks the remote-tracking branch
'origin/topic'.

> +
> +    $ git checkout -b topic origin/topic 
> +
> +The output looks like
> +
> +------------
> +    remote: Enumerating objects: 1, done.
> +    remote: Counting objects: 100% (1/1), done.
> +    remote: Total 1 (delta 0), reused 0 (delta 0), pack-reused 0
> +    Receiving objects: 100% (1/1), 43 bytes | 43.00 KiB/s, done.
> +    Branch 'topic' set up to track remote branch 'topic' from 'origin'.
> +    Switched to a new branch 'topic'
> +------------
> +
> +The output is a bit surprising but it shows how partial clone works.
> +When we check out the branch 'topic' Git will request the missing blobs
> +because they are needed. Then, We

s/We/we/

> can switch back to branch 'master' by
> +
> +    $ git checkout master
> +
> +This time the output looks like
> +
> +------------
> +    Switched to branch 'master'
> +    Your branch is up to date with 'origin/master'.
> +------------
> +
> +It shows that when we switch back to the previous location, the checkout
> +is done without a download because the repository has all the blobs that
> +were downloaded previously.
> +
> +`git log` may also make a surprise with partial clones.

"make a surprise" reads awkward. "have surprising behaviour" would be better.

> `git log
> +-- <pathspec>` will not cause downloads with the blob filters,

I think "if the repository was cloned with `--filter=blob:none`" would be clearer
than "with the blob filters".

> because
> +it's only reading commits and trees. In addition

"However, any options" would be more appropriate than "In addition to" here.

> to any options that
> +require git

s/git/Git/ (and the same thing below)

> to look at the contents of blobs, like "-p" and "--stat"
> +, options

you don't have to spell out "options" again here. And the options
should be enclosed in backticks instead of double quotes.

> that cause git to report pathnames, like "--summary" and
> +"--raw", will trigger lazy/on-demand fetching of blobs, as they are
> +needed to detect inexact renames.
> +
> +linkgit:partial-clone[1]

Again, I'm pretty sure that does not work. You should build the documentation
locally and check that the links you are adding work. "MyFirstContrbution" 
has pointer on how to do that.


Thank you for working on that ! 
It's always great to see people wanting to improve the documentation.

Cheers,

Philippe.

Re: [PATCH v3] clone: document partial clone section

[Junio C Hamano]

Philippe Blain <levraiphilippeblain@gmail.com> writes:

> Hi Dyrone,
>
>> Le 26 oct. 2020 à 23:12, Teng Long via GitGitGadget <gitgitgadget@gmail.com> a écrit :
>> 
>> From: Dyrone Teng <dyroneteng@gmail.com>
>> 
>> Partial clones are created using 'git clone', but there is no related
>> help information in the git-clone documentation during a period. Add
>> a relevant section to help users understand what partial clones are
>> and how they differ from normal clones.
>> 
>> The section briefly introduces the applicable scenarios and some
>> precautions of partial clone. If users want to know more about its
>> technical design and other details, users can view the link of
>> git-partial-clone(7) according to the guidelines in the section.
>> 
>> Signed-off-by: Teng Long <dyroneteng@gmail.com>

Compare this line and "From:" we see above?
They need to match.

>> ---
>>    clone: document partial clone section
>> 
>>    Partial clones are created using 'git clone', but there is no related
>>    help information in the git-clone documentation during a period. Add a
>>    relevant section to help users understand what partial clones are and
>>    how they differ from normal clones.
>> 
>>    The section briefly introduces the applicable scenarios and some
>>    precautions of partial clone. If users want to know more about its
>>    technical design and other details, users can view the link of
>>    git-partial-clone(7) according to the guidelines in the section.
>
> Since your series has just the one patch now, you don't need to
> add a description in your GitGitGadget (GGG) PR. That's why it
> appears two times here: the text above the '---' is the commit
> message, and the text below is the PR description.

Nice.  We learn new things every day---I've always wondered where
the duplicated description we sometimes see comes from.

> In the context of a one-patch series, you can use this space to
> add additional info that do not fit into the commit message, for
> example questions about your patch, etc.  It is also a good idea
> (and viewed positively by reviewers) to use it to add a summary of
> what changed in your series since the last version you sent. I
> encourage you to read MyFirstContribution [1] for a good tutorial
> on the contribution process. Also, GGG understands that if you end
> your PR description with a line starting with "CC:" and an email
> address, further iterations of your series will be sent to those
> email addresses. So it would have been good to add Stolee in
> there, like this:
>
> CC: Derrick Stolee <stolee@gmail.com>

> (Junio prefers not to be directly CC'ed).

... unless it is the "final version with concensus among reviewers",
that is.

>> Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-745%2Fdyrone%2Fmaster-v3
>> Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-745/dyrone/master-v3
>> Pull-Request: https://github.com/git/git/pull/745
>> 
>> Range-diff vs v2:
>> 
>> 1:  6f340d9aad < -:  ---------- partial-clone: set default filter with --partial
>> 2:  9baf4c8ba3 < -:  ---------- clone: document --partial and --filter options
>> 3:  c1a44a3509 ! 1:  681c5dcb79 clone: document partial clone section
>>     @@ Commit message
>>          clone: document partial clone section
>> 
>>          Partial clones are created using 'git clone', but there is no related
>>     -    help information in the git-clone documentation. Add a relevant section
>>     -    to help users understand what partial clones are and how they differ
>>     -    from normal clones.
>>     +    help information in the git-clone documentation during a period. Add
>>     +    a relevant section to help users understand what partial clones are
>>     +    and how they differ from normal clones.
>
> It appears that you sent the same version of the patch as in v1, instead
> of the one you sent in v2 ? You had removed "during a period"  for v2, 
> but here it pops up again. You should check that you've sent the more 
> up to date version of your patch, before sending v4.
>
> I will not comment on the patch below, since it's not the more up-to-date.
> I will send comments shortly on the v2 version by replying to [2] (the v2 version 
> of your patch).
>
> Cheers,
>
> Philippe.
>
> [1] https://git-scm.com/docs/MyFirstContribution
> [2] https://lore.kernel.org/git/c1a44a35095e7d681c312ecaa07c46e49f2fae67.1586791560.git.gitgitgadget@gmail.com/

[PATCH v4] clone: document partial clone section

[Teng Long via GitGitGadget]

From: Teng Long <dyroneteng@gmail.com>

Partial clones are created using 'git clone', but there is no related
help information in the git-clone documentation. Add a relevant section
to help users understand what partial clones are and how they differ
from normal clones.

The section briefly introduces the applicable scenarios and some
precautions of partial clone. If users want to know more about its
technical design and other details, users can view the link of
git-partial-clone(7) according to the guidelines in the section.

Signed-off-by: Teng Long <dyroneteng@gmail.com>
---
    clone: document partial clone section
    
    Partial clones are created using 'git clone', but there is no related
    help information in the git-clone documentation during a period. Add a
    relevant section to help users understand what partial clones are and
    how they differ from normal clones.
    
    The section briefly introduces the applicable scenarios and some
    precautions of partial clone. If users want to know more about its
    technical design and other details, users can view the link of
    git-partial-clone(7) according to the guidelines in the section.

Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-745%2Fdyrone%2Fmaster-v4
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-745/dyrone/master-v4
Pull-Request: https://github.com/git/git/pull/745

Range-diff vs v3:

 1:  681c5dcb7904 ! 1:  6d543cc11378 clone: document partial clone section
     @@
       ## Metadata ##
     -Author: Dyrone Teng <dyroneteng@gmail.com>
     +Author: Teng Long <dyroneteng@gmail.com>
      
       ## Commit message ##
          clone: document partial clone section
      
          Partial clones are created using 'git clone', but there is no related
     -    help information in the git-clone documentation during a period. Add
     -    a relevant section to help users understand what partial clones are
     -    and how they differ from normal clones.
     +    help information in the git-clone documentation. Add a relevant section
     +    to help users understand what partial clones are and how they differ
     +    from normal clones.
      
          The section briefly introduces the applicable scenarios and some
          precautions of partial clone. If users want to know more about its


 Documentation/git-clone.txt | 69 +++++++++++++++++++++++++++++++++++++
 1 file changed, 69 insertions(+)

diff --git a/Documentation/git-clone.txt b/Documentation/git-clone.txt
index c89831009989..15495675a8ce 100644
--- a/Documentation/git-clone.txt
+++ b/Documentation/git-clone.txt
@@ -308,6 +308,75 @@ or `--mirror` is given)
 	for `host.xz:foo/.git`).  Cloning into an existing directory
 	is only allowed if the directory is empty.
 
+Partial Clone
+-------------
+
+By default, `git clone` will download every reachable object, including
+every version of every file in the history of the repository. The **partial clone**
+feature allows Git to transfer fewer objects and request them from the
+remote only when they are needed, so some reachable objects can be
+omitted from the initial `git clone` and subsequent `git fetch`
+operations. In this way, a partial clone can reduce the network traffic
+costs and disk space usage when git is working under a large repository.
+
+To use the partial clone feature, you can run `git clone` with the 
+`--filter=<filter-spec>` option. If the repository has a deep history
+and you don't want to download any blobs, the form `filter=blob:none`
+will omit all the blobs. If the repository has some large blobs and you
+want to prevent some large blobs being downloaded by an appropriate
+threshold, the form `--filter=blob:limit=<n>[kmg]` omits blobs larger
+than n bytes or units (see linkgit:git-rev-list[1]).
+
+When using a partial clone, Git will request missing objects from the
+remote(s) when necessary. Several commands that do not involve a request
+over a network may now trigger these requests.
+
+For example, The <repository> contains two branches which names 'master'
+and 'topic. Then, we clone the repository by
+
+    $ git clone --filter=blob:none --no-checkout <repository>
+
+With the `--filter=blob:none` option Git will omit all the blobs and
+the `--no-checkout` option Git will not perform a checkout of HEAD
+after the clone is complete. Then, we check out the remote tracking
+'topic' branch by
+
+    $ git checkout -b topic origin/topic 
+
+The output looks like
+
+------------
+    remote: Enumerating objects: 1, done.
+    remote: Counting objects: 100% (1/1), done.
+    remote: Total 1 (delta 0), reused 0 (delta 0), pack-reused 0
+    Receiving objects: 100% (1/1), 43 bytes | 43.00 KiB/s, done.
+    Branch 'topic' set up to track remote branch 'topic' from 'origin'.
+    Switched to a new branch 'topic'
+------------
+
+The output is a bit surprising but it shows how partial clone works.
+When we check out the branch 'topic' Git will request the missing blobs
+because they are needed. Then, We can switch back to branch 'master' by
+
+    $ git checkout master
+
+This time the output looks like
+
+------------
+    Switched to branch 'master'
+    Your branch is up to date with 'origin/master'.
+------------
+
+It shows that when we switch back to the previous location, the checkout
+is done without a download because the repository has all the blobs that
+were downloaded previously.
+
+`git log` may also make a surprise with partial clones. `git log
+--<path>` will not cause downloads with the blob filters, because it's
+only reading commits. `git log -p -- <path>` will download blobs to
+generate the patch output and git log --raw will download all blobs
+that changed at recent commits in order to compute renames.
+
 :git-clone: 1
 include::urls.txt[]
 

base-commit: e1cfff676549cdcd702cbac105468723ef2722f4
-- 
gitgitgadget

Re: [PATCH v4] clone: document partial clone section

[Philippe Blain]

Hi Dyrone,

Le 2021-02-25 à 04:13, Teng Long via GitGitGadget a écrit :
> From: Teng Long <dyroneteng@gmail.com>
> 
> Partial clones are created using 'git clone', but there is no related
> help information in the git-clone documentation. Add a relevant section
> to help users understand what partial clones are and how they differ
> from normal clones.
> 
> The section briefly introduces the applicable scenarios and some
> precautions of partial clone. If users want to know more about its
> technical design and other details, users can view the link of
> git-partial-clone(7) according to the guidelines in the section.
> 
> Signed-off-by: Teng Long <dyroneteng@gmail.com>
> ---
>      clone: document partial clone section
>      
>      Partial clones are created using 'git clone', but there is no related
>      help information in the git-clone documentation during a period. Add a
>      relevant section to help users understand what partial clones are and
>      how they differ from normal clones.
>      
>      The section briefly introduces the applicable scenarios and some
>      precautions of partial clone. If users want to know more about its
>      technical design and other details, users can view the link of
>      git-partial-clone(7) according to the guidelines in the section.
> 
> Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-745%2Fdyrone%2Fmaster-v4
> Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-745/dyrone/master-v4
> Pull-Request: https://github.com/git/git/pull/745
> 
> Range-diff vs v3:
> 
>   1:  681c5dcb7904 ! 1:  6d543cc11378 clone: document partial clone section
>       @@
>         ## Metadata ##
>       -Author: Dyrone Teng <dyroneteng@gmail.com>
>       +Author: Teng Long <dyroneteng@gmail.com>
>        
>         ## Commit message ##
>            clone: document partial clone section
>        
>            Partial clones are created using 'git clone', but there is no related
>       -    help information in the git-clone documentation during a period. Add
>       -    a relevant section to help users understand what partial clones are
>       -    and how they differ from normal clones.
>       +    help information in the git-clone documentation. Add a relevant section
>       +    to help users understand what partial clones are and how they differ
>       +    from normal clones.
>        
>            The section briefly introduces the applicable scenarios and some
>            precautions of partial clone. If users want to know more about its

The "range-diff" above is automatically inserted by GitGitGadget and shows what has changed
since the last version you sent (i.e. it compares v3 to v4). So you adressed Junio's comment
about your commit identity and signed-off-by identity needing to match, good.
You also adressed my comment about the wording of the first paragraph of the commit message.
But then I wrote:

However, you did not address all the feedback I sent as a reply to patch 3/3 of v2 (see [1]).
So it would be good to send a v5 with these suggestions incorporated (or, if you do not
agree with a reviewer, you should still answer them and explain why).

Cheers,

Philippe.

[1] https://lore.kernel.org/git/B90939A5-5693-4EB6-8F07-5B50F63B3143@gmail.com/

[PATCH v5] clone: document partial clone section

[Teng Long via GitGitGadget]

From: Dyrone Teng <dyroneteng@gmail.com>

Partial clones are created using 'git clone', but there is no related
help information in the git-clone documentation during a period. Add
a relevant section to help users understand what partial clones are
and how they differ from normal clones.

The section briefly introduces the applicable scenarios and some
precautions of partial clone. If users want to know more about its
technical design and other details, users can view the link of
git-partial-clone(7) according to the guidelines in the section.

Signed-off-by: Teng Long <dyroneteng@gmail.com>
---
    clone: document partial clone section
    
    cc: Philippe Blain levraiphilippeblain@gmail.com

Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-745%2Fdyrone%2Fmaster-v5
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-745/dyrone/master-v5
Pull-Request: https://github.com/git/git/pull/745

Range-diff vs v4:

 1:  6d543cc11378 ! 1:  681c5dcb7904 clone: document partial clone section
     @@
       ## Metadata ##
     -Author: Teng Long <dyroneteng@gmail.com>
     +Author: Dyrone Teng <dyroneteng@gmail.com>
      
       ## Commit message ##
          clone: document partial clone section
      
          Partial clones are created using 'git clone', but there is no related
     -    help information in the git-clone documentation. Add a relevant section
     -    to help users understand what partial clones are and how they differ
     -    from normal clones.
     +    help information in the git-clone documentation during a period. Add
     +    a relevant section to help users understand what partial clones are
     +    and how they differ from normal clones.
      
          The section briefly introduces the applicable scenarios and some
          precautions of partial clone. If users want to know more about its


 Documentation/git-clone.txt | 69 +++++++++++++++++++++++++++++++++++++
 1 file changed, 69 insertions(+)

diff --git a/Documentation/git-clone.txt b/Documentation/git-clone.txt
index c89831009989..15495675a8ce 100644
--- a/Documentation/git-clone.txt
+++ b/Documentation/git-clone.txt
@@ -308,6 +308,75 @@ or `--mirror` is given)
 	for `host.xz:foo/.git`).  Cloning into an existing directory
 	is only allowed if the directory is empty.
 
+Partial Clone
+-------------
+
+By default, `git clone` will download every reachable object, including
+every version of every file in the history of the repository. The **partial clone**
+feature allows Git to transfer fewer objects and request them from the
+remote only when they are needed, so some reachable objects can be
+omitted from the initial `git clone` and subsequent `git fetch`
+operations. In this way, a partial clone can reduce the network traffic
+costs and disk space usage when git is working under a large repository.
+
+To use the partial clone feature, you can run `git clone` with the 
+`--filter=<filter-spec>` option. If the repository has a deep history
+and you don't want to download any blobs, the form `filter=blob:none`
+will omit all the blobs. If the repository has some large blobs and you
+want to prevent some large blobs being downloaded by an appropriate
+threshold, the form `--filter=blob:limit=<n>[kmg]` omits blobs larger
+than n bytes or units (see linkgit:git-rev-list[1]).
+
+When using a partial clone, Git will request missing objects from the
+remote(s) when necessary. Several commands that do not involve a request
+over a network may now trigger these requests.
+
+For example, The <repository> contains two branches which names 'master'
+and 'topic. Then, we clone the repository by
+
+    $ git clone --filter=blob:none --no-checkout <repository>
+
+With the `--filter=blob:none` option Git will omit all the blobs and
+the `--no-checkout` option Git will not perform a checkout of HEAD
+after the clone is complete. Then, we check out the remote tracking
+'topic' branch by
+
+    $ git checkout -b topic origin/topic 
+
+The output looks like
+
+------------
+    remote: Enumerating objects: 1, done.
+    remote: Counting objects: 100% (1/1), done.
+    remote: Total 1 (delta 0), reused 0 (delta 0), pack-reused 0
+    Receiving objects: 100% (1/1), 43 bytes | 43.00 KiB/s, done.
+    Branch 'topic' set up to track remote branch 'topic' from 'origin'.
+    Switched to a new branch 'topic'
+------------
+
+The output is a bit surprising but it shows how partial clone works.
+When we check out the branch 'topic' Git will request the missing blobs
+because they are needed. Then, We can switch back to branch 'master' by
+
+    $ git checkout master
+
+This time the output looks like
+
+------------
+    Switched to branch 'master'
+    Your branch is up to date with 'origin/master'.
+------------
+
+It shows that when we switch back to the previous location, the checkout
+is done without a download because the repository has all the blobs that
+were downloaded previously.
+
+`git log` may also make a surprise with partial clones. `git log
+--<path>` will not cause downloads with the blob filters, because it's
+only reading commits. `git log -p -- <path>` will download blobs to
+generate the patch output and git log --raw will download all blobs
+that changed at recent commits in order to compute renames.
+
 :git-clone: 1
 include::urls.txt[]
 

base-commit: e1cfff676549cdcd702cbac105468723ef2722f4
-- 
gitgitgadget

Re: [PATCH v5] clone: document partial clone section

[Junio C Hamano]

"Teng Long via GitGitGadget" <gitgitgadget@gmail.com> writes:

> From: Dyrone Teng <dyroneteng@gmail.com>
>
> Partial clones are created using 'git clone', but there is no related
> help information in the git-clone documentation during a period. Add
> a relevant section to help users understand what partial clones are
> and how they differ from normal clones.
>
> The section briefly introduces the applicable scenarios and some
> precautions of partial clone. If users want to know more about its
> technical design and other details, users can view the link of
> git-partial-clone(7) according to the guidelines in the section.
>
> Signed-off-by: Teng Long <dyroneteng@gmail.com>
> ---
>     clone: document partial clone section
>     
>     cc: Philippe Blain levraiphilippeblain@gmail.com
>
> Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-745%2Fdyrone%2Fmaster-v5
> Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-745/dyrone/master-v5
> Pull-Request: https://github.com/git/git/pull/745

Puzzlling.

This seems to be identical to v3.  Some "rebase-i / push -f"
accident, or something?

> Range-diff vs v4:
>
>  1:  6d543cc11378 ! 1:  681c5dcb7904 clone: document partial clone section
>      @@
>        ## Metadata ##
>      -Author: Teng Long <dyroneteng@gmail.com>
>      +Author: Dyrone Teng <dyroneteng@gmail.com>
>       
>        ## Commit message ##
>           clone: document partial clone section
>       
>           Partial clones are created using 'git clone', but there is no related
>      -    help information in the git-clone documentation. Add a relevant section
>      -    to help users understand what partial clones are and how they differ
>      -    from normal clones.
>      +    help information in the git-clone documentation during a period. Add
>      +    a relevant section to help users understand what partial clones are
>      +    and how they differ from normal clones.
>       
>           The section briefly introduces the applicable scenarios and some
>           precautions of partial clone. If users want to know more about its
>
>
>  Documentation/git-clone.txt | 69 +++++++++++++++++++++++++++++++++++++
>  1 file changed, 69 insertions(+)
>
> diff --git a/Documentation/git-clone.txt b/Documentation/git-clone.txt
> index c89831009989..15495675a8ce 100644
> --- a/Documentation/git-clone.txt
> +++ b/Documentation/git-clone.txt
> @@ -308,6 +308,75 @@ or `--mirror` is given)
>  	for `host.xz:foo/.git`).  Cloning into an existing directory
>  	is only allowed if the directory is empty.
>  
> +Partial Clone
> +-------------
> +
> +By default, `git clone` will download every reachable object, including
> +every version of every file in the history of the repository. The **partial clone**
> +feature allows Git to transfer fewer objects and request them from the
> +remote only when they are needed, so some reachable objects can be
> +omitted from the initial `git clone` and subsequent `git fetch`
> +operations. In this way, a partial clone can reduce the network traffic
> +costs and disk space usage when git is working under a large repository.
> +
> +To use the partial clone feature, you can run `git clone` with the 
> +`--filter=<filter-spec>` option. If the repository has a deep history
> +and you don't want to download any blobs, the form `filter=blob:none`
> +will omit all the blobs. If the repository has some large blobs and you
> +want to prevent some large blobs being downloaded by an appropriate
> +threshold, the form `--filter=blob:limit=<n>[kmg]` omits blobs larger
> +than n bytes or units (see linkgit:git-rev-list[1]).
> +
> +When using a partial clone, Git will request missing objects from the
> +remote(s) when necessary. Several commands that do not involve a request
> +over a network may now trigger these requests.
> +
> +For example, The <repository> contains two branches which names 'master'
> +and 'topic. Then, we clone the repository by
> +
> +    $ git clone --filter=blob:none --no-checkout <repository>
> +
> +With the `--filter=blob:none` option Git will omit all the blobs and
> +the `--no-checkout` option Git will not perform a checkout of HEAD
> +after the clone is complete. Then, we check out the remote tracking
> +'topic' branch by
> +
> +    $ git checkout -b topic origin/topic 
> +
> +The output looks like
> +
> +------------
> +    remote: Enumerating objects: 1, done.
> +    remote: Counting objects: 100% (1/1), done.
> +    remote: Total 1 (delta 0), reused 0 (delta 0), pack-reused 0
> +    Receiving objects: 100% (1/1), 43 bytes | 43.00 KiB/s, done.
> +    Branch 'topic' set up to track remote branch 'topic' from 'origin'.
> +    Switched to a new branch 'topic'
> +------------
> +
> +The output is a bit surprising but it shows how partial clone works.
> +When we check out the branch 'topic' Git will request the missing blobs
> +because they are needed. Then, We can switch back to branch 'master' by
> +
> +    $ git checkout master
> +
> +This time the output looks like
> +
> +------------
> +    Switched to branch 'master'
> +    Your branch is up to date with 'origin/master'.
> +------------
> +
> +It shows that when we switch back to the previous location, the checkout
> +is done without a download because the repository has all the blobs that
> +were downloaded previously.
> +
> +`git log` may also make a surprise with partial clones. `git log
> +--<path>` will not cause downloads with the blob filters, because it's
> +only reading commits. `git log -p -- <path>` will download blobs to
> +generate the patch output and git log --raw will download all blobs
> +that changed at recent commits in order to compute renames.
> +
>  :git-clone: 1
>  include::urls.txt[]
>  
>
> base-commit: e1cfff676549cdcd702cbac105468723ef2722f4

Fix inconsistent signed-off-by abd author name

[Teng Long]

Teng Long (1):
  clone: document partial clone section

 Documentation/git-clone.txt | 69 +++++++++++++++++++++++++++++++++++++
 1 file changed, 69 insertions(+)

-- 
2.31.1

>Puzzlling.
>
>This seems to be identical to v3.  Some "rebase-i / push -f"
>accident, or something?

To Junio:

I confuse working and non-working user.name, fixed now in newest patch.
Thanks.

[PATCH 1/1] clone: document partial clone section

[Teng Long]

Partial clones are created using 'git clone', but there is no related
help information in the git-clone documentation during a period. Add
a relevant section to help users understand what partial clones are
and how they differ from normal clones.

The section briefly introduces the applicable scenarios and some
precautions of partial clone. If users want to know more about its
technical design and other details, users can view the link of
git-partial-clone(7) according to the guidelines in the section.

Signed-off-by: Teng Long <dyroneteng@gmail.com>
---
 Documentation/git-clone.txt | 69 +++++++++++++++++++++++++++++++++++++
 1 file changed, 69 insertions(+)

diff --git a/Documentation/git-clone.txt b/Documentation/git-clone.txt
index c898310099..15495675a8 100644
--- a/Documentation/git-clone.txt
+++ b/Documentation/git-clone.txt
@@ -308,6 +308,75 @@ or `--mirror` is given)
 	for `host.xz:foo/.git`).  Cloning into an existing directory
 	is only allowed if the directory is empty.
 
+Partial Clone
+-------------
+
+By default, `git clone` will download every reachable object, including
+every version of every file in the history of the repository. The **partial clone**
+feature allows Git to transfer fewer objects and request them from the
+remote only when they are needed, so some reachable objects can be
+omitted from the initial `git clone` and subsequent `git fetch`
+operations. In this way, a partial clone can reduce the network traffic
+costs and disk space usage when git is working under a large repository.
+
+To use the partial clone feature, you can run `git clone` with the 
+`--filter=<filter-spec>` option. If the repository has a deep history
+and you don't want to download any blobs, the form `filter=blob:none`
+will omit all the blobs. If the repository has some large blobs and you
+want to prevent some large blobs being downloaded by an appropriate
+threshold, the form `--filter=blob:limit=<n>[kmg]` omits blobs larger
+than n bytes or units (see linkgit:git-rev-list[1]).
+
+When using a partial clone, Git will request missing objects from the
+remote(s) when necessary. Several commands that do not involve a request
+over a network may now trigger these requests.
+
+For example, The <repository> contains two branches which names 'master'
+and 'topic. Then, we clone the repository by
+
+    $ git clone --filter=blob:none --no-checkout <repository>
+
+With the `--filter=blob:none` option Git will omit all the blobs and
+the `--no-checkout` option Git will not perform a checkout of HEAD
+after the clone is complete. Then, we check out the remote tracking
+'topic' branch by
+
+    $ git checkout -b topic origin/topic 
+
+The output looks like
+
+------------
+    remote: Enumerating objects: 1, done.
+    remote: Counting objects: 100% (1/1), done.
+    remote: Total 1 (delta 0), reused 0 (delta 0), pack-reused 0
+    Receiving objects: 100% (1/1), 43 bytes | 43.00 KiB/s, done.
+    Branch 'topic' set up to track remote branch 'topic' from 'origin'.
+    Switched to a new branch 'topic'
+------------
+
+The output is a bit surprising but it shows how partial clone works.
+When we check out the branch 'topic' Git will request the missing blobs
+because they are needed. Then, We can switch back to branch 'master' by
+
+    $ git checkout master
+
+This time the output looks like
+
+------------
+    Switched to branch 'master'
+    Your branch is up to date with 'origin/master'.
+------------
+
+It shows that when we switch back to the previous location, the checkout
+is done without a download because the repository has all the blobs that
+were downloaded previously.
+
+`git log` may also make a surprise with partial clones. `git log
+--<path>` will not cause downloads with the blob filters, because it's
+only reading commits. `git log -p -- <path>` will download blobs to
+generate the patch output and git log --raw will download all blobs
+that changed at recent commits in order to compute renames.
+
 :git-clone: 1
 include::urls.txt[]
 
-- 
2.31.1

Re: [PATCH 1/1] clone: document partial clone section

[Bagas Sanjaya]

On 06/05/21 13.30, Teng Long wrote:
> Partial clones are created using 'git clone', but there is no related
> help information in the git-clone documentation during a period. Add
> a relevant section to help users understand what partial clones are
> and how they differ from normal clones.
> 
> The section briefly introduces the applicable scenarios and some
> precautions of partial clone. If users want to know more about its
> technical design and other details, users can view the link of
> git-partial-clone(7) according to the guidelines in the section.
> 
> Signed-off-by: Teng Long <dyroneteng@gmail.com>
> ---
>   Documentation/git-clone.txt | 69 +++++++++++++++++++++++++++++++++++++
>   1 file changed, 69 insertions(+)
> 
> diff --git a/Documentation/git-clone.txt b/Documentation/git-clone.txt
> index c898310099..15495675a8 100644
> --- a/Documentation/git-clone.txt
> +++ b/Documentation/git-clone.txt
> @@ -308,6 +308,75 @@ or `--mirror` is given)
>   	for `host.xz:foo/.git`).  Cloning into an existing directory
>   	is only allowed if the directory is empty.
>   
> +Partial Clone
> +-------------
> +
> +By default, `git clone` will download every reachable object, including
> +every version of every file in the history of the repository. The **partial clone**
> +feature allows Git to transfer fewer objects and request them from the
> +remote only when they are needed, so some reachable objects can be
> +omitted from the initial `git clone` and subsequent `git fetch`
> +operations. In this way, a partial clone can reduce the network traffic
> +costs and disk space usage when git is working under a large repository.
> +
> +To use the partial clone feature, you can run `git clone` with the
> +`--filter=<filter-spec>` option. If the repository has a deep history
> +and you don't want to download any blobs, the form `filter=blob:none`
> +will omit all the blobs. If the repository has some large blobs and you
> +want to prevent some large blobs being downloaded by an appropriate
> +threshold, the form `--filter=blob:limit=<n>[kmg]` omits blobs larger
> +than n bytes or units (see linkgit:git-rev-list[1]).
> +
Why not the following?:

```
If the repository has some large blobs and you want to omit blobs larger
than desired size limit, use `--filter=blob:limit=<n>[kmg]`.
```

> +When using a partial clone, Git will request missing objects from the
> +remote(s) when necessary. Several commands that do not involve a request
> +over a network may now trigger these requests.
> +
> +For example, The <repository> contains two branches which names 'master'
> +and 'topic. Then, we clone the repository by
> +
> +    $ git clone --filter=blob:none --no-checkout <repository>
> +
> +With the `--filter=blob:none` option Git will omit all the blobs and
> +the `--no-checkout` option Git will not perform a checkout of HEAD
> +after the clone is complete. Then, we check out the remote tracking
> +'topic' branch by
> +
> +    $ git checkout -b topic origin/topic
> +
> +The output looks like
> +
> +------------
> +    remote: Enumerating objects: 1, done.
> +    remote: Counting objects: 100% (1/1), done.
> +    remote: Total 1 (delta 0), reused 0 (delta 0), pack-reused 0
> +    Receiving objects: 100% (1/1), 43 bytes | 43.00 KiB/s, done.
> +    Branch 'topic' set up to track remote branch 'topic' from 'origin'.
> +    Switched to a new branch 'topic'
> +------------
> +
> +The output is a bit surprising but it shows how partial clone works.
> +When we check out the branch 'topic' Git will request the missing blobs
> +because they are needed. Then, We can switch back to branch 'master' by
> +
> +    $ git checkout master
> +
> +This time the output looks like
> +
> +------------
> +    Switched to branch 'master'
> +    Your branch is up to date with 'origin/master'.
> +------------
> +
> +It shows that when we switch back to the previous location, the checkout
> +is done without a download because the repository has all the blobs that
> +were downloaded previously.
> +
> +`git log` may also make a surprise with partial clones. `git log
> +--<path>` will not cause downloads with the blob filters, because it's
> +only reading commits. `git log -p -- <path>` will download blobs to
> +generate the patch output and git log --raw will download all blobs
> +that changed at recent commits in order to compute renames.
> +
>   :git-clone: 1
>   include::urls.txt[]
>   
> 

This describes client-side usage. However, you missed the point that not
all server supports partial clone. If you have your own Git server, and
you want to enable partial clone, you need to invoke as user running the
server daemon (typically `git`):

`git config --global uploadpack.allowfilter true`

And you also missed the case when someone wants to remove partial clone
filters (in order to turn into full clone), for example when needed to
push to another repository as backup. See Gitlab docs for the instructions
[1].

However, brian m. carlson [CC'ed] suggested that "fetch missing objects"
step is instead be done using xargs to avoid "Argument list too long" error,
see [2].

[1]: https://docs.gitlab.com/ee/topics/git/partial_clone.html#remove-partial-clone-filtering
[2]: https://lore.kernel.org/git/YD7bczBsIR5rkqfc@camp.crustytoothpaste.net/
-- 
An old man doll... just what I always wanted! - Clara