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

[Phillip Wood <phillip.wood123@gmail.com>]

Hi Patrick

On 01/07/2026 07:55, Patrick Steinhardt wrote:
> On Sat, Jun 27, 2026 at 08:40:48AM +0200, SZEDER Gábor wrote:
>> On Mon, Jun 22, 2026 at 12:38:22PM +0200, Patrick Steinhardt wrote:
>>> The Git project is not exactly the easiest project to get started in:
>>> it's written in C and POSIX shell, with bits of Perl, Rust and other
>>> languages sprinkled into it. On top of that, the project has grown
>>> somewhat organically over time, making the codebase hard to navigate.
>>>
>>> These are problems that we're aware of, and there have been and still
>>> are efforts to clean up some of the technical debt that is natural to
>>> exist an a project that is more than 20 years old. Furthermore, we
>>> provide resources to newcomers that help them out like our coding
>>> guidelines, code of conduct or "MyFirstContribution.adoc".
>>>
>>> But there is a rather practical problem: finding your way around in our
>>> project's tree is not easy. Doing a directory listing in the top-level
>>> directory will present you with more than 550 files, which makes it
>>> extremely hard for a newcomer to figure out what files they are even
>>> supposed to look at. This makes the onboarding experience somewhat
>>> harder than it really needs to be. This isn't only a problem for
>>> newcomers though, as I myself struggle to find the files I am looking
>>> for because of the sheer number of files.
>>>
>>> Besides the problem of discoverability it also creates a problem of
>>> structure. It is not obvious at all which files are part of "libgit.a"
>>> and which files are only linked into our final executables. So while we
>>> have this split in our build systems, that split is not evident at all
>>> in our tree.
>>>
>>> Introduce a new "lib/" directory and move all of our sources for
>>> "libgit.a" into it to fix these issues. It makes the split we have
>>> evident and reduces the number of files in our top-level tree from 550
>>> files to ~80 files.
>>>
>>> This is still a lot of files, but it's significantly easier to navigate
>>> already. Furthermore, we can further iterate after this step and think
>>> about introducing a better structure for remaining files, as well.
>>
>> Please also discuss the drawbacks of this proposal, and try to argue
>> convincingly that the benefits outweigh the drawbacks.
> 
> This is overall a subjective change, so there is no "right" or "wrong".
> The reason why I think the pain is ultimately worth it is that it's a
> one-time cost for a permanent improvement in discoverability. And that
> improvement is especially helpful for newcomers, who already have a hard
> time navigating the code base.

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.

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.

>> I, for one, see myself being rather annoyed by regular 'git log
>> lib/foo.c' stopping at the rename barrier, and by the limitations of
>> '--follow'.
> 
> Right. As mentioned in a parallel subthread, I think this is a
> deficiency in Git itself which we are in the best position to fix. If it
> is proving to be painful, then it might even help to subject ourselves
> to the same pain that other projects that do larger renames experience.
> So it might motivate us to improve this area.

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.

Thanks

Phillip

> In any case, I'll amend these thoughts to the commit message, thanks!
> 
> Patrick