Re: [PATCH 5/7] commit-graph: document file format v2

From: Derrick Stolee <derrickstolee@github.com>
Date: Feb 28, 2022, 13:44 UTC
Message-ID: <d19f5ee8-af92-805f-7ea2-8285862c1123@github.com>
In-Reply-To: <220225.86a6ee7eid.gmgdl@evledraar.gmail.com>

On 2/25/2022 5:31 PM, Ævar Arnfjörð Bjarmason wrote:

> 
> On Thu, Feb 24 2022, Derrick Stolee via GitGitGadget wrote:
>

...

Show 29 quoted lines

>>    Generation Data (ID: {'G', 'D', 'A', 'T' }) (N * 4 bytes) [Optional]
>>      * This list of 4-byte values store corrected commit date offsets for the
>> @@ -103,6 +112,9 @@ CHUNK DATA:
>>      * Generation Data chunk is present only when commit-graph file is written
>>        by compatible versions of Git and in case of split commit-graph chains,
>>        the topmost layer also has Generation Data chunk.
>> +    * This chunk does not exist if the commit-graph file format version is 2,
>> +      because the corrected commit date offset data is stored in the Commit
>> +      Data chunk.
>>  
>>    Generation Data Overflow (ID: {'G', 'D', 'O', 'V' }) [Optional]
>>      * This list of 8-byte values stores the corrected commit date offsets
> 
> We talked a while ago now about how we do commit-graph format changes
> and this is partially echoing those earlier questions[1] from 2019.
> 
> I fully understand why we're writing this amended CDAT chunk in a
> different layout. By not having the GDAT side-chunk to look up in the
> data is more local, that part of the file is more compact etc.
> 
> What I don't understand is why getting those performance improvements
> requires the breaking version change & the writing of the incompatible
> version number.
> 
> I.e. couldn't the differently formatted CDAT chunk be written instead to a new
> chunk name (say "2DAT") instead? Per [1] we'd pay a small fixed cost for
> a possibly empty chunk (I didn't re-do those numbers), but surely the
> performance improvements will be about the same for that miniscule
> overhead.

CDAT is a required chunk. It is part of the v1 spec that CDAT exists and is correct. All other Git clients will error out when reading a "v1" graph without such a chunk, and in a way that is less helpful to users. Instead of clearly indicating "file version is too new" it will say "commit-graph is missing the Commit Data chunk" which is not helpful.

Show 5 quoted lines

> It will give you something you can't have here, which is optional
> compatibility with older clients by writing both versions. That'll be a
> ~2x as large file on disk, but with the page cache & each client version
> skipping to the data it needs caching characteristics & data locality
> should work out to about the same thing.

Writing both is the only way that this could work without incrementing the graph version number, but I'd rather just update the number and avoid wasting the effort to write that extra data.

It seems you are hyper-focused on "we don't _need_ to update the version number" and you are willing to recommend wasteful approaches in order to support that stance.

So: you're right. We don't _need_ to update the version number. But this
is the best choice among the options available.

> Or maybe they won't. I just found it surprising when reviewing this to
> not find an answer to why that approach wasn't
> considered.

The point is to create a new format that can be chosen when deployed in an environment where older Git versions will not exist (such as a Git server). The new version is not chosen by default and instead is opt-in through the commitGraph.generationVersion config option.

Perhaps in a year or two we would consider making this the new default, but there is no rush to do so.

Thanks, -Stolee