From: brian m. carlson <sandals@crustytoothpaste.net>
Date: Tue, 30 Sep 2025 16:39:59 GMT
Subject: Re: [PATCH 5/9] docs: add documentation for loose objects
Message-ID: <aNwH3wqMzbNMpnEB@fruit.crustytoothpaste.net>
In-Reply-To: <aNOkBuigxCODIcVN@pks.im>

On 2025-09-24 at 07:55:50, Patrick Steinhardt wrote:
> On Fri, Sep 19, 2025 at 01:09:07AM +0000, brian m. carlson wrote:
> > We currently have no documentation for how loose objects are stored.
> > Let's add some here so its easy for people to understand how they
> 
> Nit: s/its/it is/

Will be fixed in v2.

> Do we maybe want to call this "gitformat-loose-objects(5)"? "loose"
> feels rather generic.

We have "index" and "pack", so I'd rather keep it short.

> > @@ -0,0 +1,49 @@
> > +gitformat-loose(5)
> > +==================
> 
> Makes me wonder whether we should also have gitformat-reffiles(5) and
> gitformat-reftables(5). Obviously nothing you have to do, but rather an
> action item for myself or others interested in the ref backends.

Yeah, I definitely think that would be useful.

> > +SYNOPSIS
> > +--------
> > +[verse]
> > +$GIT_DIR/objects/[0-9a-f][0-9a-f]/*
> > +$GIT_DIR/objects/loose-object-idx
> > +$GIT_DIR/objects/loose-map/map-*.map
> 
> It's a bit weird to list the mapping files here without explaining them.
> Should we maybe drop them for now and only add them once we also add a
> section explaining their format?

I've bumped those two lines to a future commit (probably part 2).

> I feel that "most of its primary repository data" is a bit misleading,
> as one can expect that most of the data should be in packfiles instead.
> How about the following instead:
> 
>     Loose objects are how Git stores individual objects, where every
>     object is written as a separate file.
> 
>     Over the lifetime of a repository, new objects are typically written
>     as loose objects initially. Eventually, these loose objects will be
>     compacted into packfiles via repository maintenance to improve disk
>     space usage and speed up the lookup of those objects.

I adopted most of this language.

> Should we maybe give a hint why we have these sharding directories?

Done in v2.
-- 
brian m. carlson (they/them)
Toronto, Ontario, CA