git.vger.kernel.org archive mirror
 help / color / mirror / Atom feed
From: Taylor Blau <me@ttaylorr.com>
To: Derrick Stolee via GitGitGadget <gitgitgadget@gmail.com>
Cc: git@vger.kernel.org, me@ttaylorr.com, jonathantanmy@google.com,
	christian.couder@gmail.com, git@jeffhostetler.com,
	Derrick Stolee <dstolee@microsoft.com>
Subject: Re: [PATCH 0/2] Slightly simplify partial clone user experience
Date: Sun, 22 Mar 2020 10:03:24 -0600	[thread overview]
Message-ID: <20200322160324.GA53845@syl.local> (raw)
In-Reply-To: <pull.586.git.1584638887.gitgitgadget@gmail.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

  parent reply	other threads:[~2020-03-22 16:03 UTC|newest]

Thread overview: 15+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2020-03-19 17:28 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 [this message]
2020-03-22 19:50 ` [PATCH v2] clone: document --filter options Derrick Stolee via GitGitGadget
2020-03-24  3:40   ` 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

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=20200322160324.GA53845@syl.local \
    --to=me@ttaylorr.com \
    --cc=christian.couder@gmail.com \
    --cc=dstolee@microsoft.com \
    --cc=git@jeffhostetler.com \
    --cc=git@vger.kernel.org \
    --cc=gitgitgadget@gmail.com \
    --cc=jonathantanmy@google.com \
    --subject='Re: [PATCH 0/2] Slightly simplify partial clone user experience' \
    /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

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 NNTP newsgroup(s).