holocron/plugins/git/skills/git-submodules/references/setup-and-update.md

topic, source_keys

topic	source_keys
submodules	git-scm-submodule-docs

Adding, initializing, updating and pinning submodules

Clone a superproject that already has submodules

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

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

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

rtk git submodule update --remote --merge --recursive
rtk 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.

Run one command across every submodule

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