Re: [PATCH] git.txt: document limitations on non-typical repos (and hints)

pclouds@gmail.com writes:

I have seen this "mild" suggested in the discussion, but do we want any adjective here? The runtime for, say, "git log" from the tip to the root obviously would grow proportionally to the length of the history, i.e. the number of records you would want to see, and it may not be "mild" if your history is very deep. Same for the runtime for "git diff" in a wide project with many changed paths.

More importantly, what is "degradation"? It is not a degradation if "git log" took 100x as long for a project with 100k commits compared to a similar project with 1k commits.

If you do not have enough core to hold the part of the ancestry graph that is involved to compute "git log A..B" to show a gazillion commits, it will eat into the swap, take a lot more time than it takes "git log B" to show the same number of commits. That _is_ degradation, and I suspect it won't be mild at all.

How did you come up with this 50k number?

Is "sparse checkout" a real feature that has been made usable by mere mortals, battle tested, and shown to be reliable?

It feels funny that we have to refer to the documentation of plumbing read-tree when the key verb in this paragraph is "checkout". With the current documentation set, you can follow read-tree page that mentions some magic called skip-worktree-bit, get tempted to jump to update-index page and get lost in the implementation details of the feature, which is irrelevant to the end user. If you resisted the temptation and keep reading read-tree page, you see the description of info/sparse-checkout to learn how to control the feature, but it does not come with an easy-to-follow example. A few concrete suggestions to "Sparse checkout" section in read-tree:

    - Move the section to a separate file and include it in read-tree
      page, so that we can include it later in checkout page;

    - Drop the first paragraph;

    - Move the second and third paragraph, that still describe the
      machinery more than the usage, much later in the section;

    - Start the section with the description of info/sparse-checkout; the
      first sentence ("while ... is usually used") need to be rewritten,
      because (1) it is not a complete sentence and grammatically
      incorrect, and (2) it reads as if you will say an alternative file
      can be used instead of info/sparse-checkout, which is not what you
      wanted to do; perhaps "$GIT_DIR/info/sparse-checkout is used to
      specify which paths are to be (and not to be) checked out. It lists
      glob patterns to match paths to be checked out. Prefix the pattern
      with a '!' to specify a pattern to match paths not to be checked
      out.  Note: a bug in the implementation requires you to end a
      pattern with a trailing slash to match a directory".

    - Show examples; not just the samples of how contents of that control
      file looks like, but also with a concrete command sequence (e.g. (1)
      run "git clone -n", (2) edit info/sparse-checkout to contain this,
      (3) run "git checkout", (4) here is how to widen/narrow the sparse
      checkout--first edit info/sparse-checkout to look like this and then
      run "git xxx" to match the updated definition, etc.).

    - Drop BUGS section from read-tree documentation (but see Note: above
      in my example); the bug mentioned there is not a bug of read-tree,
      but is a bug in the sparse-checkout feature.

I think the suggestion to use Sparse checkout in git(1)---i.e. your patch we are discussing here, is a bit premature before the above happens.

It is "need to", not "are known to", isn't it?

"If possible" is not a good excuse. How would one _avoid_ checkout of a file if one wants to use it? You can't. Similarly to "diff". This advice is pretty much useless, isn't it? It's not much better than saying "if your machine has too little RAM, things will get slow---deal with it".