github-update-submodule 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 [Muhammad Saad Amin] @SENODROOM
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,168 @@
+# github-update-submodule
+
+> Recursively pull all Git submodules to their latest remote commit and push the updated refs up every parent repo — so **GitHub always points to the latest commit** in every submodule, no matter how deeply nested.
+
+---
+
+## The Problem
+
+Git submodules work by storing a **commit pointer** (a hash) in the parent repo. When a submodule gets new commits, the parent repo's pointer goes stale — GitHub still shows the old commit until someone manually updates and pushes it. With deeply nested submodules this becomes a nightmare to manage by hand.
+
+```
+GitHub (parent repo)  ──pins──▶  old commit ❌
+Your local submodule             latest commit ✅
+```
+
+## The Solution
+
+One command. Run it in any repo with submodules and every parent on GitHub will point to the latest commit — automatically, recursively, all the way down the tree.
+
+```bash
+github-update-submodule
+```
+
+---
+
+## Installation
+
+```bash
+npm install -g github-update-submodule
+```
+
+---
+
+## Usage
+
+Navigate to your root repo in the terminal and run:
+
+```bash
+github-update-submodule
+```
+
+That's it. The tool will:
+
+1. **Pull** — fetch every submodule (at any nesting depth) and reset it to the latest commit on its remote branch
+2. **Commit** — stage and commit the updated submodule pointers in each parent repo
+3. **Push** — push from the innermost repos outward to the root, so GitHub is fully up to date at every level
+
+### Options
+
+| Flag | Description |
+|---|---|
+| `--no-push` | Pull locally only, do not commit or push |
+| `--dry-run` | Preview what would change without touching anything |
+| `--message <m>` | Custom commit message (default: `chore: update submodule refs`) |
+| `--branch <b>` | Default branch if not declared in `.gitmodules` (default: `main`) |
+| `--depth <n>` | Limit recursion depth |
+| `--verbose` | Show full git output for every operation |
+| `--no-color` | Disable colored output |
+
+### Examples
+
+```bash
+# Standard usage — pull + commit + push everything
+github-update-submodule
+
+# Preview changes without modifying anything
+github-update-submodule --dry-run
+
+# Pull locally only, skip the push
+github-update-submodule --no-push
+
+# Custom commit message
+github-update-submodule --message "ci: bump all submodule refs to latest"
+
+# Run on a specific repo path
+github-update-submodule /path/to/your/repo
+
+# Use master as the default branch
+github-update-submodule --branch master
+
+# Limit to 2 levels of nesting
+github-update-submodule --depth 2
+```
+
+---
+
+## How It Works
+
+### Phase 1 — Pull
+
+For each submodule (recursively):
+
+1. Initialises any submodule that hasn't been cloned yet
+2. Runs `git fetch --prune origin`
+3. Resolves the correct branch (from `.gitmodules`, then remote HEAD, then `--branch` flag)
+4. Runs `git checkout -B <branch> origin/<branch>` to hard-move to the remote tip
+5. Stages the updated pointer in the parent repo with `git add <path>`
+6. Recurses into the submodule's own submodules
+
+### Phase 2 — Commit & Push
+
+Walks the repo tree **innermost → outermost**:
+
+1. For each repo that has staged changes, commits with the configured message
+2. Pushes to `origin/<branch>`
+3. Moves up to the parent and repeats
+
+The innermost-first order ensures that by the time GitHub receives a pointer update from a parent repo, the commit it points to already exists on the remote.
+
+---
+
+## Example Output
+
+```
+╔══════════════════════════════════════════╗
+║   github-update-submodule                ║
+╚══════════════════════════════════════════╝
+
+› Repository     : /projects/my-app
+› Default branch : main
+› Push mode      : ON
+
+Phase 1 — Pull all submodules to latest remote commit
+
+▸ QuantumDocsSyncer  (docs/QuantumDocsSyncer)
+  › Fetching from origin…
+  › Branch: main
+  ✔ Updated  d11a9fce → 4a82bc91
+  ▸ frontend  (frontend)
+    › Fetching from origin…
+    › Branch: main
+    ✔ Updated  fe03e5be → 9c14d7aa
+  ▸ backend  (backend)
+    › Fetching from origin…
+    › Branch: main
+    ✔ Already up to date (b6732bc5)
+
+Phase 2 — Commit & push updated refs (innermost → root)
+
+› QuantumDocsSyncer — committing on main…
+↑ QuantumDocsSyncer → origin/main
+› my-app — committing on main…
+↑ my-app → origin/main
+
+─────────────────────────────────────────
+Summary
+  ✔ Updated    : 2
+  · Up to date : 1
+  ↑ Committed  : 2
+  ↑ Pushed     : 2
+  ⚠ Skipped    : 0
+  ✘ Failed     : 0
+    Total      : 3  (18.42s)
+```
+
+---
+
+## Requirements
+
+- **Node.js** >= 14
+- **Git** installed and available in your PATH
+- Your git remotes must be authenticated (SSH keys or credential manager) so pushes can succeed without a password prompt
+
+---
+
+## License
+
+MIT

