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

From: Junio C Hamano <gitster@pobox.com>
Date: Feb 26, 2011, 10:23 UTC
Message-ID: <7vsjvb6qmt.fsf@alter.siamese.dyndns.org>
In-Reply-To: <20110226100310.GA21724@do>

Nguyen Thai Ngoc Duy <pclouds@gmail.com> writes:

> OK here come the missing bits on top of the previous patch. Looks good?

Thanks.

Show 21 quoted lines

> diff --git a/Documentation/technical/index-format.txt b/Documentation/technical/index-format.txt
> index 5b1d70d..574eb3b 100644
> --- a/Documentation/technical/index-format.txt
> +++ b/Documentation/technical/index-format.txt
> @@ -118,7 +118,7 @@ GIT index format
>  === Tree cache
>  
>    Tree cache extension contains pre-computes hashes for all trees that
> -  can be derived from the index
> +  can be derived from the index.
>  
>    - Extension tag { 'T', 'R', 'E', 'E' }
>  
> @@ -137,8 +137,20 @@ GIT index format
>  
>  === Resolve undo
>  
> -  TODO
> +  Resolve undo extension records staged entries before they are
> +  resolved and removed from index. It can be used to recreate conflicts
> +  after the conflict is incorrectly resolved.

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).

Show 13 quoted lines

>    - Extension tag { 'R', 'E', 'U', 'C' }
>  
>    - 32-bit size
> +
> +  - A number of entries
> +
> +    NUL-terminated entry name
> +
> +    Entry mode of the entry in three stages, in increasing order from
> +    1 to 3, in NUL-terminated ASCII octal number.
> +
> +    160 bit SHA-1 of the entry in three stages, in increasing
> +    order from 1 to 3. A stage with zero mode will be skipped.