Submodules¶
oops-sub-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 |
|---|---|---|---|
--pull-request |
boolean | Indicates that the submodule is a pull request (affects naming) | False |
--dry-run |
boolean | Show planned actions only | False |
--no-commit |
boolean | Do not commit automatically at the end | False |
--addons |
text | List of addons for which to create symlinks (default: '') | None |
--auto-symlinks |
boolean | Auto-create symlinks at repo root for each addon folder detected in the submodule | False |
--name |
text | Optional submodule name (defaults to ' |
None |
--base-dir |
text | Base dir for submodules (default: .third-party) | <function <lambda> at 0x7f295537ad40> |
-b, --branch |
text | Branch to track for the submodule (e.g., 18.0) | None |
--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-sub-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-sub-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-sub-fix¶
Fix common submodule issues detected by oops-sub-check.
Normalises submodule URLs to the configured scheme (e.g. SSH) and replaces deprecated repository paths as defined in the project config.
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--no-commit |
boolean | Do not commit automatically at the end | False |
--help |
boolean | Show this message and exit. | False |
Examples:
Fix issues and commit the result:
Fix without committing:
oops-sub-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:
oops-sub-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-sub-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-sub-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-sub-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 0x7f295537b880> |
-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-sub-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-sub-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: