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.
63 lines
2.7 KiB
Markdown
63 lines
2.7 KiB
Markdown
---
|
|
name: git-submodules
|
|
|
|
description: >
|
|
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`.
|
|
|
|
metadata:
|
|
category: git
|
|
source_keys:
|
|
- git-scm-submodule-docs
|
|
---
|
|
|
|
## Gotchas
|
|
|
|
- **`update` leaves 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`.
|
|
- **`--recursive` is never the default.** Subcommands stop one level deep, so nested submodules go stale silently.
|
|
- **`git rm` leaves `.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
|
|
|
|
```yaml
|
|
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>
|
|
```
|