Skip to content

feat: add submodules init to nest all submodules at once - #228

Merged
thorsten-klein merged 1 commit into
mainfrom
feat/184-submodules-init
Nov 14, 2026
Merged

thorsten-klein merged 1 commit into
mainfrom
feat/184-submodules-init

Conversation

@thorsten-klein

@thorsten-klein thorsten-klein commented Nov 14, 2026 •

Copy link
Copy Markdown
Owner

What this changes

A new command turns all submodules of a repository into nested
repositories:

git nested submodules init                  # the first level
git nested submodules init --recursive      # also deeper ones
git nested submodules init --only lib/core  # only some
  • Each submodule gets one commit.
  • --only and --ignore pick some of them. init keeps the choice in
    .gitmodules.
  • --resolve-relative <url> resolves relative submodule urls. Without it,
    init stops at one. In a fork, origin is the wrong base.
  • The choice goes into .gitnested as submodules: nest or keep.
  • A branch or push of a nested repo inside a nested repo leaves the outer
    one alone.

Why

Part one of #184. #202 builds on it: submodules merge and submodules pull keep the nested repos in step with upstream.

Stack: #228 (this) → #202.

Checklist

  • uv run poe all passes (ruff, mypy, pyright, bandit, complexipy, and the
    tests at 100% coverage)
  • New behaviour has a test
  • README / --help / the man page updated, if the change is visible to users
  • The PR title reads as a Conventional Commit
    (feat:, fix:, docs:, …) — it becomes the squash-merge commit message
    and the changelog line

`git nested submodules init` turns each submodule into a nested repo, at
the commit it pins. Each one gets a commit.

- `--recursive` nests their submodules too, at any depth.
- `--only` and `--ignore` pick some of them. `init` keeps the choice in
  .gitmodules.
- `--resolve-relative <url>` resolves relative submodule urls. Without
  it, `init` stops at one.
- The choice goes into .gitnested as `submodules: nest` or `keep`.
- A branch or push of a nested repo inside a nested repo leaves the
  outer one alone.

Refs #184
@codecov

codecov Bot commented Nov 14, 2026 •

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 100.00%. Comparing base (3189981) to head (eda7678).
⚠️ Report is 1 commits behind head on main.
✅ All tests successful. No failed tests found.

Additional details and impacted files

Impacted file tree graph

@@            Coverage Diff            @@
##              main      #228   +/-   ##
=========================================
  Coverage   100.00%   100.00%           
=========================================
  Files           50        51    +1     
  Lines         2907      2985   +78     
=========================================
+ Hits          2907      2985   +78     
Files with missing lines Coverage Δ
src/git_nested/cli/location.py 100.00% <100.00%> (ø)
src/git_nested/cli/parser.py 100.00% <ø> (ø)
src/git_nested/cli/spec.py 100.00% <ø> (ø)
src/git_nested/commands/__init__.py 100.00% <ø> (ø)
src/git_nested/commands/clone.py 100.00% <100.00%> (ø)
src/git_nested/commands/config.py 100.00% <ø> (ø)
src/git_nested/commands/init.py 100.00% <100.00%> (ø)
src/git_nested/commands/pull.py 100.00% <100.00%> (ø)
src/git_nested/commands/submodules.py 100.00% <100.00%> (ø)
src/git_nested/commands/verify.py 100.00% <100.00%> (ø)
... and 4 more

@sonarqubecloud

Copy link
Copy Markdown

@thorsten-klein
thorsten-klein merged commit 70b690e into main Nov 14, 2026
15 checks passed
@thorsten-klein
thorsten-klein deleted the feat/184-submodules-init branch November 14, 2026 08:46
thorsten-klein added a commit that referenced this pull request Nov 14, 2026
## What this changes

A new command keeps the nested repos of `submodules init` (#228) in step
with upstream:

```bash
git fetch upstream
git nested submodules update --dry-run upstream/main  # see what it would do
git nested submodules update upstream/main            # merge, then update the nested repos
```

`update` merges the commit and keeps each upstream commit, with its SHA
and author. Then it changes the nested repos the way upstream changed
its
submodules. Each changed submodule gets one commit. It never fetches.

| Upstream did | `update` does |
|---|---|
| moved a pin | pull the nested repo to it. Local changes stay |
| added a submodule | nest it, as `submodules:` in `.gitnested` says |
| removed a submodule | remove the nested repo. Warn if it had local
changes |
| moved a submodule | move the folder. Local changes stay |
| changed a url | write the new `remote` |

- It keeps what `init` chose. A new submodule that `--only` or
`--ignore`
leaves out stays a submodule. So does one with `update = none`, as in
git.
- Options: `--dry-run` (also shows deeper nested repos),
`--single-commit`,
  `--continue`, `--abort`, `-S`, `--signoff`.
- A nested repo with a `pin` stays where it is.
- If the commit is merged already, `update` only updates the nested
repos
  that lag behind. So after `--abort`, a second run does the rest.
- A plain `git merge` of upstream is not the way. `update` says to abort
it
  and use `update` instead.
- Nested repos with patches work: the patches go on the new pin.

It also fixes what a test on tdesktop found (see #184):

- `update = none` submodules got nested. Now they stay submodules, also
in
  `init` and `clone --recurse-submodules`.
- `--abort` left a half sync and the stopped worktree.
- git-nested's block in `.gitattributes` conflicted with new upstream
rules.
- `--dry-run` missed deeper submodules.
- LF files that a parent rule would check out with CRLF now stay LF.
- A conflict in a nested repo showed the steps of a plain `pull`. Now it
  shows only `update --continue` and `--abort`.

### Trade-offs

- The upstream commits come in as they are. So they still have their
  gitlinks. A checkout of one shows empty submodule folders. Use
  `git bisect --first-parent`. Your own commits never have a gitlink.
- By default the merge commit comes first. One commit per submodule
  follows. `--single-commit` makes one merge commit instead.

### Speed

20 submodules, all moved by upstream: about 11 s with local repos. No
submodule moved: 0.25 s. Over a network, each moved submodule adds one
fetch.

## Why

A fork of a project with submodules wants plain files, the upstream
history, and updates from upstream. A plain `git merge` of upstream
breaks
on the gitlinks.

Fixes #184

## Checklist

- [x] `uv run poe all` passes (ruff, mypy, pyright, bandit, complexipy,
and the
      tests at 100% coverage)
- [x] New behaviour has a test
- [x] README / `--help` / the man page updated, if the change is visible
to users
- [x] The PR title reads as a [Conventional
Commit](https://www.conventionalcommits.org)
(`feat:`, `fix:`, `docs:`, …) — it becomes the squash-merge commit
message
      and the changelog line
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant