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

[Patrick Steinhardt <ps@pks.im>]

On Mon, Apr 20, 2026 at 08:03:44AM -0400, Derrick Stolee wrote:
> On 4/16/2026 9:24 AM, Patrick Steinhardt wrote:
> > Hi,
> > 
> > this small patch series follows up on a discussion we had two years ago
> > during the Git Contributor's Summit in Berlin.
> 
> Yes. "small". ;)
>  
> > I'm fully aware that this will likely result in some discussion, which
> > is why I have labelled this as RFC. I'd be fine with a result of "let's
> > not do it" if we cannot agree on this step, but I think that the current
> > layout hurts discoverability quite a bit. Not only for newcomers, but
> > I'm also struggling with it quite frequently.
> 
> I agree that the flat layout can be hard to navigate. While we are not
> at a scale that needs something like sparse-checkout, but this wide root
> directory cannot be reduced by cone-mode patterns. This is meaningful
> only for niche cases like "I only care about Documentation/" or someone
> testing sparse-checkout performance on a copy of this repo. It's something
> that I do think worth mentioning whenever such a large refactor will be
> undertaken.
>  
> > I also intentionally decided to send this close to the upcoming release
> > so that the series can be merged early in the next release cycle if we
> > were to agree on it.
> 
> There are two really big disruptions that this will introduce. I bring
> them up only so that we can discuss them and make sure we handle the
> communication to the community and appropriately time the merge of this
> series:
> 
> 1. It will conflict with most patch series in flight. How can we
>    communicate which topics will be caught up in the rename before it
>    merges, which will be modified at merge time by Junio, and which
>    will need to be sent anew on top of this rename?

Yeah, this is an open question. In any case, I'd be happy to help out
with the exercise, if there's anything I can do to make this less
painful.

> 2. It will conflict with forks that have long-lived history that is
>    merged with or replayed on the core project. The examples I know
>    well are github/git, git-for-windows/git, and microsoft/git as
>    discussed in [1].
> 
>    Something that I think would help for these cases is for the rename
>    to be done as a solo topic merged into 'master' on top of a major
>    release, such as immediately after v2.54.0 (or similar). This would
>    allow a merge or rebase from the previous checkpoint to update to
>    the rename without any other upstream edits causing further conflicts.
> 
>    Fork maintainers could then decide if they want to update their forks
>    onto the rename early in the release cycle or as part of the next
>    release cycle. My preference would be to update as part of the current
>    release cycle so any changes during the release cycle automatically
>    incorporate the change similar to working with the core project. (I
>    am not a maintainer of any of these, so it's not actually my decision.)
> 
> [1] https://github.blog/developer-skills/github/friend-zone-strategies-friendly-fork-management/

Agreed. I've been chatting with Dscho last week to assess a bit how much
pain this would cause, and he basically said "go for it". But Git for
Windows is of course not the only fork we have.

> Finally, I looked at what's left after your renames and I see that the
> root directory has these categories of files remaining at root:
> 
> * Dotfiles that must be at root.
> * Documentation that must be at root (README, code of conduct, etc.)
> * Root build logic.
> * .c and .sh files for root-level commands (git, git-*, scalar, etc.)
> 
> Of these, I'd be interested to see if there was value in moving this
> final category of file into another directory, say 'cmd', 'commands',
> or similar. It's the only remaining knob that I think is technically
> possible to further trim this list of files.
> 
> Did you consider moving these files, too?

My initial version was moving around remaining ".c", ".sh" and ".perl"
files, as well. These are (almost) all related to top-level commands
commands, so I was handling those by introducing a new "bin/" directory
and moving them in there.

I think the remaining files would mostly stay as-is though. At least I
couldn't come up with any obvious additional renames.

> _If_ we were considering moving these files, then I'd rather make
> one big rename change instead of repeating this exercise multiple
> times.

I eventually decided to not change too many things at once, as the
"lib/" changes are by far the biggest change, and also result in the
biggest improvement, if you ask me. These changes would also
significantly increase the size of this patch series.

So I still lean into the direction of doing things one step at a time,
because it focusses the discussion, and every subsequent step is
significantly smaller. But if it helps I wouldn't mind also going the
extra mile.

Thanks!

Patrick