Defame1297/holocron
0
0
Fork 0
Code Issues 14 Pull Requests Actions Packages Projects Releases 3 Wiki Activity

refactor(git-submodules): retrofit to the ADR-0020 context contract

Browse Source 
Description 480 -> 248 chars, body 1011 -> 347 words. The single
submodules.md splits into setup-and-update, urls-and-config, and removal.

Restores three regressions the first pass introduced: 'repointing' as the
trigger for the URL branch, which had none while the boundary clause
steered those queries to git-remotes; clone and absorbgitdirs in the output
enum, which dispatch still routed to; and status --cached, the flag that
makes the pre-commit pointer gate verifiable.
This commit is contained in:
Defame1297
2026-08-30 13:10:53 +00:00
parent 3c74beb280
commit 261e5b5491
16 changed files with 512 additions and 328 deletions
Download Patch File Download Diff File Expand all files Collapse all files

21
plugins/git/.apm/skills/git-submodules/README.md
View File

@@ -1,10 +1,17 @@
# git-submodules # git-submodules
Initialize, clone, update, and manage git submodules for multi-repository projects. Add, initialize, update, pin, inspect, and remove git submodules in multi-repository projects.
## What it does ## What it does
This skill handles submodule operations within the git workflow suite. It initializes submodules, clones repositories with nested submodule dependencies, updates submodule pinning, and manages version control across multi-repo projects. The skill provides clean workflows for projects with complex dependency structures and returns structured results suitable for agent composition. This skill handles submodule operations within the git workflow suite: cloning a superproject with
its nested repositories, adding a dependency as a submodule, initializing and updating with
pinning or branch tracking, parallel and recursive traversal, rebinding URLs and tracked branches,
and the full removal sequence including the `.git/modules/` cleanup git leaves behind. It returns
structured results suitable for agent composition.
It sits alongside the other git skills rather than duplicating them: `git-worktrees` covers
multiple checkouts of a single repository, and `git-remotes` covers the superproject's own remotes.
## Usage ## Usage
@@ -12,13 +19,17 @@ This skill handles submodule operations within the git workflow suite. It initia
/git-submodules /git-submodules
``` ```
Describe your submodule task: initialize, clone, update, or manage versions. The skill will handle the operation and return structured results (operation, status, per-submodule details, conflicts, and a recovery `next_step` when applicable) suitable for agent composition. Describe the submodule task. The skill applies the shared working rules, dispatches to the
reference for that task, and returns structured results (operation, status, per-submodule details,
conflicts, and a recovery `next_step` when applicable).
## Files ## Files
| File | Purpose | | File | Purpose |
|------|---------| |------|---------|
| `SKILL.md` | Skill instructions for agents | | `SKILL.md` | Skill instructions for agents — gotchas, shared working rules, and the task dispatch table |
| `references/README.md` | Describes contents of references/ | | `references/README.md` | Describes contents of references/ |
| `references/submodules.md` | Deep-dive reference: full flag tables, workflow patterns, safe-removal sequence, `absorbgitdirs`, `foreach` variables | | `references/setup-and-update.md` | Loaded when cloning a superproject, adding a submodule, or initializing, updating, or re-pinning one — includes the full `add` and `update` flag tables and the pinning workflows |
| `references/urls-and-config.md` | Loaded when changing where a submodule points or how it is configured — `.gitmodules` vs `.git/config` anatomy, both key tables, `sync`/`set-url`/`set-branch`, local mirror overrides, relative URLs, the custom-`update` security gate, and `absorbgitdirs` |
| `references/removal.md` | Loaded when removing or deinitializing a submodule — why `deinit` is not removal, and the four-step removal sequence |
| `references/sources.md` | Research sources and provenance | | `references/sources.md` | Research sources and provenance |

95
plugins/git/.apm/skills/git-submodules/SKILL.md
View File