package/bin/github-update-submodule.js

@@ -0,0 +1,376 @@
+#!/usr/bin/env node
+
+/**
+ * github-update-submodule
+ * Recursively pulls all Git submodules to their latest remote commit,
+ * then commits and pushes the updated refs up every parent repo —
+ * so GitHub always points to the latest commit in every submodule.
+ *
+ * Usage:
+ *   github-update-submodule [repo-path] [options]
+ *
+ * Options:
+ *   --no-push         Skip committing and pushing (local update only)
+ *   --message  <m>    Commit message  (default: "chore: update submodule refs")
+ *   --dry-run         Show what would happen without making any changes
+ *   --branch   <b>    Default branch when none is declared in .gitmodules (default: main)
+ *   --depth    <n>    Max recursion depth (default: unlimited)
+ *   --verbose         Show full git output
+ *   --no-color        Disable colored output
+ *
+ * Examples:
+ *   github-update-submodule
+ *   github-update-submodule --dry-run
+ *   github-update-submodule --no-push
+ *   github-update-submodule --message "ci: bump submodules"
+ *   github-update-submodule /path/to/repo --branch master
+ */
+
+const { spawnSync } = require("child_process");
+const path = require("path");
+const fs = require("fs");
+
+// ─── CLI argument parsing ────────────────────────────────────────────────────
+
+const args = process.argv.slice(2);
+
+const options = {
+  repoPath:      process.cwd(),
+  push:          true,                          // ON by default
+  commitMessage: "chore: update submodule refs",
+  dryRun:        false,
+  defaultBranch: "main",
+  maxDepth:      Infinity,
+  verbose:       false,
+  color:         true,
+};
+
+for (let i = 0; i < args.length; i++) {
+  const arg = args[i];
+  if      (arg === "--no-push")   options.push          = false;
+  else if (arg === "--dry-run")   options.dryRun        = true;
+  else if (arg === "--verbose")   options.verbose       = true;
+  else if (arg === "--no-color")  options.color         = false;
+  else if (arg === "--branch")    options.defaultBranch = args[++i];
+  else if (arg === "--message")   options.commitMessage = args[++i];
+  else if (arg === "--depth")     options.maxDepth      = parseInt(args[++i], 10);
+  else if (!arg.startsWith("--")) options.repoPath      = path.resolve(arg);
+}
+
+// ─── Colour helpers ──────────────────────────────────────────────────────────
+
+const C = options.color
+  ? { reset:"\x1b[0m", bold:"\x1b[1m", dim:"\x1b[2m", green:"\x1b[32m",
+      yellow:"\x1b[33m", cyan:"\x1b[36m", red:"\x1b[31m", magenta:"\x1b[35m", blue:"\x1b[34m" }
+  : Object.fromEntries(
+      ["reset","bold","dim","green","yellow","cyan","red","magenta","blue"].map(k => [k, ""])
+    );
+
+// ─── Logging ─────────────────────────────────────────────────────────────────
+
+const indent  = (d) => "  ".repeat(d);
+const log     = (d, sym, col, msg) => console.log(`${indent(d)}${col}${sym} ${msg}${C.reset}`);
+const info    = (d, m) => log(d, "›", C.cyan,             m);
+const success = (d, m) => log(d, "✔", C.green,            m);
+const warn    = (d, m) => log(d, "⚠", C.yellow,           m);
+const error   = (d, m) => log(d, "✘", C.red,              m);
+const header  = (d, m) => log(d, "▸", C.bold + C.magenta, m);
+const pushLog = (d, m) => log(d, "↑", C.bold + C.green,   m);
+const verbose = (d, m) => { if (options.verbose) log(d, " ", C.dim, m); };
+
+// ─── Git helpers ─────────────────────────────────────────────────────────────
+
+function git(cwd, ...gitArgs) {
+  const r = spawnSync("git", gitArgs, {
+    cwd,
+    encoding: "utf8",
+    env: { ...process.env, GIT_TERMINAL_PROMPT: "0" },
+  });
+  return {
+    stdout: (r.stdout || "").trim(),
+    stderr: (r.stderr || "").trim(),
+    ok:     r.status === 0,
+  };
+}
+
+function isGitRepo(dir) {
+  return fs.existsSync(path.join(dir, ".git"));
+}
+
+function parseGitmodules(repoDir) {
+  const gmPath = path.join(repoDir, ".gitmodules");
+  if (!fs.existsSync(gmPath)) return [];
+
+  const submodules = [];
+  let cur = null;
+
+  for (const rawLine of fs.readFileSync(gmPath, "utf8").split("\n")) {
+    const line = rawLine.trim();
+    if (!line || line.startsWith("#")) continue;
+
+    const sec = line.match(/^\[submodule\s+"(.+)"\]$/);
+    if (sec) {
+      cur = { name: sec[1], path: null, url: null, branch: null };
+      submodules.push(cur);
+      continue;
+    }
+    if (!cur) continue;
+
+    const kv = line.match(/^(\w+)\s*=\s*(.+)$/);
+    if (kv) {
+      if (kv[1] === "path")   cur.path   = kv[2];
+      if (kv[1] === "url")    cur.url    = kv[2];
+      if (kv[1] === "branch") cur.branch = kv[2];
+    }
+  }
+  return submodules.filter(s => s.path);
+}
+
+function resolveBranch(dir, declared) {
+  if (declared) return declared;
+  const r = git(dir, "remote", "show", "origin");
+  if (r.ok) {
+    const m = r.stdout.match(/HEAD branch:\s+(\S+)/);
+    if (m) return m[1];
+  }
+  return options.defaultBranch;
+}
+
+function hasStagedChanges(dir) {
+  return !git(dir, "diff", "--cached", "--quiet").ok;
+}
+
+// ─── Statistics ───────────────────────────────────────────────────────────────
+
+const stats = {
+  updated: 0, upToDate: 0, skipped: 0, failed: 0,
+  committed: 0, pushed: 0, total: 0,
+};
+
+// ─── Phase 1 — pull every submodule to the remote tip ────────────────────────
+
+function pullSubmodules(repoDir, depth = 0) {
+  if (depth > options.maxDepth) { warn(depth, "Max depth reached."); return false; }
+
+  const submodules = parseGitmodules(repoDir);
+  if (!submodules.length) { verbose(depth, "No submodules."); return false; }
+
+  let anyChanged = false;
+
+  for (const sub of submodules) {
+    const subDir = path.resolve(repoDir, sub.path);
+    stats.total++;
+
+    header(depth, `${sub.name}  ${C.dim}(${sub.path})${C.reset}`);
+
+    // Init if missing
+    if (!fs.existsSync(subDir) || !isGitRepo(subDir)) {
+      info(depth + 1, "Not initialised — running git submodule update --init");
+      if (!options.dryRun) {
+        const init = git(repoDir, "submodule", "update", "--init", "--", sub.path);
+        if (!init.ok) {
+          error(depth + 1, `Init failed: ${init.stderr}`);
+          stats.failed++;
+          continue;
+        }
+      }
+    }
+
+    if (!fs.existsSync(subDir)) {
+      warn(depth + 1, "Directory missing after init — skipping.");
+      stats.skipped++;
+      continue;
+    }
+
+    // Fetch
+    info(depth + 1, "Fetching from origin…");
+    if (!options.dryRun) {
+      const f = git(subDir, "fetch", "--prune", "origin");
+      if (!f.ok) warn(depth + 1, `Fetch warning: ${f.stderr}`);
+      else verbose(depth + 1, f.stderr || "fetch ok");
+    }
+
+    // Resolve branch + remote tip
+    const branch    = resolveBranch(subDir, sub.branch);
+    const remoteRef = `origin/${branch}`;
+    const remoteTip = git(subDir, "rev-parse", remoteRef).stdout;
+
+    info(depth + 1, `Branch: ${C.bold}${branch}${C.reset}`);
+
+    if (!remoteTip) {
+      warn(depth + 1, `Cannot resolve ${remoteRef} — skipping.`);
+      stats.skipped++;
+      continue;
+    }
+
+    const beforeHash = git(subDir, "rev-parse", "HEAD").stdout;
+
+    // Dry-run path
+    if (options.dryRun) {
+      if (beforeHash === remoteTip) {
+        success(depth + 1, `Up to date (${remoteTip.slice(0, 8)})`);
+        stats.upToDate++;
+      } else {
+        success(depth + 1,
+          `Would update  ${C.dim}${beforeHash.slice(0, 8)}${C.reset} → ${C.bold}${C.green}${remoteTip.slice(0, 8)}${C.reset}  (dry-run)`);
+        stats.updated++;
+        anyChanged = true;
+      }
+      pullSubmodules(subDir, depth + 1);
+      continue;
+    }
+
+    // Checkout -B <branch> <remoteRef> — moves branch pointer to remote tip
+    const co = git(subDir, "checkout", "-B", branch, remoteRef);
+    if (!co.ok) {
+      const co2 = git(subDir, "checkout", branch);
+      if (!co2.ok) {
+        error(depth + 1, `Cannot checkout '${branch}': ${co2.stderr}`);
+        stats.failed++;
+        continue;
+      }
+      const rs = git(subDir, "reset", "--hard", remoteRef);
+      if (!rs.ok) {
+        error(depth + 1, `reset --hard failed: ${rs.stderr}`);
+        stats.failed++;
+        continue;
+      }
+      verbose(depth + 1, rs.stdout);
+    } else {
+      verbose(depth + 1, co.stdout || co.stderr);
+    }
+
+    const afterHash = git(subDir, "rev-parse", "HEAD").stdout;
+
+    // Stage updated pointer in parent
+    git(repoDir, "add", sub.path);
+
+    if (beforeHash === afterHash) {
+      success(depth + 1, `Already up to date (${afterHash.slice(0, 8)})`);
+      stats.upToDate++;
+    } else {
+      success(depth + 1,
+        `Updated  ${C.dim}${beforeHash.slice(0, 8)}${C.reset} → ${C.bold}${C.green}${afterHash.slice(0, 8)}${C.reset}`);
+      stats.updated++;
+      anyChanged = true;
+    }
+
+    // Recurse — if a nested pointer changed, re-stage this submodule in parent
+    if (pullSubmodules(subDir, depth + 1)) {
+      git(repoDir, "add", sub.path);
+      anyChanged = true;
+    }
+  }
+
+  return anyChanged;
+}
+
+// ─── Phase 2 — commit + push updated refs, innermost repos first ─────────────
+
+function commitAndPush(repoDir, label, depth = 0) {
+  // Children first so innermost repos are pushed before outer ones
+  for (const sub of parseGitmodules(repoDir)) {
+    const subDir = path.resolve(repoDir, sub.path);
+    if (fs.existsSync(subDir) && isGitRepo(subDir)) {
+      commitAndPush(subDir, sub.name, depth + 1);
+    }
+  }
+
+  if (!hasStagedChanges(repoDir)) {
+    verbose(depth, `${label}: nothing staged — skipping`);
+    return;
+  }
+
+  const branch = resolveBranch(repoDir, null);
+  info(depth, `${C.bold}${label}${C.reset} — committing on ${C.bold}${branch}${C.reset}…`);
+
+  if (options.dryRun) {
+    warn(depth, `Would commit + push '${label}' → origin/${branch}  (dry-run)`);
+    stats.committed++;
+    stats.pushed++;
+    return;
+  }
+
+  const commit = git(repoDir, "commit", "-m", options.commitMessage);
+  if (!commit.ok) {
+    if (/nothing to commit/.test(commit.stdout + commit.stderr)) {
+      verbose(depth, `${label}: nothing to commit`);
+      return;
+    }
+    error(depth, `Commit failed in '${label}': ${commit.stderr}`);
+    stats.failed++;
+    return;
+  }
+  verbose(depth, commit.stdout);
+  stats.committed++;
+
+  info(depth, `Pushing ${C.bold}${label}${C.reset} → origin/${branch}…`);
+  const pushR = git(repoDir, "push", "origin", branch);
+  if (!pushR.ok) {
+    error(depth, `Push failed in '${label}': ${pushR.stderr}`);
+    stats.failed++;
+    return;
+  }
+  pushLog(depth, `${C.bold}${label}${C.reset} → origin/${branch}`);
+  stats.pushed++;
+}
+
+// ─── Entry point ─────────────────────────────────────────────────────────────
+
+function main() {
+  console.log();
+  console.log(`${C.bold}${C.blue}╔══════════════════════════════════════════╗${C.reset}`);
+  console.log(`${C.bold}${C.blue}║   github-update-submodule                ║${C.reset}`);
+  console.log(`${C.bold}${C.blue}╚══════════════════════════════════════════╝${C.reset}`);
+  console.log();
+
+  if (!isGitRepo(options.repoPath)) {
+    error(0, `Not a git repository: ${options.repoPath}`);
+    process.exit(1);
+  }
+
+  info(0, `Repository     : ${C.bold}${options.repoPath}${C.reset}`);
+  info(0, `Default branch : ${C.bold}${options.defaultBranch}${C.reset}`);
+  info(0, `Push mode      : ${options.push ? C.bold + C.green + "ON" : C.dim + "OFF"}${C.reset}`);
+  if (options.dryRun)                warn(0, "DRY RUN — no changes will be made");
+  if (options.maxDepth !== Infinity) info(0, `Max depth      : ${options.maxDepth}`);
+  console.log();
+
+  const t0 = Date.now();
+
+  // Phase 1 — pull
+  console.log(`${C.bold}${C.cyan}Phase 1 — Pull all submodules to latest remote commit${C.reset}`);
+  console.log();
+  pullSubmodules(options.repoPath, 0);
+
+  // Phase 2 — commit + push
+  if (options.push) {
+    console.log();
+    console.log(`${C.bold}${C.cyan}Phase 2 — Commit & push updated refs (innermost → root)${C.reset}`);
+    console.log();
+    commitAndPush(options.repoPath, path.basename(options.repoPath), 0);
+  } else {
+    console.log();
+    warn(0, `Refs staged locally but NOT pushed (--no-push mode).`);
+  }
+
+  const elapsed = ((Date.now() - t0) / 1000).toFixed(2);
+
+  console.log();
+  console.log(`${C.bold}${C.blue}─────────────────────────────────────────${C.reset}`);
+  console.log(`${C.bold}Summary${C.reset}`);
+  console.log(`  ${C.green}✔ Updated    : ${stats.updated}${C.reset}`);
+  console.log(`  ${C.cyan}· Up to date : ${stats.upToDate}${C.reset}`);
+  if (options.push) {
+    console.log(`  ${C.green}↑ Committed  : ${stats.committed}${C.reset}`);
+    console.log(`  ${C.green}↑ Pushed     : ${stats.pushed}${C.reset}`);
+  }
+  console.log(`  ${C.yellow}⚠ Skipped    : ${stats.skipped}${C.reset}`);
+  console.log(`  ${C.red}✘ Failed     : ${stats.failed}${C.reset}`);
+  console.log(`  ${C.dim}  Total      : ${stats.total}  (${elapsed}s)${C.reset}`);
+  console.log();
+
+  if (stats.failed > 0) process.exit(1);
+}
+
+main();

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "github-update-submodule",
+  "version": "1.0.0",
+  "description": "Recursively pull all Git submodules to their latest remote commit and push updated refs up every parent repo — so GitHub always points to the latest.",
+  "main": "bin/github-update-submodule.js",
+  "bin": {
+    "github-update-submodule": "bin/github-update-submodule.js"
+  },
+  "scripts": {
+    "test": "echo \"No tests yet\" && exit 0"
+  },
+  "keywords": [
+    "git",
+    "submodule",
+    "github",
+    "recursive",
+    "update",
+    "cli"
+  ],
+  "author": "Muhammad Saad Amin",
+  "license": "MIT",
+  "engines": {
+    "node": ">=14.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/SENODROOM/github-update-submodule.git"
+  },
+  "bugs": {
+    "url": "https://github.com/SENODROOM/github-update-submodule/issues"
+  },
+  "homepage": "https://github.com/SENODROOM/github-update-submodule#readme"
+}