[PATCH v2] index-format.txt: be more liberal on what can represent invalid cache tree

["Nguyễn Thái Ngọc Duy" <pclouds@gmail.com>]

We have been writing -1 as "invalid" since day 1. On that same day we
accept all negative entry counts as "invalid". So in theory all C Git
versions out there would be happy to accept any negative numbers. JGit
seems to do exactly the same.

Correct the document to reflect the fact that -1 is not the only magic
number. At least one implementation, libgit2, is found to treat -1
this way.

Signed-off-by: Nguyễn Thái Ngọc Duy <pclouds@gmail.com>
---
 On Thu, Dec 13, 2012 at 1:14 AM, Junio C Hamano <gitster@pobox.com> wrote:
 > Nguyễn Thái Ngọc Duy  <pclouds@gmail.com> writes:
 >
 >> We have been writing -1 as "invalid" since day 1. On that same day we
 >> accept all negative entry counts as "invalid". So in theory all C Git
 >> versions out there would be happy to accept any negative numbers. JGit
 >> seems to do exactly the same.
 >
 > I am of two minds here.
 >
 > The existing code is being more lenient than specified when they
 > read stuff others wrote, but it still adheres to -1 when writing.
 > Allowing random implementations to write random negative values will
 > close the door for us to later update the specification to encode
 > more informatin about these invalid entries by using negative value
 > other than -1 here.

 How would that work with existing versions? If you write -2 in
 cache-tree, the next time 1.8.0 updates cache tree it writes -1 back.
 That loses whatever information you attach to -2. A new cache-tree
 extension is probably better.

 > I am OK with a reword to say "negative means invalid, and writers
 > should write -1 for invalid entries", but without the latter half,
 > this change is not justified.

 Done.

 Documentation/technical/index-format.txt | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/Documentation/technical/index-format.txt b/Documentation/technical/index-format.txt
index 9d25b30..ce28a7a 100644
--- a/Documentation/technical/index-format.txt
+++ b/Documentation/technical/index-format.txt
@@ -161,8 +161,9 @@ GIT index format
     this span of index as a tree.
 
   An entry can be in an invalidated state and is represented by having
-  -1 in the entry_count field. In this case, there is no object name
-  and the next entry starts immediately after the newline.
+  a negative number in the entry_count field. In this case, there is no
+  object name and the next entry starts immediately after the newline.
+  When writing an invalid entry, -1 should always be used as entry_count.
 
   The entries are written out in the top-down, depth-first order.  The
   first entry represents the root level of the repository, followed by the
-- 
1.8.0.rc2.23.g1fb49df