Re: [PATCH] doc: technical details about the index file format

[Nguyen Thai Ngoc Duy <pclouds@gmail.com>]

On Sat, Feb 26, 2011 at 02:23:38AM -0800, Junio C Hamano wrote:
> I lack energy to come up with a succinct description right now, so here is
> an undistilled version of what I would want to see the reader of the above
> paragraph understand:
> 
>     A set of entries for a path at higher stages (i.e. the ones that
>     represent a merge conflict at the path) used to be removed from the
>     index and replaced with the result of the resolution when the conflict
>     is resolved (e.g. with "git add path").  This extension saves these
>     higher stage entries away so that "checkout -m" and other operations
>     can recreate the conflicted state, in case you botched a conflict
>     resolution and want to redo it from scratch.
> 
> The description of the data contents looked fine, except that "A number of
> entries" felt a bit unclear (it would make the reader wonder if we record
> how many we have at that location as an integer, which is not the case).

OK another try. I also add more details to tree cache. If somebody
uses this document to create a git-compatible tool, then such a tool
should behave the way git expects it.

A related note. Because we store SHA-1s in resolve undo ext. fsck
should check these for reachability as well. I see fsck checks for
cache-tree only.

--8<--
diff --git a/Documentation/technical/index-format.txt b/Documentation/technical/index-format.txt
index 5b1d70d..2a3490c 100644
--- a/Documentation/technical/index-format.txt
+++ b/Documentation/technical/index-format.txt
@@ -117,8 +117,12 @@ GIT index format
 
 === Tree cache
 
-  Tree cache extension contains pre-computes hashes for all trees that
-  can be derived from the index
+  Tree cache extension contains pre-computed hashes for trees that can
+  be derived from the index. It helps speed up tree object generation
+  from index for a new commit.
+
+  When a path is updated in index, the path must be invalidated and
+  removed from tree cache.
 
   - Extension tag { 'T', 'R', 'E', 'E' }
 
@@ -137,8 +141,25 @@ GIT index format
 
 === Resolve undo
 
-  TODO
+  A conflict is represented in index as a set of higher stage entries.
+  When a conflict is resolved (e.g. with "git add path"), these higher
+  stage entries will be removed and a stage-0 entry with proper
+  resoluton is added.
+
+  Resolve undo extension saves these higher stage entries so that
+  conflicts can be recreated (e.g. with "git checkout -m"), in case
+  users want to redo a conflict resolution from scratch.
 
   - Extension tag { 'R', 'E', 'U', 'C' }
 
   - 32-bit size
+
+  - A number of conflict entries
+
+    NUL-terminated conflict path
+
+    Three NUL-terminated ASCII octal numbers, entry mode of entries in
+    stage 1 to 3.
+
+    At most three 160-bit SHA-1s of the entry in three stages from 1
+    to 3. SHA-1 is not saved for any stage with entry mode zero.
--8<--
-- 
Duy