Re: [PATCH v13 04/13] reftable: file format documentation

From: Han-Wen Nienhuys <hanwen@google.com>
Date: May 20, 2020, 17:20 UTC
Message-ID: <CAFQ2z_P-cf38yR-VyvfDSgPUO_d38mgsi32UkRSPWMZKJOmjZg@mail.gmail.com>
In-Reply-To: <CAFQ2z_OazuU32Nm3geLCbu_R2u_JKTqCXX0NF35C0=9xV7Ow0g@mail.gmail.com>

On Wed, May 20, 2020 at 6:06 PM Han-Wen Nienhuys <hanwen@google.com> wrote:

Show 22 quoted lines

> > > +The `message_length` may be 0, in which case there was no message
> > > +supplied for the update.
> > > +
> > > +Contrary to traditional reflog (which is a file), renames are encoded as
> > > +a combination of ref deletion and ref creation.
> >
> > Yay?  How does the deletion record look like?  The new object name
> > being 0*hashlength?  I didn't see it defined in the description (and
> > I am guessing that log_type of 0x0 is *NOT* used for that purpose).
>
> quoting the spec:
>
> "Log record entries use `log_type` to indicate what follows:
>
> * `0x0`: deletion; no log data."
>
> > So, NEEDSWORK: describe how "creation of a ref" and "deletion of a ref"
> > appears in a log as a log record entry.
>
> the creation would be the appearance of a reflog record for the ref.
> You'd have to search back in time to decide if a reflog record it was
> an update to an existing record or a creation.

Correction. This is one of the things that confused me earlier: reflog entries for creating and deleting branches look like this

    000000000000 -> xxxxx      (create)
    xxxxxx.. xx        -> 00000 .. (delete)

respectively. When the rename happens, we can signal that the deletion and addition are linked, because they occur at the same update_index.

The deletion records for logs (type=0x0) remove a reflog entry at a specific (earlier used) update_index. So you could have the following situation:

0x0001.ref : reflog "refs/heads/master" @ update_index=0x0001, new=xxx, old=yyy ...

and then a subsequent table could specify

0x0020.ref : reflog "refs/heads/master" @ update_index=0x0001 (type=0x0)

which would hide the earlier reflog entry.

Jonathan Nieder said that this is used for git-stash, but I have never understood why this is necessary, and would love to clarify this better.

I'll clarify the explanation to reflect this.

-- 
Han-Wen Nienhuys - Google Munich
I work 80%. Don't expect answers from me on Fridays.
--
Google Germany GmbH, Erika-Mann-Strasse 33, 80636 Munich
Registergericht und -nummer: Hamburg, HRB 86891
Sitz der Gesellschaft: Hamburg
Geschäftsführer: Paul Manicle, Halimah DeLaine Prado