fix: split sparse-checkout & commit checkout when cloning; refresh docs/CLI

* Run `git sparse-checkout set …` and `git checkout <sha>` as two calls—matches Git’s CLI rules and fixes failures.
* Tidy clone path creation via _ensure_directory; use DEFAULT_TIMEOUT.
* Clarify CLI/help strings and schema docstrings.
* Update tests for the new two-step checkout flow.

Author: filipchristiansen

src/gitingest/cli.py

@@ -29,17 +29,19 @@
     "--exclude-pattern",
     "-e",
     multiple=True,
-    help="""Patterns to exclude. Handles python's arbitrary subset of Unix
-    shell-style wildcards. See:
-    https://docs.python.org/3/library/fnmatch.html""",
+    help=(
+        "Patterns to exclude. Handles Python's arbitrary subset of Unix shell-style "
+        "wildcards. See: https://docs.python.org/3/library/fnmatch.html"
+    ),
 )
 @click.option(
     "--include-pattern",
     "-i",
     multiple=True,
-    help="""Patterns to include. Handles python's arbitrary subset of Unix
-    shell-style wildcards. See:
-    https://docs.python.org/3/library/fnmatch.html""",
+    help=(
+        "Patterns to include. Handles Python's arbitrary subset of Unix shell-style "
+        "wildcards. See: https://docs.python.org/3/library/fnmatch.html"
+    ),
 )
 @click.option("--branch", "-b", default=None, help="Branch to clone and ingest")
 def main(
@@ -58,21 +60,29 @@ def main(
     Parameters
     ----------
     source : str
-        The source directory or repository to analyze.
+        A directory path or a Git repository URL.
     output : str, optional
-        The path where the output file will be written. If not specified, the output will be written
-        to a file named `<repo_name>.txt` in the current directory.
+        Output file path. Defaults to `<repo_name>.txt`.
     max_size : int
-        The maximum file size to process, in bytes. Files larger than this size will be ignored.
+        Maximum file size (in bytes) to consider.
     exclude_pattern : Tuple[str, ...]
-        A tuple of patterns to exclude during the analysis. Files matching these patterns will be ignored.
+        Glob patterns for pruning the file set.
     include_pattern : Tuple[str, ...]
-        A tuple of patterns to include during the analysis. Only files matching these patterns will be processed.
+        Glob patterns for including files in the output.
     branch : str, optional
-        The branch to clone (optional).
+        Specific branch to ingest (defaults to the repository's default).
     """
-    # Main entry point for the CLI. This function is called when the CLI is run as a script.
-    asyncio.run(_async_main(source, output, max_size, exclude_pattern, include_pattern, branch))
+
+    asyncio.run(
+        _async_main(
+            source=source,
+            output=output,
+            max_size=max_size,
+            exclude_pattern=exclude_pattern,
+            include_pattern=include_pattern,
+            branch=branch,
+        )
+    )
 
 
 async def _async_main(
@@ -92,40 +102,49 @@ async def _async_main(
     Parameters
     ----------
     source : str
-        The source directory or repository to analyze.
+        A directory path or a Git repository URL.
     output : str, optional
-        The path where the output file will be written. If not specified, the output will be written
-        to a file named `<repo_name>.txt` in the current directory.
+        Output file path. Defaults to `<repo_name>.txt`.
     max_size : int
-        The maximum file size to process, in bytes. Files larger than this size will be ignored.
+        Maximum file size (in bytes) to consider.
     exclude_pattern : Tuple[str, ...]
-        A tuple of patterns to exclude during the analysis. Files matching these patterns will be ignored.
+        Glob patterns for pruning the file set.
     include_pattern : Tuple[str, ...]
-        A tuple of patterns to include during the analysis. Only files matching these patterns will be processed.
+        Glob patterns for including files in the output.
     branch : str, optional
-        The branch to clone (optional).
+        Specific branch to ingest (defaults to the repository's default).
 
     Raises
     ------
     Abort
         If there is an error during the execution of the command, this exception is raised to abort the process.
     """
     try:
-        # Combine default and custom ignore patterns
+        # Normalise pattern containers (the ingest layer expects sets)
         exclude_patterns = set(exclude_pattern)
         include_patterns = set(include_pattern)
 
-        if not output:
+        # Choose a default output path if none provided
+        if output is None:
             output = OUTPUT_FILE_NAME
-        summary, _, _ = await ingest_async(source, max_size, include_patterns, exclude_patterns, branch, output=output)
+
+        summary, _, _ = await ingest_async(
+            source=source,
+            max_file_size=max_size,
+            include_patterns=include_patterns,
+            exclude_patterns=exclude_patterns,
+            branch=branch,
+            output=output,
+        )
 
         click.echo(f"Analysis complete! Output written to: {output}")
         click.echo("\nSummary:")
         click.echo(summary)
 
     except Exception as exc:
+        # Convert any exception into Click.Abort so that exit status is non-zero
         click.echo(f"Error: {exc}", err=True)
-        raise click.Abort()
+        raise click.Abort() from exc
 
 
 if __name__ == "__main__":

src/gitingest/cloning.py

@@ -4,14 +4,13 @@
 from pathlib import Path
 from typing import Optional
 
+from gitingest.config import DEFAULT_TIMEOUT
 from gitingest.schemas import CloneConfig
 from gitingest.utils.git_utils import check_repo_exists, ensure_git_installed, run_command
 from gitingest.utils.timeout_wrapper import async_timeout
 
-TIMEOUT: int = 60
 
-
-@async_timeout(TIMEOUT)
+@async_timeout(DEFAULT_TIMEOUT)
 async def clone_repo(config: CloneConfig) -> None:
     """
     Clone a repository to a local path based on the provided configuration.
@@ -29,8 +28,6 @@ async def clone_repo(config: CloneConfig) -> None:
     ------
     ValueError
         If the repository is not found or if the provided URL is invalid.
-    OSError
-        If an error occurs while creating the parent directory for the repository.
     """
     # Extract and validate query parameters
     url: str = config.url
@@ -40,18 +37,14 @@ async def clone_repo(config: CloneConfig) -> None:
     partial_clone: bool = config.subpath != "/"
 
     # Create parent directory if it doesn't exist
-    parent_dir = Path(local_path).parent
-    try:
-        os.makedirs(parent_dir, exist_ok=True)
-    except OSError as exc:
-        raise OSError(f"Failed to create parent directory {parent_dir}: {exc}") from exc
+    await _ensure_directory(Path(local_path).parent)
 
     # Check if the repository exists
     if not await check_repo_exists(url):
         raise ValueError("Repository not found, make sure it is public")
 
     clone_cmd = ["git", "clone", "--single-branch"]
-    # TODO re-enable --recurse-submodules
+    # TODO: Re-enable --recurse-submodules when submodule support is needed
 
     if partial_clone:
         clone_cmd += ["--filter=blob:none", "--sparse"]
@@ -67,19 +60,35 @@ async def clone_repo(config: CloneConfig) -> None:
     await ensure_git_installed()
     await run_command(*clone_cmd)
 
-    if commit or partial_clone:
-        checkout_cmd = ["git", "-C", local_path]
+    # 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())
+
+        await run_command("git", "-C", local_path, "sparse-checkout", "set", subpath)
 
-        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 the commit if it is provided
+    if commit:
+        await run_command("git", "-C", local_path, "checkout", commit)
 
-            checkout_cmd += ["sparse-checkout", "set", subpath]
 
-        if commit:
-            checkout_cmd += ["checkout", commit]
+async def _ensure_directory(path: Path) -> None:
+    """
+    Ensure the directory exists, creating it if necessary.
+
+    Parameters
+    ----------
+    path : Path
+        The path to ensure exists
 
-        # Check out the specific commit and/or subpath
-        await run_command(*checkout_cmd)
+    Raises
+    ------
+    OSError
+        If the directory cannot be created
+    """
+    try:
+        os.makedirs(path, exist_ok=True)
+    except OSError as exc:
+        raise OSError(f"Failed to create directory {path}: {exc}") from exc

src/gitingest/config.py

@@ -7,6 +7,7 @@
 MAX_DIRECTORY_DEPTH = 20  # Maximum depth of directory traversal
 MAX_FILES = 10_000  # Maximum number of files to process
 MAX_TOTAL_SIZE_BYTES = 500 * 1024 * 1024  # 500 MB
+DEFAULT_TIMEOUT = 60  # seconds
 
 OUTPUT_FILE_NAME = "digest.txt"
 

src/gitingest/schemas/ingestion_schema.py

@@ -29,6 +29,8 @@ class CloneConfig:
         The branch to clone (default is None).
     subpath : str
         The subpath to clone from the repository (default is "/").
+    blob: bool
+        Whether the repository is a blob (default is False).
     """
 
     url: str

tests/test_repository_clone.py

@@ -435,16 +435,23 @@ async def test_clone_with_commit_and_subpath() -> None:
                 clone_config.local_path,
             )
 
-            # Verify the sparse-checkout command sets the correct path
+            # Verify sparse-checkout set
             mock_exec.assert_any_call(
                 "git",
                 "-C",
                 clone_config.local_path,
                 "sparse-checkout",
                 "set",
                 "src/docs",
+            )
+
+            # Verify checkout commit
+            mock_exec.assert_any_call(
+                "git",
+                "-C",
+                clone_config.local_path,
                 "checkout",
                 clone_config.commit,
             )
 
-            assert mock_exec.call_count == 2
+            assert mock_exec.call_count == 3