# git-submodules

Add, initialize, update, pin, inspect, and remove git submodules in multi-repository projects.

## What it does

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

```
/git-submodules
```

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

| File | Purpose |
|------|---------|
| `SKILL.md` | Skill instructions for agents — gotchas, shared working rules, and the task dispatch table |
| `references/README.md` | Describes contents of references/ |
| `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 |