Defame1297
20e5627fd7
Three statements were false against the git in use (2.39.5), each verified by
running it.
`git rebase --autosquash HEAD~N` without `-i` is a silent no-op: git prints
"Successfully rebased", the `fixup!` commit survives with the same SHA, and
rewrite-history.md presented that as the preferred flow with `-i` as an optional
review step. The agent reports the squash as done and the `fixup!` subject then
trips this repo's own commit-msg gate. `-i` is now the command, not the alternative.
"Fetch never modifies a local branch, so it is always safe to run" — new text on
this branch — is false: `git fetch origin main:probe` fast-forwarded the local
branch, and a `+` prefix force-updates it, losing commits. The claim is scoped to
the no-refspec form.
`git worktree add --orphan` does not exist before Git 2.42; on 2.39.5 it is
`error: unknown option 'orphan'`, exit 129. The same file gives a version floor for
`--recurse-submodules` three sections earlier. Floor added, with a fallback that
was tested before being documented.
git-workflow claimed "every request resolves to exactly one of these six" while
rebase, reset and stash were owned by no skill — `git reset` appeared nowhere in
the plugin, old tree or new — so "undo my last commit" routed nowhere. The claim is
gone, the router gains rows for all three, and the procedures now exist: plain
rebase with `--onto` and conflict handling, a reset mode table gated on `--hard`,
and stash save/pop/list/drop. `--hard` gets an always-loaded Gotcha, matching the
register the force-push refusal already sets.
Cherry-pick had three claimants pointing at git-history while git-commits owned the
flow, and the two copies were not equivalent — git-history's lacked the destination
check, the rtk prefix and `--abort`. Resolved to git-commits per #112; the weaker
duplicate is replaced by a hand-off.
git-commits' metadata.version was deleted rather than bumped in 14af50b, leaving two
house-contract documents citing a worked v0.1.2 to v0.1.3 transition against a file
declaring no version. Restored to 0.1.3.
Also: the divergent-pull explanation stated a `--ff-only` default that does not
exist (it is a hard error); `--remote` "requires" a configured branch where it uses
one; `git push origin --delete` moved to git-remotes, which owns the remote-side
gates; seven retired `git:<name>` source slugs; git-orchestrate quoted a
git-workflow sentence that no longer exists; git-submodules regains the indirect
trigger that made "add a dependency repo" routable; and commit atomicity is a common
gate rather than reachable only from the create flow.
Refs: #112, #113
97 lines
3.6 KiB
Markdown
97 lines
3.6 KiB
Markdown
---
|
|
topic: submodules
|
|
source_keys:
|
|
- git-scm-submodule-docs
|
|
---
|
|
|
|
# Adding, initializing, updating and pinning submodules
|
|
|
|
## Clone a superproject that already has submodules
|
|
|
|
```bash
|
|
rtk git clone --recurse-submodules <url> # Git 2.13+, one step
|
|
# or, against an existing clone
|
|
rtk git submodule update --init --recursive
|
|
```
|
|
|
|
## Add a dependency as a submodule
|
|
|
|
```bash
|
|
rtk git submodule add <url> <path>
|
|
rtk 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
|
|
|
|
`rtk 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
|
|
|
|
`rtk 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
|
|
rtk git submodule update --recursive # after every rtk git pull
|
|
rtk git config submodule.recurse true # or do it automatically on pull/push/checkout
|
|
```
|
|
|
|
## Move the pin forward to the tracked branch tip
|
|
|
|
```bash
|
|
rtk git submodule update --remote --merge --recursive
|
|
rtk git commit -am "chore: update submodules to latest"
|
|
```
|
|
|
|
`--remote` uses `submodule.<name>.branch` when it is set; 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`.
|
|
|
|
## Run one command across every submodule
|
|
|
|
```bash
|
|
rtk git submodule foreach --recursive '<command>'
|
|
rtk git submodule foreach 'git pull origin main || :' # || : continues past a failure
|
|
```
|
|
|
|
`<command>` runs inside each submodule's own working tree, so the git calls in it are the
|
|
submodule's own — that is the one place a bare `git` is correct. Append `|| :` to keep the
|
|
traversal going instead of aborting at the first failure.
|
|
|
|
Git exports five shell variables into `<command>`. `$sm_path` and `$displaypath` name the same
|
|
directory from different vantage points and are not interchangeable:
|
|
|
|
| Variable | Meaning |
|
|
|---|---|
|
|
| `$name` | Logical submodule name (the `.gitmodules` section name, which need not match the path) |
|
|
| `$sm_path` | Path relative to the superproject root |
|
|
| `$displaypath` | Path relative to the current working directory |
|
|
| `$sha1` | Commit SHA the superproject has recorded for this submodule |
|
|
| `$toplevel` | Absolute path of the superproject's root |
|