"Teng Long via GitGitGadget" <gitgitgadget@xxxxxxxxx> writes: > From: Dyrone Teng <dyroneteng@xxxxxxxxx> > > 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@xxxxxxxxx> > --- > clone: document partial clone section > > cc: Philippe Blain levraiphilippeblain@xxxxxxxxx > > 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@xxxxxxxxx> > +Author: Dyrone Teng <dyroneteng@xxxxxxxxx> > > ## 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
