[PATCH v2 3/3] clone: document partial clone section

From

DGDyrone Teng via GitGitGadget <gitgitgadget@gmail.com>

Date

Apr 13, 2020, 15:26 UTC

Message-ID

<c1a44a35095e7d681c312ecaa07c46e49f2fae67.1586791560.git.gitgitgadget@gmail.com>

In-Reply-To

<pull.745.v2.git.git.1586791560.gitgitgadget@gmail.com>

From: Dyrone Teng <dyroneteng@gmail.com>

Signed-off-by: Dyrone Teng <dyroneteng@gmail.com>
---
 Documentation/git-clone.txt | 72 +++++++++++++++++++++++++++++++++++++
 1 file changed, 72 insertions(+)

diff --git a/Documentation/git-clone.txt b/Documentation/git-clone.txt
index eafa1c39927..a6e13666ea1 100644
--- a/Documentation/git-clone.txt
+++ b/Documentation/git-clone.txt
@@ -310,6 +310,78 @@ 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.
+
+To use the partial clone feature, you can run `git clone` with the 
+`--filter=<filter-spec>` option. If you want to clone a repository
+without 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]).
+
+As mentioned before, a partially cloned repository may have to request
+the missing objects when they are needed. So some 'local' commands may
+fail without a network connection to the remote repository.
+
+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
+-- <pathspec>` will not cause downloads with the blob filters, because
+it's only reading commits and trees. In addition to any options that
+require git to look at the contents of blobs, like "-p" and "--stat"
+, options that cause git to report pathnames, like "--summary" and
+"--raw", will trigger lazy/on-demand fetching of blobs, as they are
+needed to detect inexact renames.
+
+linkgit:partial-clone[1]
+
 :git-clone: 1
 include::urls.txt[]
 

-- 
gitgitgadget