docs & tests maintenance: polish submodule flag docs, async helper, tidy tests

* **CLI**

  * Add example using `--include-submodules` in help text
  * Shorten `include_submodules` param description in `_async_main`
  * Re-order args in `ingest_async` call for readability

* **Clone**

  * Convert `_checkout_partial_clone` to **async** and update docstring accordingly

* **Schemas / Entrypoint**

  * Tighten wording in docstrings for `include_submodules`

* **Tests**

  * Drop redundant `test_cli` case for options mix
  * Rename `test_clone_commit_without_branch` → `test_clone_commit`
  * Strengthen `test_clone_with_include_submodules` assertions

Author: filipchristiansen

src/gitingest/cli.py

@@ -101,6 +101,9 @@ def main(**cli_kwargs: Unpack[_CLIArgs]) -> None:
         $ gitingest https://github.com/user/private-repo -t ghp_token
         $ GITHUB_TOKEN=ghp_token gitingest https://github.com/user/private-repo
 
+    Include submodules:
+        $ gitingest https://github.com/user/repo --include-submodules
+
     """
     asyncio.run(_async_main(**cli_kwargs))
 
@@ -138,8 +141,7 @@ async def _async_main(
     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``).
+        If ``True``, recursively include 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.
@@ -166,15 +168,15 @@ async def _async_main(
             click.echo(f"Analyzing source, output will be written to '{output_target}'...", err=True)
 
         summary, _, _ = await ingest_async(
-            source=source,
+            source,
             max_file_size=max_size,
             include_patterns=include_patterns,
             exclude_patterns=exclude_patterns,
             branch=branch,
-            include_submodules=include_submodules,
-            output=output_target,
             include_gitignored=include_gitignored,
+            include_submodules=include_submodules,
             token=token,
+            output=output_target,
         )
     except Exception as exc:
         # Convert any exception into Click.Abort so that exit status is non-zero

src/gitingest/clone.py

@@ -49,7 +49,6 @@ 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)
@@ -64,7 +63,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"]
-    if include_submodules:
+
+    if config.include_submodules:
         clone_cmd += ["--recurse-submodules"]
 
     if partial_clone:
@@ -96,28 +96,20 @@ async def clone_repo(config: CloneConfig, *, token: str | None = None) -> None:
         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.
+async def _checkout_partial_clone(config: CloneConfig, token: str | None) -> None:
+    """Configure sparse-checkout for a partially cloned repository.
 
     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.
+        # Remove the file name from the subpath when ingesting from a file url (e.g. blob/branch/path/file.txt)
         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)
+    await run_command(*checkout_cmd, "sparse-checkout", "set", subpath)

src/gitingest/entrypoint.py

@@ -54,7 +54,7 @@ async def ingest_async(
     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``).
+        If ``True``, recursively include 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.
@@ -133,7 +133,7 @@ def ingest(
     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``).
+        If ``True``, recursively include 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.

src/gitingest/schemas/ingestion.py

@@ -11,7 +11,7 @@
 
 
 @dataclass
-class CloneConfig:  # pylint: disable=too-many-instance-attributes, too-many-arguments
+class CloneConfig:  # pylint: disable=too-many-instance-attributes
     """Configuration for cloning a Git repository.
 
     This class holds the necessary parameters for cloning a repository to a local path, including
@@ -82,7 +82,7 @@ class IngestionQuery(BaseModel):  # pylint: disable=too-many-instance-attributes
     include_patterns : set[str] | None
         The patterns to include.
     include_submodules : bool
-        The flag whether to include Git submodules in the analysis. (default: ``False``)
+        Whether to include all Git submodules within the repository. (default: ``False``)
 
     """
 

tests/test_cli.py

@@ -27,19 +27,10 @@
                 "tests/",
                 "--include-pattern",
                 "src/",
-            ],
-            True,
-            id="custom-options",
-        ),
-        pytest.param(
-            [
-                "./",
-                "--output",
-                str(OUTPUT_FILE_NAME),
                 "--include-submodules",
             ],
             True,
-            id="with-include-submodules",
+            id="custom-options",
         ),
     ],
 )

tests/test_clone.py

@@ -181,10 +181,10 @@ async def test_clone_default_shallow_clone(run_command_mock: AsyncMock) -> None:
 
 
 @pytest.mark.asyncio
-async def test_clone_commit_without_branch(run_command_mock: AsyncMock) -> None:
-    """Test cloning when a commit hash is provided but no branch is specified.
+async def test_clone_commit(run_command_mock: AsyncMock) -> None:
+    """Test cloning when a commit hash is provided.
 
-    Given a valid URL and a commit hash (but no branch):
+    Given a valid URL and a commit hash:
     When ``clone_repo`` is called,
     Then the repository should be cloned and checked out at that commit.
     """
@@ -420,19 +420,22 @@ async def test_clone_with_commit_and_subpath(run_command_mock: AsyncMock) -> Non
 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.
+    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.
     """
+    expected_call_count = 1  # No commit and no partial clone
     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"
+    assert run_command_mock.call_count == expected_call_count
+    run_command_mock.assert_called_once_with(
+        "git",
+        "clone",
+        "--single-branch",
+        "--recurse-submodules",
+        "--depth=1",
+        clone_config.url,
+        clone_config.local_path,
+    )