feat: support coordinated feature branching across nested independent git repos

sakitA · Copilot · sakitA · commit 4e28ed8c05dc · 2026-04-08T00:37:03.000-07:00
Add auto-detection of nested independent git repositories (not submodules) and create matching feature branches in each when running create-new-feature. Changes: - common.sh: Add find_nested_git_repos() - discovers nested repos up to 2 levels deep - common.ps1: Add Find-NestedGitRepos - PowerShell equivalent - create-new-feature.sh: Create feature branches in all nested repos after root - create-new-feature.ps1: Same for PowerShell - specify.md: Document NESTED_REPOS JSON output field - test_nested_repos.py: 9 tests covering discovery and branch creation Design decisions: - Auto-detect via .git presence (no configuration required) - Non-blocking: nested repo failures are warnings, not errors - JSON output extended with NESTED_REPOS array [{path, status}] - Backward-compatible: no change for single-repo workflows Resolves #2120 Related to #1050 Note: This contribution was made with AI assistance (GitHub Copilot). Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
diff --git a/scripts/bash/common.sh b/scripts/bash/common.sh
@@ -252,6 +252,58 @@ json_escape() {
 check_file() { [[ -f "$1" ]] && echo "  ✓ $2" || echo "  ✗ $2"; }
 check_dir() { [[ -d "$1" && -n $(ls -A "$1" 2>/dev/null) ]] && echo "  ✓ $2" || echo "  ✗ $2"; }
 
+# Discover nested independent git repositories under REPO_ROOT.
+# Searches up to 2 directory levels deep for subdirectories containing .git
+# (directory or file, covering worktrees/submodules). Excludes the root repo
+# itself and common non-project directories.
+# Outputs one absolute path per line.
+find_nested_git_repos() {
+    local repo_root="${1:-$(get_repo_root)}"
+    # Directories to skip during traversal
+    local -a skip_dirs=(".specify" ".git" "node_modules" "vendor" ".venv" "venv"
+                        "__pycache__" ".gradle" "build" "dist" "target" ".idea"
+                        ".vscode" "specs")
+
+    _should_skip() {
+        local name="$1"
+        for skip in "${skip_dirs[@]}"; do
+            [ "$name" = "$skip" ] && return 0
+        done
+        return 1
+    }
+
+    # Level 1
+    for child in "$repo_root"/*/; do
+        [ -d "$child" ] || continue
+        child="${child%/}"
+        local child_name
+        child_name="$(basename "$child")"
+        _should_skip "$child_name" && continue
+
+        if [ -e "$child/.git" ]; then
+            # Verify it is a valid git work tree
+            if git -C "$child" rev-parse --is-inside-work-tree >/dev/null 2>&1; then
+                echo "$child"
+            fi
+        else
+            # Level 2
+            for grandchild in "$child"/*/; do
+                [ -d "$grandchild" ] || continue
+                grandchild="${grandchild%/}"
+                local gc_name
+                gc_name="$(basename "$grandchild")"
+                _should_skip "$gc_name" && continue
+
+                if [ -e "$grandchild/.git" ]; then
+                    if git -C "$grandchild" rev-parse --is-inside-work-tree >/dev/null 2>&1; then
+                        echo "$grandchild"
+                    fi
+                fi
+            done
+        fi
+    done
+}
+
 # Resolve a template name to a file path using the priority stack:
 #   1. .specify/templates/overrides/
 #   2. .specify/presets/<preset-id>/templates/ (sorted by priority from .registry)
diff --git a/scripts/bash/create-new-feature.sh b/scripts/bash/create-new-feature.sh
@@ -368,32 +368,101 @@ if [ "$DRY_RUN" != true ]; then
     printf '# To persist: export SPECIFY_FEATURE=%q\n' "$BRANCH_NAME" >&2
 fi
 
+# Create matching feature branches in nested independent git repositories
+NESTED_REPOS_JSON=""
+if [ "$HAS_GIT" = true ]; then
+    nested_repos=$(find_nested_git_repos "$REPO_ROOT")
+    if [ -n "$nested_repos" ]; then
+        NESTED_REPOS_JSON="["
+        first=true
+        while IFS= read -r nested_path; do
+            [ -z "$nested_path" ] && continue
+            # Normalize: remove trailing slash
+            nested_path="${nested_path%/}"
+            # Compute relative path for output
+            rel_path="${nested_path#"$REPO_ROOT/"}"
+            rel_path="${rel_path%/}"
+            status="skipped"
+
+            if [ "$DRY_RUN" = true ]; then
+                status="dry_run"
+            else
+                # Attempt to create the branch in the nested repo
+                if git -C "$nested_path" checkout -q -b "$BRANCH_NAME" 2>/dev/null; then
+                    status="created"
+                else
+                    # Check if the branch already exists
+                    if git -C "$nested_path" branch --list "$BRANCH_NAME" 2>/dev/null | grep -q .; then
+                        if [ "$ALLOW_EXISTING" = true ]; then
+                            current_nested="$(git -C "$nested_path" rev-parse --abbrev-ref HEAD 2>/dev/null || true)"
+                            if [ "$current_nested" = "$BRANCH_NAME" ]; then
+                                status="existing"
+                            elif git -C "$nested_path" checkout -q "$BRANCH_NAME" 2>/dev/null; then
+                                status="existing"
+                            else
+                                status="failed"
+                                >&2 echo "[specify] Warning: Failed to switch nested repo '$rel_path' to branch '$BRANCH_NAME'"
+                            fi
+                        else
+                            status="existing"
+                        fi
+                    else
+                        status="failed"
+                        >&2 echo "[specify] Warning: Failed to create branch '$BRANCH_NAME' in nested repo '$rel_path'"
+                    fi
+                fi
+            fi
+
+            if [ "$first" = true ]; then
+                first=false
+            else
+                NESTED_REPOS_JSON+=","
+            fi
+            NESTED_REPOS_JSON+="{\"path\":\"$(json_escape "$rel_path")\",\"status\":\"$status\"}"
+        done <<< "$nested_repos"
+        NESTED_REPOS_JSON+="]"
+    fi
+fi
+
 if $JSON_MODE; then
+    # Build the nested repos portion for JSON output
+    nested_json_field=""
+    if [ -n "$NESTED_REPOS_JSON" ]; then
+        nested_json_field="$NESTED_REPOS_JSON"
+    else
+        nested_json_field="[]"
+    fi
+
     if command -v jq >/dev/null 2>&1; then
         if [ "$DRY_RUN" = true ]; then
             jq -cn \
                 --arg branch_name "$BRANCH_NAME" \
                 --arg spec_file "$SPEC_FILE" \
                 --arg feature_num "$FEATURE_NUM" \
-                '{BRANCH_NAME:$branch_name,SPEC_FILE:$spec_file,FEATURE_NUM:$feature_num,DRY_RUN:true}'
+                --argjson nested_repos "$nested_json_field" \
+                '{BRANCH_NAME:$branch_name,SPEC_FILE:$spec_file,FEATURE_NUM:$feature_num,DRY_RUN:true,NESTED_REPOS:$nested_repos}'
         else
             jq -cn \
                 --arg branch_name "$BRANCH_NAME" \
                 --arg spec_file "$SPEC_FILE" \
                 --arg feature_num "$FEATURE_NUM" \
-                '{BRANCH_NAME:$branch_name,SPEC_FILE:$spec_file,FEATURE_NUM:$feature_num}'
+                --argjson nested_repos "$nested_json_field" \
+                '{BRANCH_NAME:$branch_name,SPEC_FILE:$spec_file,FEATURE_NUM:$feature_num,NESTED_REPOS:$nested_repos}'
         fi
     else
         if [ "$DRY_RUN" = true ]; then
-            printf '{"BRANCH_NAME":"%s","SPEC_FILE":"%s","FEATURE_NUM":"%s","DRY_RUN":true}\n' "$(json_escape "$BRANCH_NAME")" "$(json_escape "$SPEC_FILE")" "$(json_escape "$FEATURE_NUM")"
+            printf '{"BRANCH_NAME":"%s","SPEC_FILE":"%s","FEATURE_NUM":"%s","DRY_RUN":true,"NESTED_REPOS":%s}\n' "$(json_escape "$BRANCH_NAME")" "$(json_escape "$SPEC_FILE")" "$(json_escape "$FEATURE_NUM")" "$nested_json_field"
         else
-            printf '{"BRANCH_NAME":"%s","SPEC_FILE":"%s","FEATURE_NUM":"%s"}\n' "$(json_escape "$BRANCH_NAME")" "$(json_escape "$SPEC_FILE")" "$(json_escape "$FEATURE_NUM")"
+            printf '{"BRANCH_NAME":"%s","SPEC_FILE":"%s","FEATURE_NUM":"%s","NESTED_REPOS":%s}\n' "$(json_escape "$BRANCH_NAME")" "$(json_escape "$SPEC_FILE")" "$(json_escape "$FEATURE_NUM")" "$nested_json_field"
         fi
     fi
 else
     echo "BRANCH_NAME: $BRANCH_NAME"
     echo "SPEC_FILE: $SPEC_FILE"
     echo "FEATURE_NUM: $FEATURE_NUM"
+    if [ -n "$NESTED_REPOS_JSON" ] && [ "$NESTED_REPOS_JSON" != "[]" ]; then
+        echo "NESTED_REPOS: $NESTED_REPOS_JSON"
+    fi
     if [ "$DRY_RUN" != true ]; then
         printf '# To persist in your shell: export SPECIFY_FEATURE=%q\n' "$BRANCH_NAME"
     fi
diff --git a/scripts/powershell/common.ps1 b/scripts/powershell/common.ps1
@@ -199,6 +199,56 @@ function Test-DirHasFiles {
     }
 }
 
