clone: document partial clone section

[dyrone]

Hi Philippe,

Thanks for help.

Reply to your v3-reply
(https://lore.kernel.org/git/B90939A5-5693-4EB6-8F07-5B50F63B3143@gmail.com/#t)

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

"The v3 origin " If you want to clone a repository without download" has been replaced with another sentence in the new patch, so there is no modification here."

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.

"I tried make doc but some build errors occured , output on my screen:"

"
/Applications/Xcode.app/Contents/Developer/usr/bin/make -C Documentation all
SUBDIR ../
make[2]: `GIT-VERSION-FILE' is up to date.
XSLTPROC user-manual.html
warning: failed to load external entity "http://docbook.sourceforge.net/release/xsl/current/html/docbook.xsl"
compilation error: file docbook.xsl line 3 element import
xsl:import : unable to load http://docbook.sourceforge.net/release/xsl/current/html/docbook.xsl
make[1]: *** [user-manual.html] Error 5
make: *** [doc] Error 2
"

"I haven't solved this problem at the moment, so I removed the error doc link temporarily"

cc: Bagas Sanjaya bagasdotme@gmail.com

[dyrone]

/submit

[gitgitgadget-git]

There is an issue in commit bddb5999c32e9c0d54a10fbcee2b55b5433740d1:
Commit not signed off

[gitgitgadget-git]

Error: User dyrone is not permitted to use GitGitGadget

[dscho]

/allow

[gitgitgadget-git]

User dyrone is now allowed to use GitGitGadget.

[dyrone]

/submit

[gitgitgadget-git]

Submitted as pull.745.git.git.1585792946341.gitgitgadget@gmail.com

[gitgitgadget-git]

On the Git mailing list, Derrick Stolee wrote (reply to this):

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

[gitgitgadget-git]

On the Git mailing list, Junio C Hamano wrote (reply to this):

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

[gitgitgadget-git]

On the Git mailing list, Derrick Stolee wrote (reply to this):

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

[dyrone]

/submit

[gitgitgadget-git]

Submitted as pull.745.v2.git.git.1586791560.gitgitgadget@gmail.com

[gitgitgadget-git]

On the Git mailing list, Junio C Hamano wrote (reply to this):

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

[gitgitgadget-git]

On the Git mailing list, Derrick Stolee wrote (reply to this):

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/

[gitgitgadget-git]

On the Git mailing list, Derrick Stolee wrote (reply to this):

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

[gitgitgadget-git]

On the Git mailing list, Junio C Hamano wrote (reply to this):

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.

[gitgitgadget-git]

On the Git mailing list, Derrick Stolee wrote (reply to this):

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

[dscho]

Dyrone: before sending your next version, please eject these two commits. You can do this with "git rebase --onto HEAD3 HEAD1 ".

@dyrone would you, please?

[phil-blain]

Hi @dyrone ! I hope you can find some time to send a new iteration of this patch! I think it would be really great for the partial clone feature to be more documented.

[dyrone]

Hi @dyrone ! I hope you can find some time to send a new iteration of this patch! I think it would be really great for the partial clone feature to be more documented.

OK i will work on it next week

[dyrone]

Hi @dyrone ! I hope you can find some time to send a new iteration of this patch! I think it would be really great for the partial clone feature to be more documented.

I had executed git rebase --onto HEAD3 HEAD1 on my own branch and force pushed with lease as commit ' 5f2f288' now.

Did I deal that right? Because I don't really understand the problem is.

[dyrone]

/submit

[gitgitgadget-git]

Submitted as pull.745.v3.git.git.1603768321361.gitgitgadget@gmail.com

To fetch this version into FETCH_HEAD:

git fetch https://github.com/gitgitgadget/git pr-git-745/dyrone/master-v3

To fetch this version to local tag pr-git-745/dyrone/master-v3:

git fetch --no-tags https://github.com/gitgitgadget/git tag pr-git-745/dyrone/master-v3

[phil-blain]

I had executed git rebase --onto HEAD3 HEAD1 on my own branch and force pushed with lease as commit ' 5f2f288' now.

Did I deal that right? Because I don't really understand the problem is.

The problem was that since you had based your work on Stolee's branch, and Stolee then force-pushed his branch, your branch (in the point of view of GitGitGadget) contained two old commits from Stolee. By executing git rebase --onto HEAD~3 HEAD~1, you told Git "take the commits on the current branch between HEAD~1 and HEAD (so just HEAD, i.e. your own commit) and transplant them onto whatever commit Stolee's branch was branched off (HEAD~3, probably a commit on upstream/master), and that becomes the new version of the current branch (in your case, your own master branch).

Does that answer your question ?

Also, in my experience it's easier to create topic branches for GitHub PRs, and not work on the master branch.

[gitgitgadget-git]

On the Git mailing list, Philippe Blain wrote (reply to this):

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/

[gitgitgadget-git]

User Philippe Blain <levraiphilippeblain@gmail.com> has been added to the cc: list.

[gitgitgadget-git]

On the Git mailing list, Junio C Hamano wrote (reply to this):

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/

[dyrone]

/submit

[gitgitgadget-git]

Submitted as pull.745.v4.git.git.1614244436547.gitgitgadget@gmail.com

To fetch this version into FETCH_HEAD:

git fetch https://github.com/gitgitgadget/git pr-git-745/dyrone/master-v4

To fetch this version to local tag pr-git-745/dyrone/master-v4:

git fetch --no-tags https://github.com/gitgitgadget/git tag pr-git-745/dyrone/master-v4

[dyrone]

Sorry about the "---" problem appears again, I didn't understand it right in the early reply of Philippe Blain. Now I remove the First comment I leave, maybe the problem is solved?

[gitgitgadget-git]

On the Git mailing list, Philippe Blain wrote (reply to this):

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/

[gitgitgadget-git]

User Philippe Blain <levraiphilippeblain@gmail.com> has been added to the cc: list.

[dyrone]

Hi Philippe,

Thanks for help.

Reply to your v3-reply
(https://lore.kernel.org/git/B90939A5-5693-4EB6-8F07-5B50F63B3143@gmail.com/#t)

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

"The v3 origin " If you want to clone a repository without download" has been replaced with another sentence in the new patch, so there is no modification here."

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.

"I tried make doc but some build errors occured , output on my screen:"

"
/Applications/Xcode.app/Contents/Developer/usr/bin/make -C Documentation all
SUBDIR ../
make[2]: `GIT-VERSION-FILE' is up to date.
XSLTPROC user-manual.html
warning: failed to load external entity "http://docbook.sourceforge.net/release/xsl/current/html/docbook.xsl"
compilation error: file docbook.xsl line 3 element import
xsl:import : unable to load http://docbook.sourceforge.net/release/xsl/current/html/docbook.xsl
make[1]: *** [user-manual.html] Error 5
make: *** [doc] Error 2
"

"I haven't solved this problem at the moment, so I removed the error doc link temporarily"

[dscho]

@dyrone please send this as a reply to https://lore.kernel.org/git/caf0fa50-6c2b-7764-1114-d933b2a06061@gmail.com (see https://github.com/gitgitgadget/gitgitgadget/wiki/ReplyToThis for instructions how to do this).

[dyrone]

/submit

[gitgitgadget-git]

Submitted as pull.745.v5.git.git.1614695133486.gitgitgadget@gmail.com

To fetch this version into FETCH_HEAD:

git fetch https://github.com/gitgitgadget/git pr-git-745/dyrone/master-v5

To fetch this version to local tag pr-git-745/dyrone/master-v5:

git fetch --no-tags https://github.com/gitgitgadget/git tag pr-git-745/dyrone/master-v5

[gitgitgadget-git]

On the Git mailing list, Junio C Hamano wrote (reply to this):

"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

[gitgitgadget-git]

On the Git mailing list, Teng Long wrote (reply to this):

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.

[gitgitgadget-git]

On the Git mailing list, Teng Long wrote (reply to this):

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

[gitgitgadget-git]

On the Git mailing list, Bagas Sanjaya wrote (reply to this):

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

[gitgitgadget-git]

User Bagas Sanjaya <bagasdotme@gmail.com> has been added to the cc: list.

[dscho]

@dyrone this PR still looks very relevant, but unfortunately seems not to have seen any meaningful update...