install-all-submodules

Recursively detect, configure, and pull every Git submodule in your repo — with an interactive remote-name prompt at each level.

Why

When you clone a repo that has Git submodules (and those submodules have their own submodules), wiring up remotes and pulling each one by hand is tedious and error-prone. install-all-submodules walks the entire tree for you: it reads every .gitmodules file, asks you which remote name to use for each submodule, then runs the right git commands automatically.

Install

# Global install (recommended — lets you run it anywhere)
npm install -g install-all-submodules

# Or use it without installing via npx
npx install-all-submodules

Usage

cd /your/repo          # must contain a .gitmodules file
install-all-submodules

That's it. The CLI will:

1. Detect .gitmodules in the current directory
2. For each submodule ask:
   • Which remote name to use: origin, upstream, or a custom name
   • Whether to override the auto-detected remote URL
   • Which branch name to target (default: main)
3. Then automatically run:

   git remote add <name> <url>   # or set-url if remote already exists
   git branch -m <branch>
   git pull <name> <branch>

4. Recurse — if that submodule folder also contains a .gitmodules, the whole process repeats inside it, going as deep as needed.

Example Session

╔══════════════════════════════════════════════╗
║      install-all-submodules  v1.0.0          ║
║  Recursive Git submodule setup — automated   ║
╚══════════════════════════════════════════════╝

Found 2 submodule(s) in root

[website] Configuring submodule → website
  Detected URL: https://github.com/org/website.git
  ? Choose the remote name for this submodule:
    ❯ origin    (standard fork/clone remote)
      upstream  (original source remote)
      custom    (I want to type my own)
  ? Override the remote URL? No
  ? Target branch name (will run git branch -m <name>): main

    Setting up website → /your/repo/website
    $ git remote add origin https://github.com/org/website.git
    $ git branch -m main
    $ git pull origin main
    ✔ website configured

  ↳ Nested .gitmodules detected — diving deeper…

  [ui-kit] Configuring submodule → website/ui-kit
    ...

✔  All submodules have been set up successfully!

What Each Step Does

| Step | Command | Notes | |------|---------|-------| | Add remote | git remote add <name> <url> | If the remote already exists, runs git remote set-url instead | | Rename branch | git branch -m <branch> | Renames the current local branch to your chosen name | | Pull | git pull <name> <branch> | Fetches and merges from the configured remote | | Recurse | (internal) | Checks each submodule folder for its own .gitmodules |

Requirements

• Node.js ≥ 14
• Git installed and available on PATH
• Submodule directories must already exist on disk
  (run git submodule update --init first if they don't)

Programmatic API

const { processSubmodules, parseGitmodules } = require('install-all-submodules');

// Parse only — returns array of { name, path, url, branch }
const entries = parseGitmodules('/path/to/repo');

// Full interactive setup (async — uses readline prompts)
await processSubmodules('/path/to/repo', 0);

License

MIT