Defame1297
14af50bc07
git-workflow's description enumerated the six domains it exists to route away from, so it competed for selection with the very skills it should be handing off to. It now triggers on the case it actually serves: an interactive request whose domain is not yet clear. Also clears frontmatter drift across the plugin and removes duplicated guidance in pc-run that had diverged from its reference.
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>