feat: hybrid nested repo discovery explicit config + .gitignore fallback

Replace hardcoded skip list with two-tier discovery:

1. Explicit paths: If nested_repos is defined in init-options.json,
   validate and return those paths directly (no scanning).

2. .gitignore-based scan: If no explicit config, scan directories but
   use git check-ignore to skip gitignored dirs instead of a hardcoded
   skip list. Only .git is hardcoded. Dirs with their own .git are
   always treated as nested repos (even if gitignored in parent).

- Bash: find_nested_git_repos() accepts optional explicit paths (3rd+ args)
- PowerShell: Find-NestedGitRepos accepts -ExplicitPaths param
- setup-plan.sh/.ps1: reads nested_repos from init-options.json
- Python fallback for JSON parsing when jq is unavailable
- Windows \r line-ending handling in Python subprocess output
- 18 tests: discovery, gitignore filtering, explicit paths, depth, init-options

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: sakitA

scripts/bash/common.sh

@@ -282,29 +282,36 @@ check_dir() { [[ -d "$1" && -n $(ls -A "$1" 2>/dev/null) ]] && echo "  ✓ $2" |
 # 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
+# Usage: find_nested_git_repos [repo_root] [max_depth] [explicit_paths...]
+#   repo_root       — defaults to $(get_repo_root)
+#   max_depth       — defaults to 2
+#   explicit_paths  — if provided (3rd arg onward), validate and return these directly (no scanning)
 # 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"
-                        ".vscode" "specs")
 
