Re: [PATCH RFC v3 2/2] Move libgit.a sources into separate "lib/" directory

Hi Patrick & Junio,

On Tue, 11 Aug 2026, Patrick Steinhardt wrote:

> On Tue, Aug 11, 2026 at 09:33:29AM -0700, Junio C Hamano wrote:
> > Patrick Steinhardt <[email protected]> writes:
> > 
> > >> ... built-in commands in 'builtin', with subsystems like 'refs' and
> > >> 'odb' in their own directories, and everything else at the root
> > >> level, I would prefer to keep that organization until a substantial
> > >> subsystem update wants to carve out a new location for itself, just
> > >> as past updates to create 'builtin', 'refs', and 'odb' did.
> > >> 
> > >> Compared to those past moves, the proposed change looks more like
> > >> churn for the sake of moving things around, without achieving any
> > >> real organizational improvement.
> > >> 
> > >> I must say that I, too, remain skeptical.
> > >
> > > My main motivation isn't prettiness though, it's newcomers to the
> > > project. Git is not an easy project to get started in, and the root
> > > cause of that of course isn't our file layout but probably rather that
> > > Git has been growing organically for 20 years. But the file layout
> > > definitely doesn't help newcomers to find their way around in the
> > > product.
> > 
> > What I gave as good examples were not motivated by prettiness,
> > either.  Moving things around to lib/ as a whole ball of wax without
> > further classification would mean readers, whether new or old, would
> > not benefit from neatly classified set of files that gives readers a
> > concise and easy to understand rules like "you can visit builtin to
> > learn about individual command implementations".  To achieve a layout
> > that makes it easier to find our way around, you'd need to move
> > things again after moving everything into lib/.  Moving to lib/ by
> > itself does not add much value, if any.  It certainly does not add
> > any discoverability.
> 
> I think that a cleaned up root directory is by itself already adding a
> lot of value

For what it's worth, the cleaned up root directory was the benefit I
immediately spotted, too.

Of course, it would be even nicer if `lib/` was split up further, but
then:

1) You've got to start _somewhere_. As we saw with so many things on this
   list, they never materialized because reviewers asked for too much and
   weren't happy to get incremental improvements first.

2) Naming is hard. As we saw with _many_ refactorings (I am thinking about
   the low-level merge stuff as well as the ODB stuff, for example), it is
   unlikely to get the origanization right the first time. So I'd think
   that first moving the bulk of the library code to lib/ is a good start,
   and worth merging, leaving later contributions to chop off further
   parts into subdirectories of lib/.

3) The continuing maintenance pain that is felt with having to integrate
   this lib/ movement with other in-flight patch series in `seen` is the
   _exact same_ pain that many other maintainers (myself included) feel
   continuously. I think it is a good thing that this gap in Git's
   functionality is now so clearly visible that next time e.g. something
   like non-automatic rename detection is discussed, it won't be dismissed
   so easily.

> because it makes the entry points into the Git codebase more explicit.
> As I said elsewhere, the value is not in making the code that is part of
> "lib/" itself more discoverable. The value is in making everything else
> more discoverable.

:+1:

How many casual readers do you think have discovered the top-level
`RelNotes` symlink, for example?

Ciao,
Johannes

> 
> Ultimately though it's a subjective change, so it's hard to argue about
> that as I cannot present any hard facts.
> 
> Thanks!
> 
> Patrick
>