Skip to content

Accept clean submodules in SwiftPM checkouts - #34

Draft
mattt wants to merge 2 commits into
mainfrom
mattt/swiftpm-submodules
Draft

mattt wants to merge 2 commits into
mainfrom
mattt/swiftpm-submodules

Conversation

@mattt

@mattt mattt commented Nov 17, 2026

Copy link
Copy Markdown
Owner

Plonge refused a SwiftPM .build or Xcode DerivedData folder whenever a dependency's checkout had a Git submodule, even right after swift package resolve. SwiftPM initializes submodules when it makes a checkout, so the Git directory in the checkout's .git/modules is part of a cache that SwiftPM can make again. GRDB.swift, with its SQLiteCustom/src submodule, is the example in the issue.

Plonge now lets through a submodule of an accepted checkout, in .build/checkouts and in SourcePackages/checkouts, when all of these hold:

  • .gitmodules at the parent's HEAD gives the submodule's path one name and one URL, the submodule's .git file names .git/modules/<name> in the parent, and that Git directory has no commondir, no linked worktrees, and a core.worktree that names the submodule's folder.
  • Its HEAD is the commit that the parent's HEAD records for its path.
  • It passes the checkout's checks: no changed, untracked, or ignored files, no stash, no files marked assume-unchanged or skip-worktree, and no reflog entry for a push to origin.
  • Its one remote, origin, and submodule.<name>.url in the parent's configuration are the URL in .gitmodules, compared as a bare clone's origin is compared with a pin's location.
  • Every commit in it is in HEAD or in refs/remotes/origin.
  • Each submodule of the submodule passes the same checks.

These rules are stricter than the criteria in the issue in a few places. A submodule has no bare clone in the cache to compare its tags with, so a tag does not count, and a tag at a commit outside HEAD and the remote-tracking refs refuses the folder. A relative URL in .gitmodules is refused. Plonge compares URLs as written and does not apply url.<base>.insteadOf; Git stores the URL before it rewrites it, so a rewritten URL still matches. A Git directory that git submodule deinit leaves in .git/modules is refused, and so is a .git file that is not part of a submodule that passes.

One existing behavior changes. git status does not look inside the folder of a submodule that is not initialized, so Plonge accepted a checkout with files there. It now refuses that checkout, and accepts a submodule that is not initialized only when its folder is empty.

The checks run offline, so they cannot tell whether a commit in a submodule's refs/remotes/origin refs is still at its origin, or was put there without a push. When git status in the checkout reports the submodule, for a changed or untracked file or another commit, the reason names the checkout and not the submodule.

The reproduction in the issue also failed a second check. SwiftPM names the checkout's folder GRDB.swift and writes the identity in Package.resolved as grdb.swift, and Plonge looked up the pin by the folder name as written. The first commit looks it up in lower case, which affects every dependency whose name has a capital letter.

Closes #33

SwiftPM names a checkout's folder after the last element of the dependency's URL, such as GRDB.swift, and records the identity in Package.resolved in lower case, grdb.swift. Plonge looked up the pin by the folder name as written, so it refused the checkout of any dependency whose name has a capital letter. The reproduction in issue 33 fails on this check once the submodule check passes.
SwiftPM initializes a dependency's submodules when it makes a checkout, so a .build or DerivedData folder with a dependency such as GRDB.swift held a Git directory in .git/modules that Plonge refused, even right after swift package resolve (issue 33).

Plonge now lets through a submodule of an accepted checkout, recursively, when its Git directory is the one that .gitmodules names in the parent's .git/modules, its HEAD is the commit that the parent records, it passes the checkout's checks for local changes, and its origin is the URL in .gitmodules. A submodule has no bare clone in the cache to compare tags with, so every commit must be in HEAD or in refs/remotes/origin.

git status does not look inside the folder of a submodule that is not initialized, so a checkout with files there is now refused.
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.

SwiftPM .build refused when a dependency checkout has a Git submodule (e.g. GRDB.swift)

1 participant