Submodules¶
Add, audit, fix, and maintain git submodules.
Modules:
| Name | Description |
|---|---|
add |
Add a git submodule and optionally create symlinks for its addons. |
branch |
Detect and fix submodules missing a branch in .gitmodules. |
check |
Check all submodules for common issues. |
clean |
Remove stale submodule base directories and re-initialise submodules. |
fix |
Fix common submodule issues detected by oops-sub-check. |
init |
Initialize and update all submodules recursively. |
prune |
Remove submodules that are not referenced by any symlink. |
remove |
Remove one or more submodules and their associated symlinks. |
rename |
Rename submodules to match the |
replace |
Replace one or more submodules with a new repository. |
rewrite |
Move submodule paths under a canonical base directory and update symlinks. |
show |
Display a table of all submodules with their details. |
update |
Fetch and pull submodules to their latest upstream commit. |
oops submodules add¶
Add a git submodule and optionally create symlinks for its addons.
Clones the repository as a submodule under the base directory (default: .third-party), records the tracked branch, and optionally creates symlinks at the repo root for every addon found or for a specific list.
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
-y, --yes |
boolean | Skip confirmation prompt | False |
--pull-request |
boolean | Indicates that the submodule is a pull request (affects naming and path) | False |
--dry-run |
boolean | Show planned actions only, make no changes | False |
--no-commit |
boolean | Stage changes but do not commit automatically | False |
--addons |
text | Comma-separated list of addon names for which to create symlinks | None |
--auto-symlinks |
boolean | Auto-create symlinks at repo root for each addon folder detected in the submodule | False |
--base-dir |
text | Base dir for submodules (default: .third-party) | <function <lambda> at 0x7f174aaf28e0> |
--help |
boolean | Show this message and exit. | False |
Examples:
Add a submodule and create symlinks for all its addons automatically:
Add a submodule and symlink only specific addons:
Preview planned actions without touching the repository:
oops submodules branch¶
Detect and fix submodules missing a branch in .gitmodules.
Iterates over all submodules, finds those without a branch entry, and either prompts interactively or applies the default branch provided via --branch.
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--branch |
text | Branch name to set for submodules missing branch in .gitmodules | None |
--skip-pr |
boolean | Do not ask for submodules that look like pull request paths | False |
--no-commit |
boolean | Do not commit automatically at the end | False |
--help |
boolean | Show this message and exit. | False |
Examples:
Set a default branch for all submodules missing one:
Skip pull-request submodules during the fix:
oops submodules check¶
Check all submodules for common issues.
Verifies path conventions, URL scheme, branch presence, deprecated repository references, unused submodules (no symlink points to them), broken symlinks, and pull-request submodules not under the configured PR directory. Exits non-zero if any issue is found.
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--help |
boolean | Show this message and exit. | False |
Examples:
Run all configured checks and report issues:
oops submodules clean¶
Remove stale submodule base directories and re-initialise submodules.
Deletes the old and new submodule base directories (third-party and .third-party) if they exist on disk, then runs git submodule update --init to restore them from .gitmodules. Use --reset to hard-reset the repo first.
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--reset |
boolean | Do a hard reset before | False |
--help |
boolean | Show this message and exit. | False |
Examples:
Remove stale directories and re-init submodules:
Hard-reset the repo before cleaning:
oops submodules fix¶
Fix common submodule issues detected by oops-sub-check.
Normalises submodule URLs to the configured scheme (e.g. SSH).
Deprecated repository replacements are reported but not applied
automatically — use oops-sub-replace for those.
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--dry-run |
boolean | Show planned changes only. | False |
--no-commit |
boolean | Do not commit automatically at the end. | False |
--help |
boolean | Show this message and exit. | False |
Examples:
Preview what would be fixed without applying changes:
Fix issues and commit the result:
Fix without committing:
oops submodules init¶
Initialize and update all submodules recursively.
Runs git submodule update --init --recursive --jobs=N, initializing
any unregistered submodules and checking out the recorded commits in
parallel across N worker jobs.
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--jobs, -j |
integer range (1 and above) |
Number of parallel jobs. | 4 |
--help |
boolean | Show this message and exit. | False |
Examples:
Initialize all submodules with the default 4 parallel jobs:
Speed up initialization on a large project:
oops submodules prune¶
Remove submodules that are not referenced by any symlink.
Iterates over all submodules, checks whether any symlink in the repository points to the submodule path, and removes those that are unused. Specific submodules can be targeted by passing their names as arguments.
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--no-commit |
boolean | Do not commit automatically at the end | False |
--dry-run |
boolean | Show planned changes only | False |
--help |
boolean | Show this message and exit. | False |
Examples:
Preview which submodules would be removed:
Remove unused submodules and commit:
oops submodules rename¶
Rename submodules to match the
Computes the canonical name from the submodule URL and renames it if it differs. Prompts for confirmation on each change unless --no-prompt is passed. Specific submodules can be targeted by name.
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--dry-run |
boolean | Show planned changes only | False |
--no-commit |
boolean | Do not commit changes | False |
--prompt / --no-prompt |
boolean | Prompt before renaming | True |
--pull-request, --pr |
boolean | Mark submodules as pull request | False |
--help |
boolean | Show this message and exit. | False |
Examples:
Preview renames without applying them:
Rename all without interactive confirmation:
oops submodules remove¶
Remove one or more submodules and their associated symlinks.
When called without arguments, displays an indexed menu of all submodules. Enter the index numbers (comma-separated) to select which to remove. Submodule names can also be passed directly as arguments.
Associated symlinks pointing into the removed submodule paths are removed automatically. Prompts for confirmation before applying any changes.
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--dry-run |
boolean | Show planned changes only | False |
--no-commit |
boolean | Do not commit changes | False |
--force |
boolean | Skip confirmation prompt | False |
--help |
boolean | Show this message and exit. | False |
Examples:
Select submodules to remove from an interactive indexed menu:
Remove a specific submodule by name:
Preview what would be removed without making changes:
Remove without committing:
oops submodules replace¶
Replace one or more submodules with a new repository.
Removes the named submodules, adds the new repository as a submodule, and rewrites any symlinks that pointed to the old paths to point to the new one.
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--dry-run |
boolean | Show planned changes only | False |
--no-commit |
boolean | Do not commit changes | False |
--help |
boolean | Show this message and exit. | False |
Examples:
Replace a submodule with a new repository:
Preview the replacement without making changes:
oops submodules rewrite¶
Move submodule paths under a canonical base directory and update symlinks.
Computes the target path for each submodule under the base directory (default: .third-party), moves the submodule, and rewrites all symlinks that referenced the old path. Prompts for confirmation unless --force is used.
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--base-dir |
text | Base directory for rewritten paths (default: .third-party) | <function <lambda> at 0x7f174aaf3ec0> |
-f, --force |
boolean | Apply all changes without prompting | False |
--dry-run |
boolean | Show planned changes only | False |
--no-commit |
boolean | Do not commit automatically at the end | False |
--help |
boolean | Show this message and exit. | False |
Examples:
Preview path rewrites without applying them:
Rewrite all paths non-interactively:
oops submodules show¶
Display a table of all submodules with their details.
Shows name, URL, upstream branch, pull-request flag, last commit date, commit age, and SHA for each submodule. Filter to PR-only submodules with --pull-request.
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--pull-request |
boolean | Show pull request submodules only | False |
--help |
boolean | Show this message and exit. | False |
Examples:
Show all submodules with their last commit info:
Show only pull-request submodules:
oops submodules update¶
Fetch and pull submodules to their latest upstream commit.
For each submodule with a configured branch, fetches from origin, checks out the branch, and pulls the latest commits. Specific submodules can be targeted by name; PR submodules can be skipped with --skip-pr.
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--dry-run |
boolean | Show planned changes only | False |
--no-commit |
boolean | Do not commit changes | False |
--skip-pr |
boolean | Skip submodules that are pull requests | False |
--help |
boolean | Show this message and exit. | False |
Examples:
Update all submodules to their latest upstream commit:
Update a single submodule by name:
Skip pull-request submodules: