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
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
|
|
|
|
```
|
|
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>
|
|
```
|