From: Patrick Steinhardt <ps@pks.im>
Date: Thu, 02 Jul 2026 05:21:16 GMT
Subject: Re: [PATCH RFC v2 2/2] Move libgit.a sources into separate "lib/" directory
Message-ID: <akX1TMoRr87Id8Ss@pks.im>
In-Reply-To: <xmqq1pdmrcp6.fsf@gitster.g>

On Wed, Jul 01, 2026 at 07:45:09AM -0700, Junio C Hamano wrote:
> Phillip Wood <phillip.wood123@gmail.com> writes:
> 
> > As I said last time this came up, I don't really buy the discoverability 
> > argument because there are just as many files to trawl through to find 
> > what you're looking through and now there is an extra directory to 
> > check. I think the solution to that is to recommend folks use "git grep" 
> > or ctags etc. not moving code to a new directory.
> 
> Hear, hear.  Also it would be great if we can trick some talented
> technical writer into writing the "map" of the source so that by
> reading this one or two pager, any new person with reasonable
> competence will know how things are partitioned into pieces and how
> these pieces fit together.  I wonder how good LLMs are these days?
> ;-)

This isn't about discoverability of the library files though, I
specifically want to improve discoverability of all the other files that
we have in our root directory. So yes, I fully agree that this change
does not help to make that one file that is part of our library easier
to find.

> > I do however think putting all the library code in a subdirectory makes 
> > it easier to say things like "please try to avoid new uses of 
> > 'the_repository' and prefer 'error()' over 'die()' in library code" 
> > because all the library code is in the same directory. I think that is a 
> > much stronger selling point.
> 
> Yes.  "library code (things outside the subdirectories) should not
> use X" would work just fine, though.

That rule doesn't quite work:

  - We have several C files that are not library files and that are in
    the top-level directory. For example "scalar.c" or "shell.c".

  - We have several C files that are part of the library and that are in
    a subdirectory. For example "compat/", "refs/", "odb/".

So having this properly cleaned up would help to have clear indicators
what component a given file belongs to.

> > Another cost is remembering things have moved - the other day I spent 
> > too long wondering why "git show origin/seen:wt-status.c" wasn't working 
> > until I ran "git log origin/seen" and realized it had move to 
> > lib/wt-status.c.
> 
> Yes, this has bit me multiple dozen times, as the tip of 'seen' is
> contaminated with this rename, already.  It is a huge pain.

Yeah, this one I don't have any arguments against besides a very
hand-wavy "it'll get better over time" :)

Thanks!

Patrick