@@ -2,7 +2,10 @@
name: git-submodules name: git-submodules
description: > description: >
Use when managing Git submodules: add dependencies as submodules, initialize and update nested repositories, sync URLs, inspect status (including detached HEAD and divergence), and safely remove submodules. Handles multi-repo projects with pinning, parallel operations, and recursive traversal. Use for both initial setup and ongoing maintenance workflows, even if the user doesn't explicitly say "submodule". Do not use for general git operations outside of submodule management. Use when managing Git submodules — adding, updating, pinning, inspecting,
repointing, or removing a nested repository inside a superproject.
Not multiple checkouts of one repo -> `git-worktrees`.
Not the superproject's own remotes -> `git-remotes`.
metadata: metadata:
category: git category: git
@@ -10,82 +13,50 @@ metadata:
- git-scm-submodule-docs - git-scm-submodule-docs
--- ---
## Concept
A submodule is a full Git repository embedded as a subdirectory inside a parent repository (the superproject). The superproject doesn't store the submodule's files — it stores a pointer to a specific commit SHA in the submodule's own history, and the two repos keep fully independent commit histories.
Two files govern a submodule, and they serve different audiences:
- **`.gitmodules`** — version-controlled, shared with collaborators. Defines each submodule's name, path, and canonical URL.
- **`.git/config`** — local only, populated by `git submodule init`. This is where local URL overrides live (e.g. a private mirror) — they never propagate to other clones.
The submodule's own `.git` directory lives at `.git/modules/<name>/` in the superproject, linked to the submodule's working tree via a `.git` pointer file. After `git submodule update`, the working tree normally ends up in **detached HEAD state** — see Gotchas.
## Gotchas ## Gotchas
- **Detached HEAD by default.** `git submodule update` checks out a specific commit, not a branch. Work on a branch first, then update the pointer in the superproject. Commits made in detached state are invisible until pinned. - **`update` leaves the submodule in detached HEAD.** Branch inside the submodule before editing, or the work is unreachable once the pointer moves.
- **Two pushes required, in order.** Always commit and push the submodule first, then update and push the superproject's pointer. The superproject only stores a commit SHA — if that SHA isn't reachable on the submodule's remote yet, `git submodule update` fails for anyone who pulls the superproject before the submodule push lands. - **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 not default.** Most commands operate one level deep. Pass `--recursive` explicitly for nested submodules. - **`--recursive` is never the default.** Subcommands stop one level deep, so nested submodules go stale silently.
- **`.git/modules/` persists after `git rm`.** Manual cleanup is needed: `rm -rf .git/modules/<name>/`. - **`git rm` leaves `.git/modules/<name>/` behind.** Nothing cleans it up, and it blocks re-adding a submodule there.
- **Detached HEAD detection.** Status prefix `+` means the checked-out commit differs from the superproject's recorded commit — normal after `update --remote`, but should be re-pinned before committing.
- **Relative URLs resolve against the remote, not the filesystem.** A `../foo.git` entry in `.gitmodules` is relative to the superproject's default remote URL.
- **Custom `update` commands are security-gated.** A `.gitmodules` entry of `update = !some-command` is never copied to `.git/config` by `git submodule init` — this stops a clone from silently executing arbitrary code.
## Conventions ## Working rules
- **Use `rtk git` for parent-repo operations.** Drop into the submodule directory only for submodule-specific git commands (committing/pushing inside the submodule itself) — mixing the two from the wrong working directory targets the wrong repo's history. Run `rtk git` from the superproject root. Enter the submodule directory only for commits and pushes
- **Check for a dirty submodule before committing the parent pointer.** After adding or updating a submodule, run `git status` in both the parent and the submodule. A `-dirty` suffix means the submodule has uncommitted local changes; committing the parent pointer now would pin a state no one else can reproduce, since those changes exist only in the local working tree. 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.
## Operations 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.
- **Clone a repo that has submodules**: `rtk git clone --recurse-submodules <url>` (one step, Git 2.13+) or `rtk git clone <url>` followed by `rtk git submodule update --init --recursive`. To run one command across every submodule: `rtk git submodule foreach --recursive '<cmd>'`. Inside
- **Add a submodule**: `rtk git submodule add <url> <path>` (`-b <branch>` to track a branch instead of a pinned commit, `--depth 1` for a shallow clone, `-f` to force past a gitignored path or name conflict, `--name <name>` when the logical name should differ from the path). Stages a `.gitmodules` entry and a gitlink — a commit is still required. `<cmd>`, Git sets `$name`, `$sm_path`, `$displaypath`, `$sha1` and `$toplevel`; append `|| :` to
- **Initialize**: `rtk git submodule init [<path>...]` copies submodule URLs from `.gitmodules` to `.git/config`. This is the point at which local URL overrides can be edited before fetching. Does not clone — use `update` (or `update --init` to run both in one step). continue past a failure instead of aborting the traversal.
- **Update (clone + checkout)**: `rtk git submodule update --init --recursive` is the common case — checks out the recorded commit in detached HEAD. Add `--remote --merge` (or `--remote --rebase`) to track the branch tip instead, `--jobs <n>` for parallel clones, `-f` to discard local changes. Full flag table: `references/submodules.md`.
- **Inspect status**: `rtk git submodule status --recursive` (add `--cached` to show SHAs in the superproject index instead of the working tree). Status prefixes: `-` not initialized, `+` diverged from the superproject's recorded commit, `U` merge conflict.
- **Sync and rebind URLs**: `rtk git submodule sync --recursive` after an upstream URL rename propagates `.gitmodules` changes into `.git/config`. `rtk git submodule set-url <path> <url>` changes a URL directly; `rtk git submodule set-branch -b <branch> <path>` sets the tracking branch used by `update --remote`.
- **Override a submodule URL locally (private mirror)**: local-only, doesn't propagate to collaborators, and gets overwritten by the next `sync`. Full steps: `references/submodules.md`.
- **Run a command across all submodules**: `rtk git submodule foreach --recursive '<command>'`. Shell variables available inside `<command>` (`$name`, `$sm_path`, `$displaypath`, `$sha1`, `$toplevel`): `references/submodules.md`.
- **Deinit (unregister without removing)**: `rtk git submodule deinit <path>` (`--all` for every submodule, `-f` if local modifications are present) clears the `.git/config` section and empties the working tree. **`deinit` is not removal** — the `.gitmodules` entry and the gitlink in the superproject's index are untouched.
- **Safe removal** (destructive; confirm before executing) — full three-step sequence including the manual `.git/modules/` cleanup: `references/submodules.md`.
- **Move an embedded `.git` into `.git/modules/`**: `rtk git submodule absorbgitdirs [<path>...]` — needed when a submodule was created or copied without going through `git submodule add`. Details: `references/submodules.md`.
## Configuration ## Dispatch
`.gitmodules` (version-controlled, shared with collaborators): Read only the row that matches the request.
| Key | Purpose | | Task | Reference |
|---|---| |---|---|
| `submodule.<name>.path` | Working tree path | | Clone a superproject with submodules, or add, initialize, update or re-pin one | `references/setup-and-update.md` |
| `submodule.<name>.url` | Remote URL | | 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` |
| `submodule.<name>.branch` | Branch used by `update --remote` | | Remove a submodule, or `deinit` one without removing it | `references/removal.md` |
| `submodule.<name>.update` | Default update procedure |
| `submodule.<name>.shallow` | Recommend shallow clone |
`.git/config` (local only, populated by `init`): Removal and `deinit` are destructive: state what will be deleted and get confirmation before
executing.
| Key | Purpose | ## Output format
|---|---|
| `submodule.<name>.url` | Local URL override |
| `submodule.<name>.update` | Local procedure override |
| `submodule.fetchJobs` | Default parallelism for `update --jobs` |
| `submodule.recurse` | Auto-recurse submodule updates on `pull`/`push`/etc. |
```bash
rtk git config submodule.recurse true # keep submodules pinned automatically after every pull
``` ```
operation: <clone|add|init|update|status|sync|set-url|set-branch|absorbgitdirs|deinit|remove>
## Agent output format
Return results as structured data:
```
operation: <clone|add|init|update|sync|set-url|set-branch|status|summary|absorbgitdirs|remove>
status: <success|error|partial> status: <success|error|partial>
message: <human-readable summary> message: <one line; include git's own output on error>
details: details:
- <submodule-path>: <state> - <submodule-path>: <state>
conflicts: [<submodule-path>, ...] # if any conflicts: [<submodule-path>, ...]
next_step: <recovery action if applicable> next_step: <recovery action, when status is error or partial>
``` ```
For errors, include the git command output and recommend recovery (e.g., `git submodule deinit`, force-update, or URL override).

22
plugins/git/.apm/skills/git-submodules/references/README.md
View File

@@ -6,10 +6,26 @@ metadata:
# References # References
## submodules.md One file per task branch in SKILL.md's dispatch table. Load only the one that matches the request.
Deep-dive reference: full `update` flag table, workflow patterns (clone, add, keep-pinned, update-to-latest, override URL), the complete safe-removal sequence, `absorbgitdirs`, and `foreach` shell variables. Load when SKILL.md's condensed Operations list isn't enough detail. ## setup-and-update.md
Cloning a superproject that has submodules, adding a dependency as a submodule, initializing
without cloning, and updating or re-pinning. Carries the `add` and `update` flag tables and the
keep-pinned and move-the-pin-forward workflows.
## urls-and-config.md
Where a submodule points and how it is configured: the `.gitmodules` vs `.git/config` split, both
key tables, `sync` / `set-url` / `set-branch`, local mirror overrides, relative URL resolution, the
security gate on custom `update` commands, and `absorbgitdirs`.
## removal.md
Removing a submodule, and why `deinit` alone does not remove one. Carries the full four-step
removal sequence including the manual `.git/modules/<name>/` cleanup.
## sources.md ## sources.md
Research sources that informed this skill — provenance chain for git-scm-submodule-docs reference material. Research sources that informed this skill — provenance chain for git-scm-submodule-docs reference
material.

32
plugins/git/.apm/skills/git-submodules/references/removal.md Normal file
View File

@@ -0,0 +1,32 @@
---
topic: submodules
source_keys:
- git-scm-submodule-docs
---
# Removing and deinitializing a submodule
Both operations are destructive. Confirm with the user before executing either.
## `deinit` is not removal
```bash
git submodule deinit <path> # --all for every submodule, -f if locally modified
```
`deinit` clears the submodule's section from `.git/config` and empties its working tree. The
`.gitmodules` entry and the gitlink in the superproject's index are untouched, so the submodule is
still registered and a later `update --init` brings it straight back. Use it to reclaim disk space
or to reset a broken checkout, not to delete a dependency.
## Full removal, in order
```bash
git submodule deinit -f <path> # unregister from .git/config
git rm <path> # drop the .gitmodules entry and the gitlink from the index
rm -rf .git/modules/<name>/ # stale git dir: not tracked, not cleaned up by git
git commit -m "chore: remove <name> submodule"
```
The third step is the one that gets skipped. `.git/modules/<name>/` survives `git rm`, and while it
is present Git refuses to add a submodule at the same path again.

74
plugins/git/.apm/skills/git-submodules/references/setup-and-update.md Normal file
View File

@@ -0,0 +1,74 @@
---
topic: submodules
source_keys:
- git-scm-submodule-docs
---
# Adding, initializing, updating and pinning submodules
## Clone a superproject that already has submodules
```bash
git clone --recurse-submodules <url> # Git 2.13+, one step
# or, against an existing clone
git submodule update --init --recursive
```
## Add a dependency as a submodule
```bash
git submodule add <url> <path>
git commit -m "chore: add <name> as submodule"
```
`add` stages a `.gitmodules` entry and a gitlink — the commit is still required. Flags:
| Flag | Meaning |
|---|---|
| `-b <branch>` | Track a branch (`submodule.<name>.branch`) instead of only a pinned commit |
| `--depth <n>` | Shallow clone |
| `-f` | Force past a gitignored path or a name conflict |
| `--name <name>` | Logical name differing from the path |
## Initialize without cloning
`git submodule init [<path>...]` copies submodule URLs from `.gitmodules` into `.git/config` and
does nothing else. This is the point at which a local URL override can be edited before any fetch
happens. If a local mirror override is wanted, read `references/urls-and-config.md` before running
`update`. Use `update --init` to run both steps at once.
## Update
`git submodule update --init --recursive` is the common case: it clones what is missing and checks
out the commit the superproject recorded, in detached HEAD.
| Flag | Meaning |
|---|---|
| `--init` | Run `init` first, avoiding a separate step |
| `--remote` | Use the submodule's remote branch tip instead of the superproject's recorded commit |
| `--checkout` | Detached HEAD at the recorded commit (default) |
| `--rebase` | Rebase the current branch onto the recorded commit |
| `--merge` | Merge the recorded commit into the current branch |
| `--recursive` | Operate on nested submodules |
| `--jobs <n>` | Parallel clone (defaults to `submodule.fetchJobs`) |
| `-N` / `--no-fetch` | Skip the remote fetch |
| `-f` | Discard local changes in the submodule working tree |
| `--depth <n>` | Shallow clone |
| `--filter <spec>` | Partial clone filter |
## Keep submodules pinned to the recorded commit
```bash
git submodule update --recursive # after every git pull
git config submodule.recurse true # or do it automatically on pull/push/checkout
```
## Move the pin forward to the tracked branch tip
```bash
git submodule update --remote --merge --recursive
git commit -am "chore: update submodules to latest"
```
`--remote` requires `submodule.<name>.branch`; without it Git falls back to the remote's default
branch. Commit the superproject afterwards or the new pin is lost on the next `update`.

4
plugins/git/.apm/skills/git-submodules/references/sources.md
View File

@@ -14,7 +14,9 @@ source_keys:
**Contributing files:** **Contributing files:**
- SKILL.md (all sections) - SKILL.md (all sections)
- references/submodules.md (all sections) - references/setup-and-update.md (all sections)
- references/urls-and-config.md (all sections)
- references/removal.md (all sections)
--- ---

93
plugins/git/.apm/skills/git-submodules/references/submodules.md
View File

@@ -1,93 +0,0 @@
---
topic: submodules
source_keys:
- git-scm-submodule-docs
---
# Submodules — Deep Reference
## Update flag reference
| Flag | Meaning |
|---|---|
| `--init` | Run init first (avoids a separate step) |
| `--remote` | Use the submodule's remote branch tip instead of the superproject's recorded commit |
| `--checkout` | Detached HEAD at recorded commit (default) |
| `--rebase` | Rebase current branch onto recorded commit |
| `--merge` | Merge recorded commit into current branch |
| `--recursive` | Operate on nested submodules |
| `--jobs <n>` | Parallel clone (defaults to `submodule.fetchJobs`) |
| `-N` / `--no-fetch` | Skip remote fetch |
| `--depth <n>` | Shallow clone |
| `--filter <spec>` | Partial clone filter |
## Workflow patterns
### Clone a repo with submodules
```bash
git clone --recurse-submodules <url> # Git 2.13+, one step
# or
git clone <url>
git submodule update --init --recursive
```
### Add a dependency as a submodule
```bash
git submodule add https://github.com/org/lib.git libs/lib
git commit -m "chore: add lib as submodule"
```
### Keep submodules pinned to the superproject's recorded commit
```bash
git submodule update --recursive # after every git pull
git config submodule.recurse true # do this automatically on pull
```
### Update submodules to the latest commit on their tracked branch
```bash
git submodule update --remote --merge --recursive
git commit -am "chore: update submodules to latest"
```
### Override a submodule URL locally (private mirror)
```bash
git submodule init
# edit .git/config: submodule.<name>.url = <mirror-url>
git submodule update
```
Local-only override (`.git/config`, not `.gitmodules`) — doesn't propagate to collaborators. Re-running `sync` overwrites it with the `.gitmodules` URL.
## Removal, in full
`deinit` alone does not remove a submodule — it only clears `.git/config` and empties the working tree. To fully remove:
```bash
git submodule deinit -f <path> # unregister from .git/config
git rm <path> # remove .gitmodules entry + gitlink from index
rm -rf .git/modules/<name>/ # stale git dir; not tracked by git, not auto-cleaned
git commit -m "chore: remove <name> submodule"
```
`.git/modules/<name>/` persisting after `git rm` will block re-adding the same path until manually deleted.
## Relocate an embedded `.git` directory
```bash
git submodule absorbgitdirs [<path>...]
```
Moves a submodule's own `.git` directory into the superproject's `.git/modules/<name>/`, linking it back with a `.git` pointer file. Needed when a submodule was created or copied without going through `git submodule add` (e.g. converting a plain nested repo into a proper submodule).
## `foreach` shell variables
Available inside the `<command>` argument to `git submodule foreach`:
| Variable | Meaning |
|---|---|
| `$name` | Logical submodule name |
| `$sm_path` | Path relative to superproject root |
| `$displaypath` | Path relative to current working directory |
| `$sha1` | Recorded commit SHA |
| `$toplevel` | Superproject's root path |
```bash
git submodule foreach --recursive '<command>'
git submodule foreach 'git pull origin main || :' # || : continues past failures
```

79
plugins/git/.apm/skills/git-submodules/references/urls-and-config.md Normal file
View File

@@ -0,0 +1,79 @@
---
topic: submodules
source_keys:
- git-scm-submodule-docs
---
# Where a submodule points, and how it is configured
## Two files, two audiences
- **`.gitmodules`** — version-controlled, shared with collaborators. Defines each submodule's
logical name, path, and canonical URL.
- **`.git/config`** — local only, populated by `git submodule init`. Local URL overrides live here
and never propagate to another clone.
The submodule's own `.git` directory lives at `.git/modules/<name>/` in the superproject and is
linked to the submodule's working tree by a `.git` pointer file.
## `.gitmodules` keys
| Key | Purpose |
|---|---|
| `submodule.<name>.path` | Working tree path |
| `submodule.<name>.url` | Remote URL |
| `submodule.<name>.branch` | Branch used by `update --remote` |
| `submodule.<name>.update` | Default update procedure |
| `submodule.<name>.shallow` | Recommend a shallow clone |
## `.git/config` keys
| Key | Purpose |
|---|---|
| `submodule.<name>.url` | Local URL override |
| `submodule.<name>.update` | Local procedure override |
| `submodule.fetchJobs` | Default parallelism for `update --jobs` |
| `submodule.recurse` | Auto-recurse submodule updates on `pull`/`push`/etc. |
## Rebind a URL or branch
```bash
git submodule sync --recursive # push .gitmodules URLs into .git/config
git submodule set-url <path> <url> # change the canonical URL
git submodule set-branch -b <branch> <path> # set the branch used by update --remote
```
Run `sync` after an upstream rename: existing clones keep the stale URL in `.git/config` until
they do.
## Override a URL locally (private mirror)
```bash
git submodule init
# edit .git/config: submodule.<name>.url = <mirror-url>
git submodule update
```
Local-only, invisible to collaborators, and overwritten by the next `sync`.
## Relative URLs
A `../foo.git` entry in `.gitmodules` resolves against the superproject's default remote URL, not
against the filesystem. It is portable across hosts that mirror the same layout and broken
everywhere else.
## Custom `update` commands are security-gated
A `.gitmodules` entry of `update = !some-command` is never copied into `.git/config` by
`git submodule init`. That is deliberate: it stops a hostile clone from silently executing
arbitrary code. Setting it locally in `.git/config` is the only way to enable it.
## Relocate an embedded `.git` directory
```bash
git submodule absorbgitdirs [<path>...]
```
Moves a submodule's own `.git` directory into `.git/modules/<name>/` and leaves a `.git` pointer
file behind. Needed when a nested repository was created or copied in without going through
`git submodule add`.

21
plugins/git/skills/git-submodules/README.md
View File

@@ -1,10 +1,17 @@
# git-submodules # git-submodules
Initialize, clone, update, and manage git submodules for multi-repository projects. Add, initialize, update, pin, inspect, and remove git submodules in multi-repository projects.
## What it does ## What it does
This skill handles submodule operations within the git workflow suite. It initializes submodules, clones repositories with nested submodule dependencies, updates submodule pinning, and manages version control across multi-repo projects. The skill provides clean workflows for projects with complex dependency structures and returns structured results suitable for agent composition. This skill handles submodule operations within the git workflow suite: cloning a superproject with
its nested repositories, adding a dependency as a submodule, initializing and updating with
pinning or branch tracking, parallel and recursive traversal, rebinding URLs and tracked branches,
and the full removal sequence including the `.git/modules/` cleanup git leaves behind. It returns
structured results suitable for agent composition.
It sits alongside the other git skills rather than duplicating them: `git-worktrees` covers
multiple checkouts of a single repository, and `git-remotes` covers the superproject's own remotes.
## Usage ## Usage
@@ -12,13 +19,17 @@ This skill handles submodule operations within the git workflow suite. It initia
/git-submodules /git-submodules
``` ```
Describe your submodule task: initialize, clone, update, or manage versions. The skill will handle the operation and return structured results (operation, status, per-submodule details, conflicts, and a recovery `next_step` when applicable) suitable for agent composition. Describe the submodule task. The skill applies the shared working rules, dispatches to the
reference for that task, and returns structured results (operation, status, per-submodule details,
conflicts, and a recovery `next_step` when applicable).
## Files ## Files
| File | Purpose | | File | Purpose |
|------|---------| |------|---------|
| `SKILL.md` | Skill instructions for agents | | `SKILL.md` | Skill instructions for agents — gotchas, shared working rules, and the task dispatch table |
| `references/README.md` | Describes contents of references/ | | `references/README.md` | Describes contents of references/ |
| `references/submodules.md` | Deep-dive reference: full flag tables, workflow patterns, safe-removal sequence, `absorbgitdirs`, `foreach` variables | | `references/setup-and-update.md` | Loaded when cloning a superproject, adding a submodule, or initializing, updating, or re-pinning one — includes the full `add` and `update` flag tables and the pinning workflows |
| `references/urls-and-config.md` | Loaded when changing where a submodule points or how it is configured — `.gitmodules` vs `.git/config` anatomy, both key tables, `sync`/`set-url`/`set-branch`, local mirror overrides, relative URLs, the custom-`update` security gate, and `absorbgitdirs` |
| `references/removal.md` | Loaded when removing or deinitializing a submodule — why `deinit` is not removal, and the four-step removal sequence |
| `references/sources.md` | Research sources and provenance | | `references/sources.md` | Research sources and provenance |

95
plugins/git/skills/git-submodules/SKILL.md
View File

@@ -2,7 +2,10 @@
name: git-submodules name: git-submodules
description: > description: >
Use when managing Git submodules: add dependencies as submodules, initialize and update nested repositories, sync URLs, inspect status (including detached HEAD and divergence), and safely remove submodules. Handles multi-repo projects with pinning, parallel operations, and recursive traversal. Use for both initial setup and ongoing maintenance workflows, even if the user doesn't explicitly say "submodule". Do not use for general git operations outside of submodule management. Use when managing Git submodules — adding, updating, pinning, inspecting,
repointing, or removing a nested repository inside a superproject.
Not multiple checkouts of one repo -> `git-worktrees`.
Not the superproject's own remotes -> `git-remotes`.
metadata: metadata:
category: git category: git
@@ -10,82 +13,50 @@ metadata:
- git-scm-submodule-docs - git-scm-submodule-docs
--- ---
## Concept
A submodule is a full Git repository embedded as a subdirectory inside a parent repository (the superproject). The superproject doesn't store the submodule's files — it stores a pointer to a specific commit SHA in the submodule's own history, and the two repos keep fully independent commit histories.
Two files govern a submodule, and they serve different audiences:
- **`.gitmodules`** — version-controlled, shared with collaborators. Defines each submodule's name, path, and canonical URL.
- **`.git/config`** — local only, populated by `git submodule init`. This is where local URL overrides live (e.g. a private mirror) — they never propagate to other clones.
The submodule's own `.git` directory lives at `.git/modules/<name>/` in the superproject, linked to the submodule's working tree via a `.git` pointer file. After `git submodule update`, the working tree normally ends up in **detached HEAD state** — see Gotchas.
## Gotchas ## Gotchas
- **Detached HEAD by default.** `git submodule update` checks out a specific commit, not a branch. Work on a branch first, then update the pointer in the superproject. Commits made in detached state are invisible until pinned. - **`update` leaves the submodule in detached HEAD.** Branch inside the submodule before editing, or the work is unreachable once the pointer moves.
- **Two pushes required, in order.** Always commit and push the submodule first, then update and push the superproject's pointer. The superproject only stores a commit SHA — if that SHA isn't reachable on the submodule's remote yet, `git submodule update` fails for anyone who pulls the superproject before the submodule push lands. - **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 not default.** Most commands operate one level deep. Pass `--recursive` explicitly for nested submodules. - **`--recursive` is never the default.** Subcommands stop one level deep, so nested submodules go stale silently.
- **`.git/modules/` persists after `git rm`.** Manual cleanup is needed: `rm -rf .git/modules/<name>/`. - **`git rm` leaves `.git/modules/<name>/` behind.** Nothing cleans it up, and it blocks re-adding a submodule there.
- **Detached HEAD detection.** Status prefix `+` means the checked-out commit differs from the superproject's recorded commit — normal after `update --remote`, but should be re-pinned before committing.
- **Relative URLs resolve against the remote, not the filesystem.** A `../foo.git` entry in `.gitmodules` is relative to the superproject's default remote URL.
- **Custom `update` commands are security-gated.** A `.gitmodules` entry of `update = !some-command` is never copied to `.git/config` by `git submodule init` — this stops a clone from silently executing arbitrary code.
## Conventions ## Working rules
- **Use `rtk git` for parent-repo operations.** Drop into the submodule directory only for submodule-specific git commands (committing/pushing inside the submodule itself) — mixing the two from the wrong working directory targets the wrong repo's history. Run `rtk git` from the superproject root. Enter the submodule directory only for commits and pushes
- **Check for a dirty submodule before committing the parent pointer.** After adding or updating a submodule, run `git status` in both the parent and the submodule. A `-dirty` suffix means the submodule has uncommitted local changes; committing the parent pointer now would pin a state no one else can reproduce, since those changes exist only in the local working tree. 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.
## Operations 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.
- **Clone a repo that has submodules**: `rtk git clone --recurse-submodules <url>` (one step, Git 2.13+) or `rtk git clone <url>` followed by `rtk git submodule update --init --recursive`. To run one command across every submodule: `rtk git submodule foreach --recursive '<cmd>'`. Inside
- **Add a submodule**: `rtk git submodule add <url> <path>` (`-b <branch>` to track a branch instead of a pinned commit, `--depth 1` for a shallow clone, `-f` to force past a gitignored path or name conflict, `--name <name>` when the logical name should differ from the path). Stages a `.gitmodules` entry and a gitlink — a commit is still required. `<cmd>`, Git sets `$name`, `$sm_path`, `$displaypath`, `$sha1` and `$toplevel`; append `|| :` to
- **Initialize**: `rtk git submodule init [<path>...]` copies submodule URLs from `.gitmodules` to `.git/config`. This is the point at which local URL overrides can be edited before fetching. Does not clone — use `update` (or `update --init` to run both in one step). continue past a failure instead of aborting the traversal.
- **Update (clone + checkout)**: `rtk git submodule update --init --recursive` is the common case — checks out the recorded commit in detached HEAD. Add `--remote --merge` (or `--remote --rebase`) to track the branch tip instead, `--jobs <n>` for parallel clones, `-f` to discard local changes. Full flag table: `references/submodules.md`.
- **Inspect status**: `rtk git submodule status --recursive` (add `--cached` to show SHAs in the superproject index instead of the working tree). Status prefixes: `-` not initialized, `+` diverged from the superproject's recorded commit, `U` merge conflict.
- **Sync and rebind URLs**: `rtk git submodule sync --recursive` after an upstream URL rename propagates `.gitmodules` changes into `.git/config`. `rtk git submodule set-url <path> <url>` changes a URL directly; `rtk git submodule set-branch -b <branch> <path>` sets the tracking branch used by `update --remote`.
- **Override a submodule URL locally (private mirror)**: local-only, doesn't propagate to collaborators, and gets overwritten by the next `sync`. Full steps: `references/submodules.md`.
- **Run a command across all submodules**: `rtk git submodule foreach --recursive '<command>'`. Shell variables available inside `<command>` (`$name`, `$sm_path`, `$displaypath`, `$sha1`, `$toplevel`): `references/submodules.md`.
- **Deinit (unregister without removing)**: `rtk git submodule deinit <path>` (`--all` for every submodule, `-f` if local modifications are present) clears the `.git/config` section and empties the working tree. **`deinit` is not removal** — the `.gitmodules` entry and the gitlink in the superproject's index are untouched.
- **Safe removal** (destructive; confirm before executing) — full three-step sequence including the manual `.git/modules/` cleanup: `references/submodules.md`.
- **Move an embedded `.git` into `.git/modules/`**: `rtk git submodule absorbgitdirs [<path>...]` — needed when a submodule was created or copied without going through `git submodule add`. Details: `references/submodules.md`.
## Configuration ## Dispatch
`.gitmodules` (version-controlled, shared with collaborators): Read only the row that matches the request.
| Key | Purpose | | Task | Reference |
|---|---| |---|---|
| `submodule.<name>.path` | Working tree path | | Clone a superproject with submodules, or add, initialize, update or re-pin one | `references/setup-and-update.md` |
| `submodule.<name>.url` | Remote URL | | 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` |
| `submodule.<name>.branch` | Branch used by `update --remote` | | Remove a submodule, or `deinit` one without removing it | `references/removal.md` |
| `submodule.<name>.update` | Default update procedure |
| `submodule.<name>.shallow` | Recommend shallow clone |
`.git/config` (local only, populated by `init`): Removal and `deinit` are destructive: state what will be deleted and get confirmation before
executing.
| Key | Purpose | ## Output format
|---|---|
| `submodule.<name>.url` | Local URL override |
| `submodule.<name>.update` | Local procedure override |
| `submodule.fetchJobs` | Default parallelism for `update --jobs` |
| `submodule.recurse` | Auto-recurse submodule updates on `pull`/`push`/etc. |
```bash
rtk git config submodule.recurse true # keep submodules pinned automatically after every pull
``` ```
operation: <clone|add|init|update|status|sync|set-url|set-branch|absorbgitdirs|deinit|remove>
## Agent output format
Return results as structured data:
```
operation: <clone|add|init|update|sync|set-url|set-branch|status|summary|absorbgitdirs|remove>
status: <success|error|partial> status: <success|error|partial>
message: <human-readable summary> message: <one line; include git's own output on error>
details: details:
- <submodule-path>: <state> - <submodule-path>: <state>
conflicts: [<submodule-path>, ...] # if any conflicts: [<submodule-path>, ...]
next_step: <recovery action if applicable> next_step: <recovery action, when status is error or partial>
``` ```
For errors, include the git command output and recommend recovery (e.g., `git submodule deinit`, force-update, or URL override).

