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

> 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