Files

Defame1297 0239b00944 feat(git-plugin): add complete git workflow automation suite

## Why
The git plugin only covered a partial slice of common git workflows.
This adds the remaining skill set (branches, commits, history, remotes,
submodules, workflow, worktrees) plus a git-orchestrate agent so the
plugin can handle end-to-end git automation instead of a handful of
commands.

## Implementation Notes
Each new skill was validated against its research docs and org
conventions after initial authoring, which surfaced hallucinated
version pins, factual errors, and completeness gaps that were
corrected in the same pass rather than left for follow-up.

## Impact
Bumps the git plugin to 1.3.0.

Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com>

2026-07-04 18:46:02 +00:00

3.1 KiB

Raw Blame History

topic, source_keys

topic

source_keys

submodules

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

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

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

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

git submodule update --remote --merge --recursive
git commit -am "chore: update submodules to latest"

Override a submodule URL locally (private mirror)

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:

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

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

git submodule foreach --recursive '<command>'
git submodule foreach 'git pull origin main || :'   # || : continues past failures

3.1 KiB Raw Blame History