+# Discover nested independent git repositories under RepoRoot.
+# Searches up to 2 directory levels deep for subdirectories containing .git
+# (directory or file, covering worktrees/submodules). Excludes the root repo
+# itself and common non-project directories.
+# Returns an array of absolute paths.
+function Find-NestedGitRepos {
+    param([string]$RepoRoot = (Get-RepoRoot))
+
+    $skipDirs = @('.specify', '.git', 'node_modules', 'vendor', '.venv', 'venv',
+                  '__pycache__', '.gradle', 'build', 'dist', 'target', '.idea',
+                  '.vscode', 'specs')
+
+    $results = @()
+
+    # Level 1
+    $children = Get-ChildItem -Path $RepoRoot -Directory -ErrorAction SilentlyContinue |
+        Where-Object { $skipDirs -notcontains $_.Name }
+
+    foreach ($child in $children) {
+        $gitMarker = Join-Path $child.FullName '.git'
+        if (Test-Path -LiteralPath $gitMarker) {
+            # Verify it is a valid git work tree
+            try {
+                $null = git -C $child.FullName rev-parse --is-inside-work-tree 2>$null
+                if ($LASTEXITCODE -eq 0) {
+                    $results += $child.FullName
+                }
+            } catch { }
+        } else {
+            # Level 2
+            $grandchildren = Get-ChildItem -Path $child.FullName -Directory -ErrorAction SilentlyContinue |
+                Where-Object { $skipDirs -notcontains $_.Name }
+
+            foreach ($gc in $grandchildren) {
+                $gcGitMarker = Join-Path $gc.FullName '.git'
+                if (Test-Path -LiteralPath $gcGitMarker) {
+                    try {
+                        $null = git -C $gc.FullName rev-parse --is-inside-work-tree 2>$null
+                        if ($LASTEXITCODE -eq 0) {
+                            $results += $gc.FullName
+                        }
+                    } catch { }
+                }
+            }
+        }
+    }
+
+    return $results
+}
+
 # Resolve a template name to a file path using the priority stack:
 #   1. .specify/templates/overrides/
 #   2. .specify/presets/<preset-id>/templates/ (sorted by priority from .registry)