22
plugins/git/skills/git-submodules/references/README.md
View File

@@ -6,10 +6,26 @@ metadata:
# References # References
## submodules.md One file per task branch in SKILL.md's dispatch table. Load only the one that matches the request.
Deep-dive reference: full `update` flag table, workflow patterns (clone, add, keep-pinned, update-to-latest, override URL), the complete safe-removal sequence, `absorbgitdirs`, and `foreach` shell variables. Load when SKILL.md's condensed Operations list isn't enough detail. ## setup-and-update.md
Cloning a superproject that has submodules, adding a dependency as a submodule, initializing
without cloning, and updating or re-pinning. Carries the `add` and `update` flag tables and the
keep-pinned and move-the-pin-forward workflows.
## urls-and-config.md
Where a submodule points and how it is configured: the `.gitmodules` vs `.git/config` split, both
key tables, `sync` / `set-url` / `set-branch`, local mirror overrides, relative URL resolution, the
security gate on custom `update` commands, and `absorbgitdirs`.
## removal.md
Removing a submodule, and why `deinit` alone does not remove one. Carries the full four-step
removal sequence including the manual `.git/modules/<name>/` cleanup.
## sources.md ## sources.md
Research sources that informed this skill — provenance chain for git-scm-submodule-docs reference material. Research sources that informed this skill — provenance chain for git-scm-submodule-docs reference
material.

