index-format: update preamble to cache tree extension
commit22ad8600c1d45ade6bd4b6bd5df87ad733b0575a
authorDerrick Stolee <dstolee@microsoft.com>
Thu, 7 Jan 2021 16:32:08 +0000 (7 16:32 +0000)
committerJunio C Hamano <gitster@pobox.com>
Sat, 16 Jan 2021 07:04:46 +0000 (15 23:04 -0800)
tree851ac7f190c00510d9db77d6963a9b7b9437f3ea
parent845d15d4d07bef903bf6f87275d2be11ca0647b5
index-format: update preamble to cache tree extension

I had difficulty in my efforts to learn about the cache tree extension
based on the documentation and code because I had an incorrect
assumption about how it behaved. This might be due to some ambiguity in
the documentation, so this change modifies the beginning of the cache
tree format by expanding the description of the feature.

My hope is that this documentation clarifies a few things:

1. There is an in-memory recursive tree structure that is constructed
   from the extension data. This structure has a few differences, such
   as where the name is stored.

2. What does it mean for an entry to be invalid?

3. When exactly are "new" trees created?

Helped-by: Junio C Hamano <gitster@pobox.com>
Signed-off-by: Derrick Stolee <dstolee@microsoft.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Documentation/technical/index-format.txt