Proposal: modularize `bin/git-forgit` into a stable entrypoint plus `lib/`

[wfxr]

Background

bin/git-forgit currently acts as the executable entrypoint, the shared helper library, the implementation of every command, the implementation of preview/private commands, and the dispatcher. As forgit keeps growing, this single-file structure increases review cost, makes reuse harder, and raises the chance of accidental coupling between unrelated commands.

I would like to propose a larger refactor that keeps the current user-facing behavior intact, while reorganizing the implementation into a clearer internal structure.

Goals

• Keep bin/git-forgit as the stable executable entrypoint.
• Split shared helpers and command entrypoints into lib/.
• Keep the first phase simple: load everything up front, then dispatch as today.
• Preserve both primary usage modes:
  • shell plugin usage in bash/zsh/fish
  • git forgit <command> usage via git-forgit on $PATH
• Make internal helpers easier to reuse without copying code or sourcing the entire bin/git-forgit.

Non-goals

• No command renames.
• No alias or completion behavior changes.
• No lazy-loading in the first phase.
• No promise that lib/* becomes a stable public API.

Proposed structure

bin/
  git-forgit

lib/
  bashunit
  core.sh
  helpers/
    ansi.sh
    git.sh
    parse.sh
    pager.sh
    path.sh
    preview.sh
    repo.sh
    select.sh
    text.sh
  forgit.sh

• bin/git-forgit
  • stays as the stable executable entrypoint
  • is responsible for setup, loading modules, and dispatch
• lib/core.sh
  • contains paths, constants, environment setup, and the most fundamental shared helpers
• lib/helpers/*.sh
  • contains reusable helpers grouped by capability rather than by command/domain
• lib/forgit.sh
  • contains command entrypoints and private command entrypoints
  • would ideally stay thin and orchestration-focused

Why keep a separate lib/forgit.sh?

Keeping a separate lib/forgit.sh makes the boundary clearer:

• bin/git-forgit becomes a small and stable entrypoint
• command implementation can continue to evolve without repeatedly reshaping the executable wrapper itself

Why group helpers by capability?

One goal here is to encourage reuse rather than local reimplementation where possible.

For that reason, it may be more useful to group helpers primarily by capability, such as parsing, selection, preview building, text processing, git wrappers, and path handling, instead of grouping them by command/domain from the start.

That makes it easier for a new command to compose existing helpers, instead of adding yet another command-local helper block.

lib/api.sh

It may also be worth reserving room for a future lib/api.sh, without making it part of phase 1.

The idea would be:

• lib/api.sh can expose many internal helpers
• this is for convenience and reuse, not as an officially supported stable API
• external consumers may use it, but it should be understood as depending on forgit internals
• helpers exposed there may change, move, be renamed, or be removed at any time

So api.sh would be a centralized export surface for internal implementation, not a compatibility promise.

Loading model

One possible way to keep phase 1 simple is:

1. bin/git-forgit resolves FORGIT_INSTALL_DIR
2. it loads lib/core.sh
3. it loads the helper modules
4. it loads lib/forgit.sh
5. it dispatches to _forgit_"${cmd}"

The main point of this phase would be structural cleanup rather than changing execution semantics.

Compatibility requirements

In particular, it would be important not to break either of the two main ways people use forgit:

1. Shell plugin mode

Ideally these would continue to work without requiring user config changes:

• forgit.plugin.zsh
• forgit.plugin.sh
• conf.d/forgit.plugin.fish

That includes:

• existing wrapper functions
• existing aliases / abbreviations
• existing FORGIT_* configuration behavior
• worktree wrappers with cd behavior

2. Git subcommand mode

These would ideally keep working as they do today:

• git forgit <command>
• git aliases that expand to forgit ...

That suggests git-forgit should remain the executable name and should stay self-contained as an entrypoint.

3. Completions

The existing bash/zsh/fish completion behavior would ideally remain unchanged in phase 1.

Risks

• reviewers may interpret lib/api.sh as a stable API unless we explicitly document otherwise
• packaging/install paths may miss newly added lib/** files

Alternatives considered

Keep everything in one file and only reorganize sections

Pros:

• lowest risk
• minimal packaging/testing impact

Cons:

• does not create real module boundaries
• is less helpful for improving helper reuse
• continues to keep bin/git-forgit as the main implementation container

Add lazy-loading from the start

Pros:

• could enable finer-grained loading later

Cons:

• adds more shell complexity immediately
• makes the first refactor harder to reason about and review

Open questions

• How coarse- or fine-grained should the initial lib/helpers/*.sh split be?
• Is it worth splitting lib/forgit.sh further at all, and if so, when?
• Is it worth preserving existing helper names during the initial move and deferring naming cleanup to a later pass?
• Is it worth eventually consolidating subcommand metadata—such as names, descriptions, and completion behavior—so bash, zsh, and fish completions can share a single definition?

Summary

My current inclination would be to:

• keep bin/git-forgit as the stable entrypoint
• move shared logic into lib/
• keep phase 1 fully eager-loaded
• organize helpers by capability
• treat any future lib/api.sh as a convenience export layer for internals, not as a stable public API

---

@cjappl @carlfriedrich @sandr01d would love to hear what you all think too. Does this direction seem reasonable? Especially curious whether the split between bin/git-forgit, lib/forgit.sh, and lib/helpers/* feels right.

[sandr01d]

I like this idea. I'm a bit concerned about how much forgit has grown in code size and splitting things up should make things easier to maintain in the long run. Pushing towards having an API layer (for lack of better terms) could also help in making bigger parts of the project unit testable.
Regarding the proposed structure, I would like to propose the following change:

Instead of having e.g. preview.sh, which (at least that's what I'd assume from the name) contains all the preview functions I would propose to have e.g., log.sh, diff.sh, etc. Where log.sh would contain

• _forgit_log_preview
• _forgit_log_enter
• _forgit_git_log

and diff.sh would contain

• _forgit_exec_diff
• _forgit_diff_view
• _forgit_edit_diffed_file
• _forgit_diff_enter

Generic helper functions would go into separate files like ansi.sh and path.sh as you proposed.

This would have two benefits:

1. When working on a specific forgit command, you have most of what's relevant visible at a glance.
2. Improves performance if we decide to introduce lazy loading. Instead of loading all the _forgit*_preview and _forgit_git_* functions for every command we create a batch of functions that are often used together.

I think this also answers most of the question regarding the granularity of the helpers.

At what point should lib/forgit.sh be split further?

I think this is something we'll be equipped to answer once we've done the transition. Maybe it won't even be necessary.

Should some helper naming be normalized during the refactor, or kept as-is until after the move?

I'd prefer to do this in a second step not part of the initial refactoring. This is already a big undertaking as is.

Is it worth consolidating command metadata further for completions later?

I'm not sure what you mean with "command metadata"...

I'm also wondering which workflow we should use to achieve this. I'd prefer split the refactoring up into multiple smaller parts to make the review process easier. Maybe it would be a good idea to tackle this as a somewhat longer running PR that gets reviewed with each new commit. For the commit structure I would go with something like

• refactor: add infrastructure to allow modularizing forgit
• refactor: move pager helper functions to pager.sh
• refactor: move log helper functions to log.sh
• refactor: move diff helper functions to diff.sh
• ...
• refactor: move path helper functions to path.sh
• ...
• refactor: update docs according to the new modular structure

WDYT?

[wfxr]

@sandr01d Thanks, this is very helpful feedback.

I think your distinction between truly generic helpers and command-local logic makes a lot of sense. Keeping things like _forgit_log_preview, _forgit_log_enter, and _forgit_git_log together in log.sh, and the diff-related helpers together in diff.sh, feels better for local readability and would also make a future lazy-loading step more natural.

So I think the right direction is probably a hybrid one:

• keep bin/git-forgit as the stable entrypoint
• move fundamental/shared pieces into lib/core.sh plus a small set of generic helper modules like ansi.sh, path.sh, parse.sh, pager.sh, etc.
• group command-specific preview / enter / wrapper logic by command, e.g. log.sh, diff.sh, ...

That feels like a better fit than pushing too much into capability-oriented buckets like preview.sh.

On the “command metadata” point: what I meant was whether, in a later phase, it would be useful to keep a single source of truth for subcommand definitions used by completions — e.g. names, descriptions, and which completion behavior they map to in bash/zsh/fish — so we do not have to duplicate that information across multiple completion files. Not for phase 1, just as a possible follow-up once the structure is cleaner. I’ve also reworded those open questions in the issue to make that clearer.

And yes, I agree with keeping the initial refactor narrow and doing it as a series of small reviewable commits.

[sandr01d]

On the “command metadata” point: what I meant was whether, in a later phase, it would be useful to keep a single source of truth for subcommand definitions used by completions — e.g. names, descriptions, and which completion behavior they map to in bash/zsh/fish — so we do not have to duplicate that information across multiple completion files. Not for phase 1, just as a possible follow-up once the structure is cleaner. I’ve also reworded those open questions in the issue to make that clearer.

Sounds good and I agree to do this in a second step after the big refactoring.

I think we probably should try to get #489 and #474 merged before the refactor because I think that rebasing the PRs will be tricky.

[carlfriedrich]

Thanks for coming up with this concept @wfxr. I am always in for a well though-out project structure, and I am sure maintaining forgit will benefit from this.

However, while I definitely consent this on a source code level, I always liked that forgit is so compact on a distribution level.

So what about leveraging the advantages of the proposed structure, while still keeping the distribution simple? bashunit for example does something similar: a well-structured source code tree which gets "compiled" (not in the meaning of generating machine code) into one single distributable shell script.

WDYT?

[wfxr]

@carlfriedrich Thanks, this is a good suggestion.

I agree it would be nice to keep the source tree modular while still preserving a compact distribution story. A generated single-file git-forgit could be a good follow-up once the internal structure is cleaner.

My preference would be not to fold that into phase 1, though. For the initial refactor I would like to keep the scope narrow: reorganize the source, keep bin/git-forgit as the stable entrypoint, keep eager loading, and avoid introducing new build/release concerns at the same time.

But yes, I think we should keep the refactor compatible with that direction.

[sandr01d]

My preference would be not to fold that into phase 1, though. For the initial refactor I would like to keep the scope narrow: reorganize the source, keep bin/git-forgit as the stable entrypoint, keep eager loading, and avoid introducing new build/release concerns at the same time.

I think we should do this in the same PR as the refactoring but after everything else has been done and reviewed. Otherwise the AUR PKGBUILDs and the homebrew formula would have to be updated just to be changed back later.

[wfxr]

I think a reasonable compromise would be to do this on a short-lived refactor/modularize branch, while still splitting it into a series of reviewable PRs.

So the rough workflow would be:

• open a refactor/modularize branch for the refactor
• stack a series of focused, behavior-preserving PRs on top of it
• once the initial modularization is done, rebase it onto the latest main and merge it back

That way we keep main stable while the refactor is in progress, but still review the work incrementally instead of as one large PR.

I think this also gives us a cleaner point to decide the packaging/distribution question before the refactor lands on main, instead of forcing that decision at the very beginning.

[carlfriedrich]

The idea with the refactor-branch spanning multiple PRs is a solid approach IMO. ✅

[carlfriedrich]

Concerning the "build" I think we might be able to port bashunit's build script to forgit by removing everything that's not applicable to our repo as a solid starting point.

In the end it doesn't do anything more than copying several shell script files into one self-contained script in a defined order, which is probably what we need here as well.

I even think that the build script is the step that we might start with (it will work with a single file input as well, i.e. the current forgit codebase). I think this will make validating the refactorings a lot easier.