feat: add optional --include-submodules flag to CLI and ingestion

- Adds --include-submodules CLI flag to control submodule analysis
- Propagates include_submodules through ingestion, schemas, and clone logic
- Updates tests to cover submodule inclusion
- Adds a helper function (_checkout_partial_clone) to avoid repetition
- Web UI for this option is not implemented for now (#313 (comment))

Author: jpotw

src/gitingest/cli.py

@@ -20,6 +20,7 @@ class _CLIArgs(TypedDict):
     include_pattern: tuple[str, ...]
     branch: str | None
     include_gitignored: bool
+    include_submodules: bool
     token: str | None
     output: str | None
 
@@ -47,6 +48,12 @@ class _CLIArgs(TypedDict):
     default=False,
     help="Include files matched by .gitignore and .gitingestignore",
 )
+@click.option(
+    "--include-submodules",
+    is_flag=True,
+    help="Include repository's submodules in the analysis",
+    default=False,
+)
 @click.option(
     "--token",
     "-t",
@@ -106,6 +113,7 @@ async def _async_main(
     include_pattern: tuple[str, ...] | None = None,
     branch: str | None = None,
     include_gitignored: bool = False,
+    include_submodules: bool = False,
     token: str | None = None,
     output: str | None = None,
 ) -> None:
@@ -129,6 +137,9 @@ async def _async_main(
         Git branch to ingest. If ``None``, the repository's default branch is used.
     include_gitignored : bool
         If ``True``, also ingest files matched by ``.gitignore`` or ``.gitingestignore`` (default: ``False``).
+    include_submodules : bool
+        If ``True``, recursively include and analyze all Git submodules within the repository.
+        Set to ``False`` to ignore submodules during analysis (default is ``False``).
     token : str | None
         GitHub personal access token (PAT) for accessing private repositories.
         Can also be set via the ``GITHUB_TOKEN`` environment variable.
@@ -160,6 +171,7 @@ async def _async_main(
             include_patterns=include_patterns,
             exclude_patterns=exclude_patterns,
             branch=branch,
+            include_submodules=include_submodules,
             output=output_target,
             include_gitignored=include_gitignored,
             token=token,

src/gitingest/clone.py

@@ -49,6 +49,7 @@ async def clone_repo(config: CloneConfig, *, token: str | None = None) -> None:
     branch: str | None = config.branch
     tag: str | None = config.tag
     partial_clone: bool = config.subpath != "/"
+    include_submodules: bool = config.include_submodules
 
     # Create parent directory if it doesn't exist
     await ensure_directory(Path(local_path).parent)
@@ -63,7 +64,8 @@ async def clone_repo(config: CloneConfig, *, token: str | None = None) -> None:
         clone_cmd += ["-c", create_git_auth_header(token, url=url)]
 
     clone_cmd += ["clone", "--single-branch"]
-    # TODO: Re-enable --recurse-submodules when submodule support is needed
+    if include_submodules:
+        clone_cmd += ["--recurse-submodules"]
 
     if partial_clone:
         clone_cmd += ["--filter=blob:none", "--sparse"]
@@ -86,15 +88,36 @@ async def clone_repo(config: CloneConfig, *, token: str | None = None) -> None:
 
     # Checkout the subpath if it is a partial clone
     if partial_clone:
-        subpath = config.subpath.lstrip("/")
-        if config.blob:
-            # When ingesting from a file url (blob/branch/path/file.txt), we need to remove the file name.
-            subpath = str(Path(subpath).parent.as_posix())
-
-        checkout_cmd = create_git_command(["git"], local_path, url, token)
-        await run_command(*checkout_cmd, "sparse-checkout", "set", subpath)
+        await _checkout_partial_clone(config, token)
 
     # Checkout the commit if it is provided
     if commit:
         checkout_cmd = create_git_command(["git"], local_path, url, token)
         await run_command(*checkout_cmd, "checkout", commit)
+
+
+def _checkout_partial_clone(config: CloneConfig, token: str | None) -> None:
+    """Handle sparse-checkout for partial clones.
+
+    This helper function sets the sparse-checkout configuration for a partial clone,
+    optionally adjusting the subpath if ingesting from a file URL.
+
+    Parameters
+    ----------
+    config : CloneConfig
+        The configuration for cloning the repository, including subpath and blob flag.
+    token : str | None
+        GitHub personal access token (PAT) for accessing private repositories.
+        Can also be set via the ``GITHUB_TOKEN`` environment variable.
+
+    Returns
+    -------
+    None
+
+    """
+    subpath = config.subpath.lstrip("/")
+    if config.blob:
+        # When ingesting from a file url (blob/branch/path/file.txt), we need to remove the file name.
+        subpath = str(Path(subpath).parent.as_posix())
+    checkout_cmd = create_git_command(["git"], config.local_path, config.url, token)
+    return run_command(*checkout_cmd, "sparse-checkout", "set", subpath)

src/gitingest/entrypoint.py

@@ -27,6 +27,7 @@ async def ingest_async(
     branch: str | None = None,
     tag: str | None = None,
     include_gitignored: bool = False,
+    include_submodules: bool = False,
     token: str | None = None,
     output: str | None = None,
 ) -> tuple[str, str, str]:
@@ -52,6 +53,8 @@ async def ingest_async(
         The tag to clone and ingest. If ``None``, no tag is used.
     include_gitignored : bool
         If ``True``, include files ignored by ``.gitignore`` and ``.gitingestignore`` (default: ``False``).
+    include_submodules : bool
+        If ``True``, recursively include and analyze all Git submodules within the repository (default: ``False``).
     token : str | None
         GitHub personal access token (PAT) for accessing private repositories.
         Can also be set via the ``GITHUB_TOKEN`` environment variable.
@@ -86,6 +89,8 @@ async def ingest_async(
     if query.url:
         _override_branch_and_tag(query, branch=branch, tag=tag)
 
+    query.include_submodules = include_submodules
+
     async with _clone_repo_if_remote(query, token=token):
         summary, tree, content = ingest_query(query)
         await _write_output(tree, content=content, target=output)
@@ -101,6 +106,7 @@ def ingest(
     branch: str | None = None,
     tag: str | None = None,
     include_gitignored: bool = False,
+    include_submodules: bool = False,
     token: str | None = None,
     output: str | None = None,
 ) -> tuple[str, str, str]:
@@ -126,6 +132,8 @@ def ingest(
         The tag to clone and ingest. If ``None``, no tag is used.
     include_gitignored : bool
         If ``True``, include files ignored by ``.gitignore`` and ``.gitingestignore`` (default: ``False``).
+    include_submodules : bool
+        If ``True``, recursively include and analyze all Git submodules within the repository (default: ``False``).
     token : str | None
         GitHub personal access token (PAT) for accessing private repositories.
         Can also be set via the ``GITHUB_TOKEN`` environment variable.
@@ -156,6 +164,7 @@ def ingest(
             branch=branch,
             tag=tag,
             include_gitignored=include_gitignored,
+            include_submodules=include_submodules,
             token=token,
             output=output,
         ),

src/gitingest/schemas/ingestion.py

@@ -11,7 +11,7 @@
 
 
 @dataclass
-class CloneConfig:
+class CloneConfig:  # pylint: disable=too-many-instance-attributes, too-many-arguments
     """Configuration for cloning a Git repository.
 
     This class holds the necessary parameters for cloning a repository to a local path, including
@@ -33,6 +33,8 @@ class CloneConfig:
         The subpath to clone from the repository (default: ``"/"``).
     blob: bool
         Whether the repository is a blob (default: ``False``).
+    include_submodules: bool
+        Whether to clone submodules (default: ``False``).
 
     """
 
@@ -43,6 +45,7 @@ class CloneConfig:
     tag: str | None = None
     subpath: str = "/"
     blob: bool = False
+    include_submodules: bool = False
 
 
 class IngestionQuery(BaseModel):  # pylint: disable=too-many-instance-attributes
@@ -78,6 +81,8 @@ class IngestionQuery(BaseModel):  # pylint: disable=too-many-instance-attributes
         The patterns to ignore (default: ``set()``).
     include_patterns : set[str] | None
         The patterns to include.
+    include_submodules : bool
+        The flag whether to include Git submodules in the analysis. (default: ``False``)
 
     """
 
@@ -95,6 +100,7 @@ class IngestionQuery(BaseModel):  # pylint: disable=too-many-instance-attributes
     max_file_size: int = Field(default=MAX_FILE_SIZE)
     ignore_patterns: set[str] = set()  # TODO: ignore_patterns and include_patterns have the same type
     include_patterns: set[str] | None = None
+    include_submodules: bool = False
 
     def extract_clone_config(self) -> CloneConfig:
         """Extract the relevant fields for the CloneConfig object.
@@ -122,6 +128,7 @@ def extract_clone_config(self) -> CloneConfig:
             tag=self.tag,
             subpath=self.subpath,
             blob=self.type == "blob",
+            include_submodules=self.include_submodules,
         )
 
     def ensure_url(self) -> None:

tests/query_parser/test_git_host_agnostic.py

@@ -68,6 +68,7 @@ async def test_parse_query_without_host(
         "commit": None,
         "max_file_size": 50,
         "include_patterns": None,
+        "include_submodules": False,
     }
 
     assert actual == expected

tests/test_cli.py

@@ -31,6 +31,16 @@
             True,
             id="custom-options",
         ),
+        pytest.param(
+            [
+                "./",
+                "--output",
+                str(OUTPUT_FILE_NAME),
+                "--include-submodules",
+            ],
+            True,
+            id="with-include-submodules",
+        ),
     ],
 )
 def test_cli_writes_file(

tests/test_clone.py

@@ -414,3 +414,25 @@ async def test_clone_with_commit_and_subpath(run_command_mock: AsyncMock) -> Non
     )
 
     assert run_command_mock.call_count == expected_call_count
+
+
+@pytest.mark.asyncio
+async def test_clone_with_include_submodules(run_command_mock: AsyncMock) -> None:
+    """Test cloning a repository with submodules included.
+
+    Given a valid URL and include_submodules=True:
+    When `clone_repo` is called,
+    Then the repository should be cloned with --recurse-submodules in the git command.
+    """
+    clone_config = CloneConfig(url=DEMO_URL, local_path=LOCAL_REPO_PATH, branch="main", include_submodules=True)
+
+    await clone_repo(clone_config)
+
+    # Check that --recurse-submodules is in the clone command
+    found = False
+    for call in run_command_mock.call_args_list:
+        args = call[0]
+        if "clone" in args and "--recurse-submodules" in args:
+            found = True
+            break
+    assert found, "--recurse-submodules not found in git clone command when include_submodules=True"