Re: [PATCH 0/2] Slightly simplify partial clone user experience

[Taylor Blau <me@ttaylorr.com>]

On Thu, Mar 19, 2020 at 05:28:05PM +0000, Derrick Stolee via GitGitGadget wrote:
> This was something discussed briefly at the contributor summit: users will
> have a hard time remembering git clone --filter=blob:none <url>.

I think that this is probably my fault :).

I was saying at the contributor summit that I think I may have created
more confusion than clarity when I was describing how to use partial
clones in my last release blog post.

In that post, I introduced partial clones by asking and answering the
following series of four questions.

  1. What do you do when your repository is too large? Partial clones.
  2. How do you only fetch down some of the objects? Object filters.
  3. How do you restrict which parts of your working copy are populated?
     Write to '.git/info/sparse-checkout'.
  4. Simplify things even further by using 'git sparse-checkout' instead.

I think that some of the criticism was along the lines of "you said that
partial clones would be easy, but nothing in the steps 2-4 is
straightforward".

I think that things would have been much clearer if I said:

  If your repository is too large to clone all at once, or has a
  checkout footprint that is too big, you can issue a partial clone
  against it by writing the following:

    $ git clone --filter=blob:none --sparse /path/to/your/repo

> This series simply adds a --partial option that is equivalent to
> --filter=blob:none, with the ability to specify a size using
> --partial=<size> that is equivalent to --filter=blob:limit=<size>.

I think that I have mixed feelings about this, too. On the one hand, it
irrefutably makes the above incantation a lot easier to write out and
remember. On the other hand, I worry about it locking in options that we
don't want to keep around forever, like adding more filters, changing
some rules about sparse checkout and so on.

Maybe these concerns aren't well-founded, and that we're not likely to
change either of those anytime soon. But, I'd rather be wrong and not be
squatting '--partial[=<n>]' than not.

> While going to the git clone documentation to add this option, I noticed
> that there is no reference to the --filter option there, nor any discussion
> of partial clone. I resolved the former.
>
> REQUEST FOR HELP: If anyone out there is looking for an opportunity to
> contribute documentation, I feel there is a need to include a section in the
> git clone documentation devoted to partial clone. Hopefully such a section
> would include answers to these questions:
>
>  1. What is a partial clone?
>  2. Why would I want a partial clone?
>  3. How do I need to be careful when using a partial clone?
>
> I don't have time to write such a document right now, which is why I'm
> asking for help if anyone is looking for a non-code way to contribute to the
> project.

This seems like a worthy goal outside of this series, and I would
certainly love to have some more documentation in this area.

> Thanks, -Stolee
>
> Derrick Stolee (2):
>   partial-clone: set default filter with --partial
>   clone: document --partial and --filter options
>
>  Documentation/git-clone.txt   | 15 ++++++++++++-
>  list-objects-filter-options.c | 18 +++++++++++++++
>  list-objects-filter-options.h |  8 ++++++-
>  t/t5616-partial-clone.sh      | 42 ++++++++++++++++++++++++++---------
>  4 files changed, 71 insertions(+), 12 deletions(-)
>
>
> base-commit: 6c85aac65fb455af85745130ce35ddae4678db84
> Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-586%2Fderrickstolee%2Fpartial-clone-ux-v1
> Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-586/derrickstolee/partial-clone-ux-v1
> Pull-Request: https://github.com/gitgitgadget/git/pull/586
> --
> gitgitgadget

Thanks,
Taylor