git.vger.kernel.org archive mirror
 help / color / mirror / Atom feed
From: Junio C Hamano <gitster@pobox.com>
To: "Teng Long via GitGitGadget" <gitgitgadget@gmail.com>
Cc: git@vger.kernel.org, Teng Long <dyroneteng@gmail.com>,
	Philippe Blain <levraiphilippeblain@gmail.com>
Subject: Re: [PATCH v5] clone: document partial clone section
Date: Wed, 03 Mar 2021 11:25:11 -0800	[thread overview]
Message-ID: <xmqqeegwjazs.fsf@gitster.c.googlers.com> (raw)
In-Reply-To: <pull.745.v5.git.git.1614695133486.gitgitgadget@gmail.com> (Teng Long via GitGitGadget's message of "Tue, 02 Mar 2021 14:25:32 +0000")

"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

  reply	other threads:[~2021-03-04  0:23 UTC|newest]

Thread overview: 24+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2020-04-02  2:02 [PATCH] " Teng Long via GitGitGadget
2020-04-02 11:29 ` Derrick Stolee
2020-04-02 17:37 ` Junio C Hamano
2020-04-02 17:52   ` Derrick Stolee
2020-04-13 15:25 ` [PATCH v2 0/3] " Teng Long via GitGitGadget
2020-04-13 15:25   ` [PATCH v2 1/3] partial-clone: set default filter with --partial Derrick Stolee via GitGitGadget
2020-04-13 15:25   ` [PATCH v2 2/3] clone: document --partial and --filter options Derrick Stolee via GitGitGadget
2020-04-13 15:26   ` [PATCH v2 3/3] clone: document partial clone section Dyrone Teng via GitGitGadget
2020-10-27 13:41     ` Philippe Blain
2020-04-13 22:45   ` [PATCH v2 0/3] " Junio C Hamano
2020-04-14 13:43     ` Derrick Stolee
2020-04-14 16:25       ` Junio C Hamano
2020-04-14 16:26         ` Derrick Stolee
2020-04-14 13:42   ` Derrick Stolee
2020-10-27  3:12   ` [PATCH v3] " Teng Long via GitGitGadget
2020-10-27 13:13     ` Philippe Blain
2020-10-27 18:51       ` Junio C Hamano
2021-02-25  9:13     ` [PATCH v4] " Teng Long via GitGitGadget
2021-02-25 13:38       ` Philippe Blain
2021-03-02 14:25       ` [PATCH v5] " Teng Long via GitGitGadget
2021-03-03 19:25         ` Junio C Hamano [this message]
2021-05-06  6:27           ` Fix inconsistent signed-off-by abd author name Teng Long
2021-05-06  6:30         ` [PATCH 1/1] clone: document partial clone section Teng Long
2021-05-07  4:00           ` Bagas Sanjaya

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=xmqqeegwjazs.fsf@gitster.c.googlers.com \
    --to=gitster@pobox.com \
    --cc=dyroneteng@gmail.com \
    --cc=git@vger.kernel.org \
    --cc=gitgitgadget@gmail.com \
    --cc=levraiphilippeblain@gmail.com \
    --subject='Re: [PATCH v5] clone: document partial clone section' \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).