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

>> +Performance concerns
>> +--------------------
>> +
>> +Git is written with performance in mind and it works extremely well
>> +with its typical repositories (i.e. source code repositories, with
>> +a moderate number of small text files, possibly with long history).
>> +Non-typical repositories (a lot of files, or very large files...)
>> +may experience mild performance degradation. This section describes
>> +how Git behaves in such repositories and how to reduce impact.
>> +
>
> 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.

> 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.
>
>> +For repositories with a large number of files (~50k files or more),
>
> How did you come up with this 50k number?

>> +but you only need a few of them present in working tree, you can use
>> +sparse checkout (see linkgit:git-read-tree[1], section 'Sparse
>> +checkout').
>
> 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:
>
> ...
>

> 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.
>
>> +... If you need all of them present in working tree, but you
>> +know in advance only a few of them may be modified, please consider
>> +using assume-unchanged bit (see linkgit:git-update-index[1]).
>> +... The following commands are
>> +however known to do full index refresh in some cases:
>
> It is "need to", not "are known to", isn't it?

>> +Some commands need entire file content in memory to process.
>> +Files that have size a significant portion of physical RAM may
>> +affect performance. You may want to avoid using the following
>> +commands if possible on such large files:
>
> "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".