+    # Collect explicit paths from 3rd argument onward
+    local -a explicit_paths=()
+    if [ $# -ge 3 ]; then
+        shift 2
+        explicit_paths=("$@")
+    fi
+
+    # If explicit paths are provided, validate and return them directly
+    if [ ${#explicit_paths[@]} -gt 0 ]; then
+        for rel_path in "${explicit_paths[@]}"; do
+            local abs_path="$repo_root/$rel_path"
+            if [ -e "$abs_path/.git" ] && git -C "$abs_path" rev-parse --is-inside-work-tree >/dev/null 2>&1; then
+                echo "$abs_path"
+            fi
+        done
+        return
+    fi
+
+    # Fallback: scan using .gitignore-based filtering
     # Run in a subshell to avoid leaking helper functions into global scope
     (
-        _should_skip() {
-            local name="$1"
-            local skip
-            for skip in "${skip_dirs[@]}"; do
-                [ "$name" = "$skip" ] && return 0
-            done
-            return 1
-        }
-
         _scan_dir() {
             local dir="$1"
             local current_depth="$2"
@@ -314,13 +321,19 @@ find_nested_git_repos() {
                 [ -d "$child" ] || continue
                 child="${child%/}"
                 child_name="$(basename "$child")"
-                _should_skip "$child_name" && continue
+                # Always skip .git directory
+                [ "$child_name" = ".git" ] && continue
 
                 if [ -e "$child/.git" ]; then
+                    # Directory has its own .git — it's a nested repo (even if gitignored in parent)
                     if git -C "$child" rev-parse --is-inside-work-tree >/dev/null 2>&1; then
                         echo "$child"
                     fi
                 elif [ "$current_depth" -lt "$max_depth" ]; then
+                    # Skip gitignored directories (they won't contain nested repos)
+                    if git -C "$repo_root" check-ignore -q "$child" 2>/dev/null; then
+                        continue
+                    fi
                     _scan_dir "$child" $((current_depth + 1))
                 fi
             done

scripts/bash/setup-plan.sh

@@ -76,7 +76,34 @@ fi
 NESTED_REPOS_JSON="[]"
 if [ "$HAS_GIT" = true ]; then
     scan_depth="${SCAN_DEPTH:-2}"
-    nested_repos=$(find_nested_git_repos "$REPO_ROOT" "$scan_depth")
+    INIT_OPTIONS="$REPO_ROOT/.specify/init-options.json"
+    explicit_repos=()
+
+    # Read explicit nested_repos from init-options.json if available
+    if [ -f "$INIT_OPTIONS" ]; then
+        if has_jq; then
+            while IFS= read -r rp; do
+                [ -n "$rp" ] && explicit_repos+=("$rp")
+            done < <(jq -r '.nested_repos // [] | .[]' "$INIT_OPTIONS" 2>/dev/null)
+        else
+            _py=$(command -v python3 2>/dev/null || command -v python 2>/dev/null || echo "")
+            if [ -n "$_py" ]; then
+                while IFS= read -r rp; do
+                    rp="${rp%$'\r'}"
+                    [ -n "$rp" ] && explicit_repos+=("$rp")
+                done < <("$_py" -c "import json,sys
+try:
+ [print(p) for p in json.load(open(sys.argv[1])).get('nested_repos',[])]
+except: pass" "$INIT_OPTIONS" 2>/dev/null)
+            fi
+        fi
+    fi
+
+    if [ ${#explicit_repos[@]} -gt 0 ]; then
+        nested_repos=$(find_nested_git_repos "$REPO_ROOT" "$scan_depth" "${explicit_repos[@]}")
+    else
+        nested_repos=$(find_nested_git_repos "$REPO_ROOT" "$scan_depth")
+    fi
     if [ -n "$nested_repos" ]; then
         NESTED_REPOS_JSON="["
         first=true

scripts/powershell/common.ps1

@@ -233,32 +233,53 @@ function Test-DirHasFiles {
 # (directory or file, covering worktrees/submodules). Excludes the root repo
 # itself and common non-project directories.
 # Returns an array of absolute paths. Scan depth is configurable (default 2).
+# If ExplicitPaths are provided, validates and returns those directly (no scanning).
 function Find-NestedGitRepos {
     param(
         [string]$RepoRoot = (Get-RepoRoot),
-        [int]$MaxDepth = 2
+        [int]$MaxDepth = 2,
+        [string[]]$ExplicitPaths = @()
     )
 
-    $skipDirs = @('.specify', '.git', 'node_modules', 'vendor', '.venv', 'venv',
-                  '__pycache__', '.gradle', 'build', 'dist', 'target', '.idea',
-                  '.vscode', 'specs')
+    # If explicit paths are provided, validate and return them directly
+    if ($ExplicitPaths.Count -gt 0) {
+        $found = @()
+        foreach ($relPath in $ExplicitPaths) {
+            $absPath = Join-Path $RepoRoot $relPath
+            $gitMarker = Join-Path $absPath '.git'
+            if (Test-Path -LiteralPath $gitMarker) {
+                try {
+                    $null = git -C $absPath rev-parse --is-inside-work-tree 2>$null
+                    if ($LASTEXITCODE -eq 0) {
+                        $found += $absPath
+                    }
+                } catch { }
+            }
+        }
+        return $found
+    }
 
+    # Fallback: scan using .gitignore-based filtering
     function ScanDir {
         param([string]$Dir, [int]$CurrentDepth)
         $found = @()
         $children = Get-ChildItem -Path $Dir -Directory -ErrorAction SilentlyContinue |
-            Where-Object { $skipDirs -notcontains $_.Name }
+            Where-Object { $_.Name -ne '.git' }
 
         foreach ($child in $children) {
             $gitMarker = Join-Path $child.FullName '.git'
             if (Test-Path -LiteralPath $gitMarker) {
+                # Directory has its own .git — it's a nested repo (even if gitignored in parent)
                 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) {
+                # Skip gitignored directories (they won't contain nested repos)
+                $null = git -C $RepoRoot check-ignore -q $child.FullName 2>$null
+                if ($LASTEXITCODE -eq 0) { continue }
                 $found += ScanDir -Dir $child.FullName -CurrentDepth ($CurrentDepth + 1)
             }
         }

scripts/powershell/setup-plan.ps1

@@ -48,7 +48,24 @@ if ($template -and (Test-Path $template)) {
 $nestedReposResult = @()
 if ($paths.HAS_GIT -eq 'true' -or $paths.HAS_GIT -eq $true) {
     $effectiveDepth = if ($ScanDepth -gt 0) { $ScanDepth } else { 2 }
-    $nestedRepos = Find-NestedGitRepos -RepoRoot $paths.REPO_ROOT -MaxDepth $effectiveDepth
+    $initOptions = Join-Path $paths.REPO_ROOT '.specify' 'init-options.json'
+    $explicitPaths = @()
+
+    # Read explicit nested_repos from init-options.json if available
+    if (Test-Path -LiteralPath $initOptions) {
+        try {
+            $opts = Get-Content $initOptions -Raw | ConvertFrom-Json
+            if ($opts.nested_repos -and $opts.nested_repos.Count -gt 0) {
+                $explicitPaths = @($opts.nested_repos)
+            }
+        } catch { }
+    }
+
+    if ($explicitPaths.Count -gt 0) {
+        $nestedRepos = Find-NestedGitRepos -RepoRoot $paths.REPO_ROOT -MaxDepth $effectiveDepth -ExplicitPaths $explicitPaths
+    } else {
+        $nestedRepos = Find-NestedGitRepos -RepoRoot $paths.REPO_ROOT -MaxDepth $effectiveDepth
+    }
     foreach ($nestedPath in $nestedRepos) {
         $relPath = $nestedPath.Substring($paths.REPO_ROOT.Length).TrimStart('\', '/')
         $nestedReposResult += [PSCustomObject]@{ path = $relPath }

tests/test_nested_repos.py

@@ -4,7 +4,8 @@
 Tests cover:
 - Discovery of nested git repos via find_nested_git_repos (bash)
 - Configurable scan depth for discovery
-- Excluded directories are skipped
+- .gitignore-based directory filtering (replaces hardcoded skip list)
+- Explicit paths from init-options.json
 - setup-plan.sh reports discovered nested repos in JSON output
 - create-new-feature.sh does NOT create branches in nested repos
 """
@@ -88,17 +89,21 @@ def git_repo_no_nested(tmp_path: Path) -> Path:
 
 
 @pytest.fixture
-def git_repo_with_excluded_dirs(tmp_path: Path) -> Path:
-    """Create a root git repo where git repos exist inside excluded directories."""
+def git_repo_with_gitignored_dirs(tmp_path: Path) -> Path:
+    """Create a root git repo with gitignored dirs containing git repos."""
     _init_git_repo(tmp_path)
     _setup_scripts(tmp_path)
 
-    # Git repo inside node_modules (should be excluded)
+    # Add .gitignore that ignores node_modules and build
+    (tmp_path / ".gitignore").write_text("node_modules/\nbuild/\n")
+    subprocess.run(["git", "add", ".gitignore"], cwd=tmp_path, check=True)
+    subprocess.run(["git", "commit", "-m", "add gitignore", "-q"], cwd=tmp_path, check=True)
+
+    # Non-repo dir inside gitignored path (should be skipped during traversal)
     nm_dir = tmp_path / "node_modules" / "some-pkg"
     nm_dir.mkdir(parents=True)
-    _init_git_repo(nm_dir)
 
-    # Valid nested repo
+    # Valid nested repo (not gitignored)
     lib_dir = tmp_path / "lib"
     lib_dir.mkdir(parents=True)
     _init_git_repo(lib_dir)
@@ -160,11 +165,11 @@ def test_no_nested_repos_returns_empty(self, git_repo_no_nested: Path):
         assert result.returncode == 0
         assert result.stdout.strip() == ""
 
-    def test_excludes_node_modules(self, git_repo_with_excluded_dirs: Path):
-        """find_nested_git_repos skips repos inside excluded directories."""
+    def test_skips_gitignored_directories(self, git_repo_with_gitignored_dirs: Path):
+        """find_nested_git_repos skips traversal into gitignored directories."""
         result = source_and_call(
-            f'find_nested_git_repos "{git_repo_with_excluded_dirs}"',
-            cwd=git_repo_with_excluded_dirs,
+            f'find_nested_git_repos "{git_repo_with_gitignored_dirs}"',
+            cwd=git_repo_with_gitignored_dirs,
         )
         assert result.returncode == 0
         paths = [p.strip().rstrip("/") for p in result.stdout.strip().splitlines() if p.strip()]
@@ -192,6 +197,67 @@ def test_discovers_level1_repos(self, tmp_path: Path):
         assert len(paths) == 1
         assert os.path.basename(paths[0]) == "mylib"
 
+    def test_nested_repo_found_even_if_gitignored(self, tmp_path: Path):
+        """A directory with its own .git is reported even if it's gitignored in the parent."""
+        _init_git_repo(tmp_path)
+        (tmp_path / ".specify").mkdir()
+
+        # Gitignore the nested repo path
+        (tmp_path / ".gitignore").write_text("nested-lib/\n")
+        subprocess.run(["git", "add", ".gitignore"], cwd=tmp_path, check=True)
+        subprocess.run(["git", "commit", "-m", "ignore", "-q"], cwd=tmp_path, check=True)
+
+        # Create nested repo at the gitignored path
+        nested = tmp_path / "nested-lib"
+        nested.mkdir()
+        _init_git_repo(nested)
+
+        result = source_and_call(
+            f'find_nested_git_repos "{tmp_path}"',
+            cwd=tmp_path,
+        )
+        assert result.returncode == 0
+        paths = [p.strip().rstrip("/") for p in result.stdout.strip().splitlines() if p.strip()]
+        assert len(paths) == 1
+        assert os.path.basename(paths[0]) == "nested-lib"
+
+
+# ── Explicit Paths Tests ─────────────────────────────────────────────────────
+
+
+class TestExplicitPaths:
+    def test_explicit_paths_returns_only_valid(self, git_repo_with_nested: Path):
+        """When explicit paths are given, only valid nested repos are returned."""
+        result = source_and_call(
+            f'find_nested_git_repos "{git_repo_with_nested}" 2 "components/core" "nonexistent/repo"',
+            cwd=git_repo_with_nested,
+        )
+        assert result.returncode == 0, result.stderr
+        paths = [p.strip().rstrip("/") for p in result.stdout.strip().splitlines() if p.strip()]
+        assert len(paths) == 1
+        assert os.path.basename(paths[0]) == "core"
+
+    def test_explicit_paths_skips_scanning(self, git_repo_with_nested: Path):
+        """When explicit paths are given, only those are checked — no scanning."""
+        result = source_and_call(
+            f'find_nested_git_repos "{git_repo_with_nested}" 2 "components/core"',
+            cwd=git_repo_with_nested,
+        )
+        assert result.returncode == 0, result.stderr
+        paths = [p.strip().rstrip("/") for p in result.stdout.strip().splitlines() if p.strip()]
+        # Only core should be returned, not api (even though it exists)
+        assert len(paths) == 1
+        assert os.path.basename(paths[0]) == "core"
+
+    def test_explicit_empty_returns_nothing(self, git_repo_with_nested: Path):
+        """When explicit paths are all invalid, nothing is returned."""
+        result = source_and_call(
+            f'find_nested_git_repos "{git_repo_with_nested}" 2 "does/not/exist"',
+            cwd=git_repo_with_nested,
+        )
+        assert result.returncode == 0
+        assert result.stdout.strip() == ""
+
 
 # ── Configurable Depth Tests ─────────────────────────────────────────────────
 
@@ -355,3 +421,19 @@ def test_discovery_does_not_create_branches(self, git_repo_with_nested: Path):
                 capture_output=True, text=True,
             )
             assert br.stdout.strip() != branch_name
+
+    def test_explicit_nested_repos_from_init_options(self, git_repo_with_nested: Path):
+        """setup-plan reads nested_repos from init-options.json and uses explicit paths."""
+        self._create_feature_first(git_repo_with_nested)
+
+        # Write init-options.json with explicit nested_repos (only core, not api)
+        init_options = git_repo_with_nested / ".specify" / "init-options.json"
+        init_options.write_text(json.dumps({"nested_repos": ["components/core"]}))
+
+        result = run_setup_plan(git_repo_with_nested, "--json")
+        assert result.returncode == 0, result.stderr
+        data = parse_json_from_output(result.stdout)
+
+        assert "NESTED_REPOS" in data
+        assert len(data["NESTED_REPOS"]) == 1
+        assert data["NESTED_REPOS"][0]["path"] == "components/core"