From: "Derrick Stolee via GitGitGadget" <gitgitgadget@gmail.com>
To: git@vger.kernel.org
Cc: me@ttaylorr.com, jonathantanmy@google.com,
christian.couder@gmail.com, git@jeffhostetler.com,
Derrick Stolee <dstolee@microsoft.com>,
Derrick Stolee <dstolee@microsoft.com>
Subject: [PATCH v2] clone: document --filter options
Date: Sun, 22 Mar 2020 19:50:06 +0000 [thread overview]
Message-ID: <pull.586.v2.git.1584906606469.gitgitgadget@gmail.com> (raw)
In-Reply-To: <pull.586.git.1584638887.gitgitgadget@gmail.com>
From: Derrick Stolee <dstolee@microsoft.com>
It turns out that the "--filter=<filter-spec>" option is not
documented anywhere in the "git clone" page, and instead is
detailed carefully in "git rev-list" where it serves a
different purpose.
Add a small bit about this option in the documentation. It
would be worth some time to create a subsection in the "git clone"
documentation about partial clone as a concept and how it can be
a surprising experience. For example, "git checkout" will likely
trigger a pack download.
Signed-off-by: Derrick Stolee <dstolee@microsoft.com>
---
Slightly simplify partial clone user experience
V2: Only update the documentation of --filter.
Thanks, -Stolee
Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-586%2Fderrickstolee%2Fpartial-clone-ux-v2
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-586/derrickstolee/partial-clone-ux-v2
Pull-Request: https://github.com/gitgitgadget/git/pull/586
Range-diff vs v1:
1: 6f340d9aadf < -: ----------- partial-clone: set default filter with --partial
2: 9baf4c8ba38 ! 1: a55c2d975ab clone: document --partial and --filter options
@@ -1,16 +1,13 @@
Author: Derrick Stolee <dstolee@microsoft.com>
- clone: document --partial and --filter options
+ clone: document --filter options
- The previous change added the "--partial[=<size>]" option to
- "git clone" equivalent to "--filter=blob:none" or
- "--filter=blob:limit=<size>" but did not document that addition.
- It turns out that the "--filter=<filter-spec>" option was not
+ It turns out that the "--filter=<filter-spec>" option is not
documented anywhere in the "git clone" page, and instead is
detailed carefully in "git rev-list" where it serves a
different purpose.
- Add a small bit about these options in the documentation. It
+ Add a small bit about this option in the documentation. It
would be worth some time to create a subsection in the "git clone"
documentation about partial clone as a concept and how it can be
a surprising experience. For example, "git checkout" will likely
@@ -27,7 +24,7 @@
[--recurse-submodules[=<pathspec>]] [--[no-]shallow-submodules]
- [--[no-]remote-submodules] [--jobs <n>] [--sparse] [--] <repository>
+ [--[no-]remote-submodules] [--jobs <n>] [--sparse]
-+ [--partial[=<size>]|--filter=<filter>] [--] <repository>
++ [--filter=<filter>] [--] <repository>
[<directory>]
DESCRIPTION
@@ -35,17 +32,15 @@
of the repository. The sparse-checkout file can be
modified to grow the working directory as needed.
-+--partial[=<size>]::
+--filter=<filter-spec>::
+ Use the partial clone feature and request that the server sends
+ a subset of reachable objects according to a given object filter.
+ When using `--filter`, the supplied `<filter-spec>` is used for
-+ the partial clone filter. When using `--partial` with no `<size>`,
-+ the `blob:none` filter is applied to filter all blobs. When using
-+ `--partial=<size>` the `blob:limit=<size>` filter is applied to
-+ filter all blobs with size larger than `<size>`. For more details
-+ on filter specifications, see the `--filter` option in
-+ linkgit:git-rev-list[1].
++ the partial clone filter. For example, `--filter=blob:none` will
++ filter out all blobs (file contents) until needed by Git. Also,
++ `--filter=blob:limit=<size>` will filter out all blobs of size
++ at least `<size>`. For more details on filter specifications, see
++ the `--filter` option in linkgit:git-rev-list[1].
+
--mirror::
Set up a mirror of the source repository. This implies `--bare`.
Documentation/git-clone.txt | 13 ++++++++++++-
1 file changed, 12 insertions(+), 1 deletion(-)
diff --git a/Documentation/git-clone.txt b/Documentation/git-clone.txt
index bf24f1813ad..08d6045c4a8 100644
--- a/Documentation/git-clone.txt
+++ b/Documentation/git-clone.txt
@@ -15,7 +15,8 @@ SYNOPSIS
[--dissociate] [--separate-git-dir <git dir>]
[--depth <depth>] [--[no-]single-branch] [--no-tags]
[--recurse-submodules[=<pathspec>]] [--[no-]shallow-submodules]
- [--[no-]remote-submodules] [--jobs <n>] [--sparse] [--] <repository>
+ [--[no-]remote-submodules] [--jobs <n>] [--sparse]
+ [--filter=<filter>] [--] <repository>
[<directory>]
DESCRIPTION
@@ -162,6 +163,16 @@ objects from the source repository into a pack in the cloned repository.
of the repository. The sparse-checkout file can be
modified to grow the working directory as needed.
+--filter=<filter-spec>::
+ Use the partial clone feature and request that the server sends
+ a subset of reachable objects according to a given object filter.
+ When using `--filter`, the supplied `<filter-spec>` is used for
+ the partial clone filter. For example, `--filter=blob:none` will
+ filter out all blobs (file contents) until needed by Git. Also,
+ `--filter=blob:limit=<size>` will filter out all blobs of size
+ at least `<size>`. For more details on filter specifications, see
+ the `--filter` option in linkgit:git-rev-list[1].
+
--mirror::
Set up a mirror of the source repository. This implies `--bare`.
Compared to `--bare`, `--mirror` not only maps local branches of the
base-commit: 6c85aac65fb455af85745130ce35ddae4678db84
--
gitgitgadget
next prev parent reply other threads:[~2020-03-22 19:50 UTC|newest]
Thread overview: 15+ messages / expand[flat|nested] mbox.gz Atom feed top
2020-03-19 17:28 [PATCH 0/2] Slightly simplify partial clone user experience Derrick Stolee via GitGitGadget
2020-03-19 17:28 ` [PATCH 1/2] partial-clone: set default filter with --partial Derrick Stolee via GitGitGadget
2020-03-20 20:26 ` Junio C Hamano
2020-03-20 20:38 ` Derrick Stolee
2020-03-22 9:46 ` Jeff King
2020-03-19 17:28 ` [PATCH 2/2] clone: document --partial and --filter options Derrick Stolee via GitGitGadget
2020-03-20 12:27 ` [PATCH 0/2] Slightly simplify partial clone user experience Derrick Stolee
2020-03-22 9:51 ` Jeff King
2020-03-22 10:58 ` Christian Couder
2020-03-22 16:45 ` Derrick Stolee
2020-03-22 19:22 ` Jeff King
2020-03-22 16:03 ` Taylor Blau
2020-03-22 19:50 ` Derrick Stolee via GitGitGadget [this message]
2020-03-24 3:40 ` [PATCH v2] clone: document --filter options Jeff King
2020-03-24 5:17 ` Jonathan Nieder
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=pull.586.v2.git.1584906606469.gitgitgadget@gmail.com \
--to=gitgitgadget@gmail.com \
--cc=christian.couder@gmail.com \
--cc=dstolee@microsoft.com \
--cc=git@jeffhostetler.com \
--cc=git@vger.kernel.org \
--cc=jonathantanmy@google.com \
--cc=me@ttaylorr.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).