From: "Teng Long via GitGitGadget" <email@example.com> To: firstname.lastname@example.org Cc: Teng Long <email@example.com>, Dyrone Teng <firstname.lastname@example.org> Subject: [PATCH] clone: document partial clone section Date: Thu, 02 Apr 2020 02:02:26 +0000 [thread overview] Message-ID: <email@example.com> (raw) From: Dyrone Teng <firstname.lastname@example.org> 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 <email@example.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). + +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
next reply other threads:[~2020-04-02 2:02 UTC|newest] Thread overview: 24+ messages / expand[flat|nested] mbox.gz Atom feed top 2020-04-02 2:02 Teng Long via GitGitGadget [this message] 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 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 \ --firstname.lastname@example.org \ --email@example.com \ --firstname.lastname@example.org \ --email@example.com \ --subject='Re: [PATCH] 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
Code repositories for project(s) associated with this 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).