diff --git a/scripts/powershell/create-new-feature.ps1 b/scripts/powershell/create-new-feature.ps1
@@ -344,12 +344,70 @@ if (-not $DryRun) {
     $env:SPECIFY_FEATURE = $branchName
 }
 
+# Create matching feature branches in nested independent git repositories
+$nestedReposResult = @()
+if ($hasGit) {
+    $nestedRepos = Find-NestedGitRepos -RepoRoot $repoRoot
+    foreach ($nestedPath in $nestedRepos) {
+        $relPath = $nestedPath.Substring($repoRoot.Length).TrimStart('\', '/')
+        $nestedStatus = 'skipped'
+
+        if ($DryRun) {
+            $nestedStatus = 'dry_run'
+        } else {
+            try {
+                git -C $nestedPath checkout -q -b $branchName 2>$null | Out-Null
+                if ($LASTEXITCODE -eq 0) {
+                    $nestedStatus = 'created'
+                } else {
+                    throw "branch creation failed"
+                }
+            } catch {
+                # Check if branch already exists
+                $existingNested = git -C $nestedPath branch --list $branchName 2>$null
+                if ($existingNested) {
+                    if ($AllowExistingBranch) {
+                        $currentNested = git -C $nestedPath rev-parse --abbrev-ref HEAD 2>$null
+                        if ($currentNested -eq $branchName) {
+                            $nestedStatus = 'existing'
+                        } else {
+                            try {
+                                git -C $nestedPath checkout -q $branchName 2>$null | Out-Null
+                                if ($LASTEXITCODE -eq 0) {
+                                    $nestedStatus = 'existing'
+                                } else {
+                                    $nestedStatus = 'failed'
+                                    Write-Warning "[specify] Failed to switch nested repo '$relPath' to branch '$branchName'"
+                                }
+                            } catch {
+                                $nestedStatus = 'failed'
+                                Write-Warning "[specify] Failed to switch nested repo '$relPath' to branch '$branchName'"
+                            }
+                        }
+                    } else {
+                        $nestedStatus = 'existing'
+                    }
+                } else {
+                    $nestedStatus = 'failed'
+                    Write-Warning "[specify] Failed to create branch '$branchName' in nested repo '$relPath'"
+                }
+            }
+        }
+
+        $nestedReposResult += [PSCustomObject]@{
+            path = $relPath
+            status = $nestedStatus
+        }
+    }
+}
+
 if ($Json) {
     $obj = [PSCustomObject]@{
         BRANCH_NAME = $branchName
         SPEC_FILE = $specFile
         FEATURE_NUM = $featureNum
         HAS_GIT = $hasGit
+        NESTED_REPOS = $nestedReposResult
     }
     if ($DryRun) {
         $obj | Add-Member -NotePropertyName 'DRY_RUN' -NotePropertyValue $true
@@ -360,6 +418,12 @@ if ($Json) {
     Write-Output "SPEC_FILE: $specFile"
     Write-Output "FEATURE_NUM: $featureNum"
     Write-Output "HAS_GIT: $hasGit"
+    if ($nestedReposResult.Count -gt 0) {
+        Write-Output "NESTED_REPOS:"
+        foreach ($nr in $nestedReposResult) {
+            Write-Output "  $($nr.path): $($nr.status)"
+        }
+    }
     if (-not $DryRun) {
         Write-Output "SPECIFY_FEATURE environment variable set to: $branchName"
     }
diff --git a/templates/commands/specify.md b/templates/commands/specify.md
@@ -89,8 +89,9 @@ Given that feature description, do this:
    - Always include the JSON flag (`--json` for Bash, `-Json` for PowerShell) so the output can be parsed reliably
    - You must only ever run this script once per feature
    - The JSON is provided in the terminal as output - always refer to it to get the actual content you're looking for
-   - The JSON output will contain BRANCH_NAME and SPEC_FILE paths
+   - The JSON output will contain BRANCH_NAME, SPEC_FILE paths, and NESTED_REPOS (an array of nested independent git repositories where the feature branch was also created)
    - For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'\''m Groot' (or double-quote if possible: "I'm Groot")
+   - **Nested git repos**: The script auto-detects subdirectories with their own `.git` (up to 2 levels deep) and creates the same feature branch in each. The JSON output includes a `NESTED_REPOS` array with `path` and `status` (`created`, `existing`, `dry_run`, or `failed`) for each nested repo. Failures in nested repos are warnings and do not block the main workflow.
 
 3. Load `templates/spec-template.md` to understand required sections.
 
diff --git a/tests/test_nested_repos.py b/tests/test_nested_repos.py
