Defame1297
38efd2be67
An independent audit of the ADR-0020 retrofit (issue #99) found that git-submodules, git-worktrees, and gitea-files each collapsed their description length correctly during retrofit but left the capability clause as a verb enumeration (e.g. "Create, list, lock, move, remove, prune, or repair") instead of ADR-0020's required single clause. The deterministic char-count gate can't catch this — it's a qualitative rubric violation the retrofit commits' own messages never claimed to address, only measurable length/word-count fixes. Validated clean via skill-audit and skill-size-check after the fix; boundary clauses and routing targets left untouched. Refs #99
2.7 KiB
name, description, metadata
| name | description | metadata | |||||
|---|---|---|---|---|---|---|---|
| git-submodules | Use when managing Git submodules — the full lifecycle of a nested repository inside a superproject. Not multiple checkouts of one repo -> `git-worktrees`. Not the superproject's own remotes -> `git-remotes`. |
|
Gotchas
updateleaves the submodule in detached HEAD. Branch inside the submodule before editing, or the work is unreachable once the pointer moves.- Push the submodule before the superproject. The superproject stores only a SHA, and one missing from the submodule's remote breaks every collaborator's
update. --recursiveis never the default. Subcommands stop one level deep, so nested submodules go stale silently.git rmleaves.git/modules/<name>/behind. Nothing cleans it up, and it blocks re-adding a submodule there.
Working rules
Run rtk git from the superproject root. Enter the submodule directory only for commits and pushes
that belong to the submodule's own history — the two repositories have independent histories, and
the same command from the wrong directory writes to the wrong one.
Before committing a superproject pointer, run rtk git submodule status --recursive. Prefixes: -
not initialized, + working tree differs from the recorded commit, U merge conflict. Add
--cached to read the SHAs the superproject index will record rather than the working-tree state.
A -dirty suffix means uncommitted changes inside the submodule, and committing the pointer over
them pins a state nobody else can reproduce.
To run one command across every submodule: rtk git submodule foreach --recursive '<cmd>'. Inside
<cmd>, Git sets $name, $sm_path, $displaypath, $sha1 and $toplevel; append || : to
continue past a failure instead of aborting the traversal.
Dispatch
Read only the row that matches the request.
| Task | Reference |
|---|---|
| Clone a superproject with submodules, or add, initialize, update or re-pin one | references/setup-and-update.md |
Change where a submodule points — sync, set-url, set-branch, a local mirror override, absorbgitdirs, or any .gitmodules / .git/config key |
references/urls-and-config.md |
Remove a submodule, or deinit one without removing it |
references/removal.md |
Removal and deinit are destructive: state what will be deleted and get confirmation before
executing.
Output format
operation: <clone|add|init|update|status|sync|set-url|set-branch|absorbgitdirs|deinit|remove>
status: <success|error|partial>
message: <one line; include git's own output on error>
details:
- <submodule-path>: <state>
conflicts: [<submodule-path>, ...]
next_step: <recovery action, when status is error or partial>