skills.rest
NAMEWTA
NAMEWTACOMMUNITY
Explore all skills by this author →
GitHub

submodule-manager

Automates adding, syncing, and indexing git submodules across categorized mono-repo directories.

2|Updated Jul 6, 2026
Search Tags:#automation#repository management#github api#mono-repo#git submodule#branch tracking#readme generator
One-click install
npx skills add https://github.com/NAMEWTA/learning-open-code --skill submodule-manager-namewta
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: submodule-manager
Source: https://github.com/NAMEWTA/learning-open-code/tree/main/.agents/skills/submodule-manager
Command: npx skills add https://github.com/NAMEWTA/learning-open-code --skill submodule-manager-namewta

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes scripts (resource) components.

What problem does it solve? Managing dozens of git submodules in a mono-repo is tedious: you must pick the right category directory, record tracking branches in .gitmodules, keep every submodule synced to its branch, and manually maintain a README index. This Skill automates all four workflows with Python scripts. ## Core Features & Use Cases - Add Submodules: Clone a repo into one of 10 category directories with auto-detected default branch, record the branch in .gitmodules, and refresh the README index. - Sync Submodules: Fetch, checkout, and pull every submodule to its configured branch with per-submodule success/failure reporting. - README Index Generation: Regenerate the root README.md with categorized tables including descriptions and star counts fetched from GitHub/Gitee APIs, preserving existing descriptions when lookups fail. - Initialization SOP: Guides new clones through git submodule update --init --recursive with troubleshooting for empty directories and missing gitlinks. - Use Case: After cloning a 62-project learning repository, run the sync script to pull every submodule to its latest tracked branch and regenerate the README index in one step. ## Quick Start Ask the agent to add https://github.com/owner/repo.git to the open-ai-agent category and sync all submodules to their latest branches.

Frequently Asked Questions about submodule-manager

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I add a git submodule with a specific tracking branch?▼

Run add_submodule.py with --url, --category, and --branch arguments. If the branch is omitted, the script auto-detects the default branch via git ls-remote and records it in .gitmodules so future syncs work.

How do I sync all git submodules to their latest remote branches?▼

Run sync_submodules.py from the repo root. It parses .gitmodules, then for each submodule runs git fetch, git checkout of the configured branch, and git pull, reporting per-submodule success or failure.

Why is git submodule status empty after cloning a repository?▼

Submodules are not initialized by default after git clone. Run git submodule update --init --recursive to check out the locked commits, or add --remote to pull the latest commits from the tracked branches.

Does the README index generation require a GitHub token?▼

No, a token is optional. The script reuses a GH_TOKEN, GITHUB_TOKEN, or an authenticated gh CLI session if available; without one it still calls the public API and preserves existing descriptions when lookups fail.

What are the limitations of branch-based submodule syncing?▼

Syncing requires every submodule to have a branch entry in .gitmodules; submodules without one are skipped. It also checks out branch heads rather than locked gitlink commits, so builds are not reproducible.

Related Skills

Explore More Software Engineering Skills→
VLSIDAVLSIDA
36

find-designs

Search GitHub for synthesizable hardware designs missing from HighTide2.

Official
Advanced
goffitygoffity

distill

Extracts patterns and insights from linked notes to create reusable knowledge base entries.

Community
Intermediate
benjaminshafiibenjaminshafii
10

sync-modules

Synchronize control-center master with upstream changes and update submodule pointers safely.

Community
Intermediate
rahulrajaramrahulrajaram

git-status-report

Report Git repository and submodule synchronization status against remote tracking branches.

Community
Intermediate