32
plugins/git/skills/git-submodules/references/removal.md Normal file
View File

@@ -0,0 +1,32 @@
---
topic: submodules
source_keys:
- git-scm-submodule-docs
---
# Removing and deinitializing a submodule
Both operations are destructive. Confirm with the user before executing either.
## `deinit` is not removal
```bash
git submodule deinit <path> # --all for every submodule, -f if locally modified
```
`deinit` clears the submodule's section from `.git/config` and empties its working tree. The
`.gitmodules` entry and the gitlink in the superproject's index are untouched, so the submodule is
still registered and a later `update --init` brings it straight back. Use it to reclaim disk space
or to reset a broken checkout, not to delete a dependency.
## Full removal, in order
```bash
git submodule deinit -f <path> # unregister from .git/config
git rm <path> # drop the .gitmodules entry and the gitlink from the index
rm -rf .git/modules/<name>/ # stale git dir: not tracked, not cleaned up by git
git commit -m "chore: remove <name> submodule"
```
The third step is the one that gets skipped. `.git/modules/<name>/` survives `git rm`, and while it
is present Git refuses to add a submodule at the same path again.

74
plugins/git/skills/git-submodules/references/setup-and-update.md Normal file
View File

@@ -0,0 +1,74 @@
---
topic: submodules
source_keys:
- git-scm-submodule-docs
---
# Adding, initializing, updating and pinning submodules
## Clone a superproject that already has submodules
```bash
git clone --recurse-submodules <url> # Git 2.13+, one step
# or, against an existing clone
git submodule update --init --recursive
```
## Add a dependency as a submodule
```bash
git submodule add <url> <path>
git commit -m "chore: add <name> as submodule"
```
`add` stages a `.gitmodules` entry and a gitlink — the commit is still required. Flags:
| Flag | Meaning |
|---|---|
| `-b <branch>` | Track a branch (`submodule.<name>.branch`) instead of only a pinned commit |
| `--depth <n>` | Shallow clone |
| `-f` | Force past a gitignored path or a name conflict |
| `--name <name>` | Logical name differing from the path |
## Initialize without cloning
`git submodule init [<path>...]` copies submodule URLs from `.gitmodules` into `.git/config` and
does nothing else. This is the point at which a local URL override can be edited before any fetch
happens. If a local mirror override is wanted, read `references/urls-and-config.md` before running
`update`. Use `update --init` to run both steps at once.
## Update
`git submodule update --init --recursive` is the common case: it clones what is missing and checks
out the commit the superproject recorded, in detached HEAD.
| Flag | Meaning |
|---|---|
| `--init` | Run `init` first, avoiding a separate step |
| `--remote` | Use the submodule's remote branch tip instead of the superproject's recorded commit |
| `--checkout` | Detached HEAD at the recorded commit (default) |
| `--rebase` | Rebase the current branch onto the recorded commit |
| `--merge` | Merge the recorded commit into the current branch |
| `--recursive` | Operate on nested submodules |
| `--jobs <n>` | Parallel clone (defaults to `submodule.fetchJobs`) |
| `-N` / `--no-fetch` | Skip the remote fetch |
| `-f` | Discard local changes in the submodule working tree |
| `--depth <n>` | Shallow clone |
| `--filter <spec>` | Partial clone filter |
## Keep submodules pinned to the recorded commit
```bash
git submodule update --recursive # after every git pull
git config submodule.recurse true # or do it automatically on pull/push/checkout
```
## Move the pin forward to the tracked branch tip
```bash
git submodule update --remote --merge --recursive
git commit -am "chore: update submodules to latest"
```
`--remote` requires `submodule.<name>.branch`; without it Git falls back to the remote's default
branch. Commit the superproject afterwards or the new pin is lost on the next `update`.

4
plugins/git/skills/git-submodules/references/sources.md
View File

@@ -14,7 +14,9 @@ source_keys:
**Contributing files:** **Contributing files:**
- SKILL.md (all sections) - SKILL.md (all sections)
- references/submodules.md (all sections) - references/setup-and-update.md (all sections)
- references/urls-and-config.md (all sections)
- references/removal.md (all sections)
--- ---

93
plugins/git/skills/git-submodules/references/submodules.md
View File

@@ -1,93 +0,0 @@
---
topic: submodules
source_keys:
- git-scm-submodule-docs
---
# Submodules — Deep Reference
## Update flag reference
| Flag | Meaning |
|---|---|
| `--init` | Run init first (avoids a separate step) |
| `--remote` | Use the submodule's remote branch tip instead of the superproject's recorded commit |
| `--checkout` | Detached HEAD at recorded commit (default) |
| `--rebase` | Rebase current branch onto recorded commit |
| `--merge` | Merge recorded commit into current branch |
| `--recursive` | Operate on nested submodules |
| `--jobs <n>` | Parallel clone (defaults to `submodule.fetchJobs`) |
| `-N` / `--no-fetch` | Skip remote fetch |
| `--depth <n>` | Shallow clone |
| `--filter <spec>` | Partial clone filter |
## Workflow patterns
### Clone a repo with submodules
```bash
git clone --recurse-submodules <url> # Git 2.13+, one step
# or
git clone <url>
git submodule update --init --recursive
```
### Add a dependency as a submodule
```bash
git submodule add https://github.com/org/lib.git libs/lib
git commit -m "chore: add lib as submodule"
```
### Keep submodules pinned to the superproject's recorded commit
```bash
git submodule update --recursive # after every git pull
git config submodule.recurse true # do this automatically on pull
```
### Update submodules to the latest commit on their tracked branch
```bash
git submodule update --remote --merge --recursive
git commit -am "chore: update submodules to latest"
```
### Override a submodule URL locally (private mirror)
```bash
git submodule init
# edit .git/config: submodule.<name>.url = <mirror-url>
git submodule update
```
Local-only override (`.git/config`, not `.gitmodules`) — doesn't propagate to collaborators. Re-running `sync` overwrites it with the `.gitmodules` URL.
## Removal, in full
`deinit` alone does not remove a submodule — it only clears `.git/config` and empties the working tree. To fully remove:
```bash
git submodule deinit -f <path> # unregister from .git/config
git rm <path> # remove .gitmodules entry + gitlink from index
rm -rf .git/modules/<name>/ # stale git dir; not tracked by git, not auto-cleaned
git commit -m "chore: remove <name> submodule"
```
`.git/modules/<name>/` persisting after `git rm` will block re-adding the same path until manually deleted.
## Relocate an embedded `.git` directory
```bash
git submodule absorbgitdirs [<path>...]
```
Moves a submodule's own `.git` directory into the superproject's `.git/modules/<name>/`, linking it back with a `.git` pointer file. Needed when a submodule was created or copied without going through `git submodule add` (e.g. converting a plain nested repo into a proper submodule).
## `foreach` shell variables
Available inside the `<command>` argument to `git submodule foreach`:
| Variable | Meaning |
|---|---|
| `$name` | Logical submodule name |
| `$sm_path` | Path relative to superproject root |
| `$displaypath` | Path relative to current working directory |
| `$sha1` | Recorded commit SHA |
| `$toplevel` | Superproject's root path |
```bash
git submodule foreach --recursive '<command>'
git submodule foreach 'git pull origin main || :' # || : continues past failures
```

