Defame1297
ae791781c2
git-workflow calls itself a router but named two of the six domains it routes to; the other four appeared nowhere in the file. All six are now named, with a routing table in the always-loaded body. git-submodules lost the foreach shell-variable semantics -- only the bare names survived, though $sm_path and $displaypath differ solely by which directory you are in. The table is back. Its relocated commands had also dropped the rtk git prefix its own SKILL.md mandates; 24 of them are re-prefixed. The wider rtk inconsistency across the plugin stays with #113. Also restores git-commits' body and footers output fields, git-branches' tag/ branch detection commands, git-worktrees' git config --worktree, pc-run's ambiguity fallback, git-remotes' git-history boundary, and git-history's pickaxe triggers. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01EJJrm5YmacbwMdzZpXcoti
80 lines
2.6 KiB
Markdown
80 lines
2.6 KiB
Markdown
---
|
|
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 `rtk 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
|
|
rtk git submodule sync --recursive # push .gitmodules URLs into .git/config
|
|
rtk git submodule set-url <path> <url> # change the canonical URL
|
|
rtk 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
|
|
rtk git submodule init
|
|
# edit .git/config: submodule.<name>.url = <mirror-url>
|
|
rtk 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
|
|
`rtk 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
|
|
rtk 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
|
|
`rtk git submodule add`.
|