feat: configurable scan depth and selective repo branching

sakitA · Copilot · sakitA · commit 5a80b813ed4a · 2026-04-08T00:49:01.000-07:00
Enhance nested repo support with two key improvements:

1. Configurable scan depth:
   - find_nested_git_repos() / Find-NestedGitRepos now accept a depth parameter
   - Uses recursive traversal instead of hardcoded 2-level nesting
   - New --scan-depth (Bash) / -ScanDepth (PowerShell) flag
   - Reads nested_repo_scan_depth from init-options.json

2. Selective branching via --repos flag:
   - New --repos (Bash) / -Repos (PowerShell) flag accepts comma-separated paths
   - Only branches repos matching the specified paths
   - Omit flag to branch all discovered repos (backward compatible)
   - Enables spec-driven branching: AI agents select relevant repos per feature

Tests: 17 tests (8 new for depth + filtering), all passing.
Docs: Updated specify.md with --repos, --scan-depth, and init-options.json config.

Co-authored-by: Copilot &lt;223556219+Copilot@users.noreply.github.com&gt;
diff --git a/scripts/bash/common.sh b/scripts/bash/common.sh
@@ -253,12 +253,16 @@ 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.
+# Searches up to $max_depth directory levels deep for subdirectories containing
+# .git (directory or file, covering worktrees/submodules). Excludes the root
+# repo itself and common non-project directories.
+# Usage: find_nested_git_repos [repo_root] [max_depth]
+#   repo_root  — defaults to $(get_repo_root)
+#   max_depth  — defaults to 2
 # Outputs one absolute path per line.
 find_nested_git_repos() {
     local repo_root="${1:-$(get_repo_root)}"
+    local max_depth="${2:-2}"
     # Directories to skip during traversal
     local -a skip_dirs=(".specify" ".git" "node_modules" "vendor" ".venv" "venv"
                         "__pycache__" ".gradle" "build" "dist" "target" ".idea"
@@ -272,36 +276,27 @@ find_nested_git_repos() {
         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
+    _scan_dir() {
+        local dir="$1"
+        local current_depth="$2"
+        for child in "$dir"/*/; do
+            [ -d "$child" ] || continue
+            child="${child%/}"
+            local child_name
+            child_name="$(basename "$child")"
+            _should_skip "$child_name" && continue
+
+            if [ -e "$child/.git" ]; then
+                if git -C "$child" rev-parse --is-inside-work-tree >/dev/null 2>&1; then
+                    echo "$child"
                 fi
-            done
-        fi
-    done
+            elif [ "$current_depth" -lt "$max_depth" ]; then
+                _scan_dir "$child" $((current_depth + 1))
+            fi
+        done
+    }
+
+    _scan_dir "$repo_root" 1
 }
 
 # Resolve a template name to a file path using the priority stack:
diff --git a/scripts/bash/create-new-feature.sh b/scripts/bash/create-new-feature.sh
@@ -8,6 +8,8 @@ ALLOW_EXISTING=false
 SHORT_NAME=""
 BRANCH_NUMBER=""
 USE_TIMESTAMP=false
+NESTED_REPOS_FILTER=""
+SCAN_DEPTH=""
 ARGS=()
 i=1
 while [ $i -le $# ]; do
@@ -52,8 +54,34 @@ while [ $i -le $# ]; do
         --timestamp)
             USE_TIMESTAMP=true
             ;;
+        --repos)
+            if [ $((i + 1)) -gt $# ]; then
+                echo 'Error: --repos requires a value (comma-separated list of repo paths)' >&2
+                exit 1
+            fi
+            i=$((i + 1))
+            next_arg="${!i}"
+            if [[ "$next_arg" == --* ]]; then
+                echo 'Error: --repos requires a value (comma-separated list of repo paths)' >&2
+                exit 1
+            fi
+            NESTED_REPOS_FILTER="$next_arg"
+            ;;
+        --scan-depth)
+            if [ $((i + 1)) -gt $# ]; then
+                echo 'Error: --scan-depth requires a value' >&2
+                exit 1
+            fi
+            i=$((i + 1))
+            next_arg="${!i}"
+            if [[ "$next_arg" == --* ]]; then
+                echo 'Error: --scan-depth requires a value' >&2
+                exit 1
+            fi
+            SCAN_DEPTH="$next_arg"
+            ;;
         --help|-h)
-            echo "Usage: $0 [--json] [--dry-run] [--allow-existing-branch] [--short-name <name>] [--number N] [--timestamp] <feature_description>"
+            echo "Usage: $0 [--json] [--dry-run] [--allow-existing-branch] [--short-name <name>] [--number N] [--timestamp] [--repos <paths>] [--scan-depth N] <feature_description>"
             echo ""
             echo "Options:"
             echo "  --json              Output in JSON format"
@@ -62,12 +90,15 @@ while [ $i -le $# ]; do
             echo "  --short-name <name> Provide a custom short name (2-4 words) for the branch"
             echo "  --number N          Specify branch number manually (overrides auto-detection)"
             echo "  --timestamp         Use timestamp prefix (YYYYMMDD-HHMMSS) instead of sequential numbering"
+            echo "  --repos <paths>     Comma-separated list of nested repo relative paths to branch (default: all discovered)"
+            echo "  --scan-depth N      Max directory depth to scan for nested repos (default: 2)"
             echo "  --help, -h          Show this help message"
             echo ""
             echo "Examples:"
             echo "  $0 'Add user authentication system' --short-name 'user-auth'"
             echo "  $0 'Implement OAuth2 integration for API' --number 5"
             echo "  $0 --timestamp --short-name 'user-auth' 'Add user authentication'"
+            echo "  $0 --repos 'components/api,components/auth' 'Add API auth support'"
             exit 0
             ;;
         *)
@@ -371,7 +402,31 @@ 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")
+    scan_depth="${SCAN_DEPTH:-2}"
+    nested_repos=$(find_nested_git_repos "$REPO_ROOT" "$scan_depth")
+
+    # Filter by --repos if specified: only branch repos in the requested list
+    if [ -n "$NESTED_REPOS_FILTER" ] && [ -n "$nested_repos" ]; then
+        IFS=',' read -ra requested_repos <<< "$NESTED_REPOS_FILTER"
+        filtered=""
+        while IFS= read -r nested_path; do
+            [ -z "$nested_path" ] && continue
+            nested_path="${nested_path%/}"
+            rel_path="${nested_path#"$REPO_ROOT/"}"
+            rel_path="${rel_path%/}"
+            for req in "${requested_repos[@]}"; do
+                req="$(echo "$req" | xargs)"
+                req="${req%/}"
+                if [ "$rel_path" = "$req" ]; then
+                    [ -n "$filtered" ] && filtered+=$'\n'
+                    filtered+="$nested_path"
+                    break
+                fi
+            done
+        done <<< "$nested_repos"
+        nested_repos="$filtered"
+    fi
+
     if [ -n "$nested_repos" ]; then
         NESTED_REPOS_JSON="["
         first=true
diff --git a/scripts/powershell/common.ps1 b/scripts/powershell/common.ps1
@@ -205,48 +205,38 @@ function Test-DirHasFiles {
 # itself and common non-project directories.
 # Returns an array of absolute paths.
 function Find-NestedGitRepos {
-    param([string]$RepoRoot = (Get-RepoRoot))
+    param(
+        [string]$RepoRoot = (Get-RepoRoot),
+        [int]$MaxDepth = 2
+    )
 
     $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 { }
-                }
+    function ScanDir {
+        param([string]$Dir, [int]$CurrentDepth)
+        $found = @()
+        $children = Get-ChildItem -Path $Dir -Directory -ErrorAction SilentlyContinue |
+            Where-Object { $skipDirs -notcontains $_.Name }
+
+        foreach ($child in $children) {
+            $gitMarker = Join-Path $child.FullName '.git'
+            if (Test-Path -LiteralPath $gitMarker) {
+                try {
+                    $null = git -C $child.FullName rev-parse --is-inside-work-tree 2>$null
+                    if ($LASTEXITCODE -eq 0) {
+                        $found += $child.FullName
+                    }
+                } catch { }
+            } elseif ($CurrentDepth -lt $MaxDepth) {
+                $found += ScanDir -Dir $child.FullName -CurrentDepth ($CurrentDepth + 1)
             }
         }
+        return $found
     }
 
-    return $results
+    return ScanDir -Dir $RepoRoot -CurrentDepth 1
 }
 
 # Resolve a template name to a file path using the priority stack:
diff --git a/scripts/powershell/create-new-feature.ps1 b/scripts/powershell/create-new-feature.ps1
@@ -9,6 +9,8 @@ param(
     [Parameter()]
     [long]$Number = 0,
     [switch]$Timestamp,
+    [string]$Repos,
+    [int]$ScanDepth = 0,
     [switch]$Help,
     [Parameter(Position = 0, ValueFromRemainingArguments = $true)]
     [string[]]$FeatureDescription
@@ -17,7 +19,7 @@ $ErrorActionPreference = 'Stop'
 
 # Show help if requested
 if ($Help) {
-    Write-Host "Usage: ./create-new-feature.ps1 [-Json] [-DryRun] [-AllowExistingBranch] [-ShortName <name>] [-Number N] [-Timestamp] <feature description>"
+    Write-Host "Usage: ./create-new-feature.ps1 [-Json] [-DryRun] [-AllowExistingBranch] [-ShortName <name>] [-Number N] [-Timestamp] [-Repos <paths>] [-ScanDepth N] <feature description>"
     Write-Host ""
     Write-Host "Options:"
     Write-Host "  -Json               Output in JSON format"
@@ -26,12 +28,15 @@ if ($Help) {
     Write-Host "  -ShortName <name>   Provide a custom short name (2-4 words) for the branch"
     Write-Host "  -Number N           Specify branch number manually (overrides auto-detection)"
     Write-Host "  -Timestamp          Use timestamp prefix (YYYYMMDD-HHMMSS) instead of sequential numbering"
+    Write-Host "  -Repos <paths>      Comma-separated list of nested repo relative paths to branch (default: all discovered)"
+    Write-Host "  -ScanDepth N        Max directory depth to scan for nested repos (default: 2)"
     Write-Host "  -Help               Show this help message"
     Write-Host ""
     Write-Host "Examples:"
     Write-Host "  ./create-new-feature.ps1 'Add user authentication system' -ShortName 'user-auth'"
     Write-Host "  ./create-new-feature.ps1 'Implement OAuth2 integration for API'"
     Write-Host "  ./create-new-feature.ps1 -Timestamp -ShortName 'user-auth' 'Add user authentication'"
+    Write-Host "  ./create-new-feature.ps1 -Repos 'components/api,components/auth' 'Add API auth support'"
     exit 0
 }
 
@@ -347,7 +352,18 @@ if (-not $DryRun) {
 # Create matching feature branches in nested independent git repositories
 $nestedReposResult = @()
 if ($hasGit) {
-    $nestedRepos = Find-NestedGitRepos -RepoRoot $repoRoot
+    $effectiveDepth = if ($ScanDepth -gt 0) { $ScanDepth } else { 2 }
+    $nestedRepos = Find-NestedGitRepos -RepoRoot $repoRoot -MaxDepth $effectiveDepth
+
+    # Filter by -Repos if specified: only branch repos in the requested list
+    if ($Repos) {
+        $requestedRepos = $Repos -split ',' | ForEach-Object { $_.Trim().TrimEnd('\', '/') } | Where-Object { $_ -ne '' }
+        $nestedRepos = $nestedRepos | Where-Object {
+            $relPath = $_.Substring($repoRoot.Length).TrimStart('\', '/')
+            $requestedRepos -contains $relPath
+        }
+    }
+
     foreach ($nestedPath in $nestedRepos) {
         $relPath = $nestedPath.Substring($repoRoot.Length).TrimStart('\', '/')
         $nestedStatus = 'skipped'
diff --git a/templates/commands/specify.md b/templates/commands/specify.md
@@ -79,10 +79,17 @@ Given that feature description, do this:
    - If `"timestamp"`, add `--timestamp` (Bash) or `-Timestamp` (PowerShell) to the script invocation
    - If `"sequential"` or absent, do not add any extra flag (default behavior)
 
+   **Nested repo configuration**: Check `.specify/init-options.json` for nested repository settings:
+   - `nested_repo_scan_depth` (integer): Max depth to scan for nested git repos (default: 2). Pass via `--scan-depth` (Bash) or `-ScanDepth` (PowerShell)
+   - `nested_repos` (array of strings): If present, lists the relative paths of known nested repos. Use this to determine which repos are relevant to the feature being created
+
+   **Selective branching**: Analyze the feature description to determine which nested repos (if any) are relevant. Pass only relevant repos via `--repos` (Bash) or `-Repos` (PowerShell) as a comma-separated list. If the feature affects all repos, omit the flag to branch all discovered repos.
+
    - Bash example: `{SCRIPT} --json --short-name "user-auth" "Add user authentication"`
-   - Bash (timestamp): `{SCRIPT} --json --timestamp --short-name "user-auth" "Add user authentication"`
+   - Bash (selective repos): `{SCRIPT} --json --repos "components/auth,components/core" --short-name "user-auth" "Add user authentication"`
+   - Bash (custom depth): `{SCRIPT} --json --scan-depth 3 --short-name "user-auth" "Add user authentication"`
    - PowerShell example: `{SCRIPT} -Json -ShortName "user-auth" "Add user authentication"`
-   - PowerShell (timestamp): `{SCRIPT} -Json -Timestamp -ShortName "user-auth" "Add user authentication"`
+   - PowerShell (selective repos): `{SCRIPT} -Json -Repos "components/auth,components/core" -ShortName "user-auth" "Add user authentication"`
 
    **IMPORTANT**:
    - Do NOT pass `--number` — the script determines the correct next number automatically
@@ -91,7 +98,7 @@ Given that feature description, do this:
    - 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, 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.
+   - **Nested git repos**: The script auto-detects subdirectories with their own `.git` (configurable depth via `--scan-depth`, default 2). Use `--repos` to branch only specific repos relevant to the feature. 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