79
plugins/git/skills/git-submodules/references/urls-and-config.md Normal file
View File

@@ -0,0 +1,79 @@
---
topic: submodules
source_keys:
- git-scm-submodule-docs
---
# Where a submodule points, and how it is configured
## Two files, two audiences
- **`.gitmodules`** — version-controlled, shared with collaborators. Defines each submodule's
logical name, path, and canonical URL.
- **`.git/config`** — local only, populated by `git submodule init`. Local URL overrides live here
and never propagate to another clone.
The submodule's own `.git` directory lives at `.git/modules/<name>/` in the superproject and is
linked to the submodule's working tree by a `.git` pointer file.
## `.gitmodules` keys
| Key | Purpose |
|---|---|
| `submodule.<name>.path` | Working tree path |
| `submodule.<name>.url` | Remote URL |
| `submodule.<name>.branch` | Branch used by `update --remote` |
| `submodule.<name>.update` | Default update procedure |
| `submodule.<name>.shallow` | Recommend a shallow clone |
## `.git/config` keys
| Key | Purpose |
|---|---|
| `submodule.<name>.url` | Local URL override |
| `submodule.<name>.update` | Local procedure override |
| `submodule.fetchJobs` | Default parallelism for `update --jobs` |
| `submodule.recurse` | Auto-recurse submodule updates on `pull`/`push`/etc. |
## Rebind a URL or branch
```bash
git submodule sync --recursive # push .gitmodules URLs into .git/config
git submodule set-url <path> <url> # change the canonical URL
git submodule set-branch -b <branch> <path> # set the branch used by update --remote
```
Run `sync` after an upstream rename: existing clones keep the stale URL in `.git/config` until
they do.
## Override a URL locally (private mirror)
```bash
git submodule init
# edit .git/config: submodule.<name>.url = <mirror-url>
git submodule update
```
Local-only, invisible to collaborators, and overwritten by the next `sync`.
## Relative URLs
A `../foo.git` entry in `.gitmodules` resolves against the superproject's default remote URL, not
against the filesystem. It is portable across hosts that mirror the same layout and broken
everywhere else.
## Custom `update` commands are security-gated
A `.gitmodules` entry of `update = !some-command` is never copied into `.git/config` by
`git submodule init`. That is deliberate: it stops a hostile clone from silently executing
arbitrary code. Setting it locally in `.git/config` is the only way to enable it.
## Relocate an embedded `.git` directory
```bash
git submodule absorbgitdirs [<path>...]
```
Moves a submodule's own `.git` directory into `.git/modules/<name>/` and leaves a `.git` pointer
file behind. Needed when a nested repository was created or copied in without going through
`git submodule add`.