Re: [PATCH 5/9] docs: add documentation for loose objects
On 2025-09-24 at 07:55:50, Patrick Steinhardt wrote:
Show 5 quoted lines
> 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/
> 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.
Show 7 quoted lines
> > @@ -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.
Show 10 quoted lines
> > +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).
Show 11 quoted lines
> 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?
--
brian m. carlson (they/them)
Toronto, Ontario, CA
brian m. carlson <sandals@crustytoothpaste.net>