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
next prev parent reply other threads:[~2021-03-04 0:53 UTC|newest]
Thread overview: 24+ messages / expand[flat|nested] mbox.gz Atom feed top
2020-04-02 2:02 [PATCH] clone: document partial clone section 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
List information: http://vger.kernel.org/majordomo-info.html
* 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 \
/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
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this public inbox
https://80x24.org/mirrors/git.git
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 read-only IMAP folder(s) and NNTP newsgroup(s).