diff mbox series

[v2] clone: document --filter options

Message ID pull.586.v2.git.1584906606469.gitgitgadget@gmail.com (mailing list archive)
State New, archived
Headers show
Series [v2] clone: document --filter options | expand

Commit Message

Linus Arver via GitGitGadget March 22, 2020, 7:50 p.m. UTC 
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(-)


base-commit: 6c85aac65fb455af85745130ce35ddae4678db84

Comments

Jeff King March 24, 2020, 3:40 a.m. UTC | #1 
On Sun, Mar 22, 2020 at 07:50:06PM +0000, Derrick Stolee via GitGitGadget wrote:

>     Slightly simplify partial clone user experience
>     
>     V2: Only update the documentation of --filter.

Thanks, this part is definitely an improvement (and I read over the
proposed text again, and it looks very good).

-Peff
Jonathan Nieder March 24, 2020, 5:17 a.m. UTC | #2 
Derrick Stolee wrote:

> 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.
[...]
>  Documentation/git-clone.txt | 13 ++++++++++++-
>  1 file changed, 12 insertions(+), 1 deletion(-)

Reviewed-by: Jonathan Nieder <jrnieder@gmail.com>

Thanks.

>                                                         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.

I think that belongs in its own git-partial-clone(7) page.

Thanks,
Jonathan
diff mbox series

Patch

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