fix: deduplicate env-var helper, add --tag flag, and tidy docs/tests

Refactor

* Deduplicate `_get_env_var` by moving it to `utils/config_utils.py`.
* Remove redundant `local_path` parameter from `_process_file`.

Fix

* Add missing `tag` parameter to `_async_main`, `main`, and `_CLIArgs`.
* Introduce the missing `--tag` CLI flag.

Docs and consistency

* Update `README.md` for `markdownlint` compliance and other minor tweaks.
* Add missing argument docs to `_async_main` docstring.
* Re-order global variables in `config.py` for consistency.
* Swap the order of `include_patterns` and `ignore_patterns` in `parse_query` and `ingest_async`.
* Tidy docstrings for `_async_main`, `IngestionQuery`, `parse_query`, `ingest_async`, and `ingest`.

Tests

* Temporarily disable `[tool.ruff.lint.isort]` due to conflict with the `isort` pre-commit hook.
* Add new arguments to `expected` in `test_parse_query_without_host`.
* Run `pre-commit` hooks.

Author: filipchristiansen

README.md

@@ -135,7 +135,7 @@ By default, the digest is written to a text file (`digest.txt`) in your current
 - Use `--output/-o <filename>` to write to a specific file.
 - Use `--output/-o -` to output directly to `STDOUT` (useful for piping to other tools).
 
-Configure processing limits:
+### 🔧 Configure processing limits
 
 ```bash
 # Set higher limits for large repositories
@@ -157,32 +157,34 @@ See more options and usage details with:
 gitingest --help
 ```
 
-### 🔧 Configuration via Environment Variables
+### Configuration via Environment Variables
 
 You can configure various limits and settings using environment variables. All configuration environment variables start with the `GITINGEST_` prefix:
 
-**File Processing Configuration:**
-- `GITINGEST_MAX_FILE_SIZE` - Maximum size of a single file to process (default: 10485760 bytes, 10MB)
-- `GITINGEST_MAX_FILES` - Maximum number of files to process (default: 10000)
-- `GITINGEST_MAX_TOTAL_SIZE_BYTES` - Maximum size of output file (default: 524288000 bytes, 500MB)
-- `GITINGEST_MAX_DIRECTORY_DEPTH` - Maximum depth of directory traversal (default: 20)
-- `GITINGEST_DEFAULT_TIMEOUT` - Default operation timeout in seconds (default: 60)
-- `GITINGEST_OUTPUT_FILE_NAME` - Default output filename (default: "digest.txt")
-- `GITINGEST_TMP_BASE_PATH` - Base path for temporary files (default: system temp directory)
+#### File Processing Configuration
 
-**Server Configuration (for self-hosting):**
-- `GITINGEST_MAX_DISPLAY_SIZE` - Maximum size of content to display in UI (default: 300000 bytes)
-- `GITINGEST_DELETE_REPO_AFTER` - Repository cleanup timeout in seconds (default: 3600, 1 hour)
-- `GITINGEST_MAX_FILE_SIZE_KB` - Maximum file size for UI slider in KB (default: 102400, 100MB)
-- `GITINGEST_MAX_SLIDER_POSITION` - Maximum slider position in UI (default: 500)
+- `GITINGEST_MAX_FILE_SIZE` - Maximum size of a single file to process *(default: 10485760 bytes, 10 MB)*
+- `GITINGEST_MAX_FILES` - Maximum number of files to process *(default: 10000)*
+- `GITINGEST_MAX_TOTAL_SIZE_BYTES` - Maximum size of output file *(default: 524288000 bytes, 500 MB)*
+- `GITINGEST_MAX_DIRECTORY_DEPTH` - Maximum depth of directory traversal *(default: 20)*
+- `GITINGEST_DEFAULT_TIMEOUT` - Default operation timeout in seconds *(default: 60)*
+- `GITINGEST_OUTPUT_FILE_NAME` - Default output filename *(default: "digest.txt")*
+- `GITINGEST_TMP_BASE_PATH` - Base path for temporary files *(default: system temp directory)*
 
-**Example usage:**
+#### Server Configuration (for self-hosting)
+
+- `GITINGEST_MAX_DISPLAY_SIZE` - Maximum size of content to display in UI *(default: 300000 bytes)*
+- `GITINGEST_DELETE_REPO_AFTER` - Repository cleanup timeout in seconds *(default: 3600, 1 hour)*
+- `GITINGEST_MAX_FILE_SIZE_KB` - Maximum file size for UI slider in kB *(default: 102400, 100 MB)*
+- `GITINGEST_MAX_SLIDER_POSITION` - Maximum slider position in UI *(default: 500)*
+
+#### Example usage
 
 ```bash
 # Configure for large scientific repositories
 export GITINGEST_MAX_FILES=50000
-export GITINGEST_MAX_FILE_SIZE=20971520  # 20MB
-export GITINGEST_MAX_TOTAL_SIZE_BYTES=1073741824  # 1GB
+export GITINGEST_MAX_FILE_SIZE=20971520           # 20 MB
+export GITINGEST_MAX_TOTAL_SIZE_BYTES=1073741824  #  1 GB
 
 gitingest https://github.com/some/large-repo
 ```
@@ -219,9 +221,9 @@ summary, tree, content = ingest("https://github.com/username/repo-with-submodule
 # Configure limits programmatically
 summary, tree, content = ingest(
     "https://github.com/username/large-repo",
-    max_file_size=20 * 1024 * 1024,  # 20MB per file
+    max_file_size=20 * 1024 * 1024,   # 20 MB per file
     max_files=50000,                  # 50k files max
-    max_total_size_bytes=1024**3,     # 1GB total
+    max_total_size_bytes=1024**3,     # 1 GB total
     max_directory_depth=30            # 30 levels deep
 )
 ```

pyproject.toml

@@ -97,9 +97,9 @@ per-file-ignores = { "tests/**/*.py" = ["S101"] } # Skip the "assert used" warni
 [tool.ruff.lint.pylint]
 max-returns = 10
 
-[tool.ruff.lint.isort]
-order-by-type = true
-case-sensitive = true
+# [tool.ruff.lint.isort]
+# order-by-type = true
+# case-sensitive = true
 
 [tool.pycln]
 all = true

src/gitingest/cli.py

@@ -9,7 +9,7 @@
 import click
 from typing_extensions import Unpack
 
-from gitingest.config import MAX_FILE_SIZE, MAX_FILES, MAX_TOTAL_SIZE_BYTES, MAX_DIRECTORY_DEPTH, OUTPUT_FILE_NAME
+from gitingest.config import MAX_DIRECTORY_DEPTH, MAX_FILE_SIZE, MAX_FILES, MAX_TOTAL_SIZE_BYTES, OUTPUT_FILE_NAME
 from gitingest.entrypoint import ingest_async
 
 
@@ -22,6 +22,7 @@ class _CLIArgs(TypedDict):
     exclude_pattern: tuple[str, ...]
     include_pattern: tuple[str, ...]
     branch: str | None
+    tag: str | None
     include_gitignored: bool
     include_submodules: bool
     token: str | None
@@ -63,6 +64,7 @@ class _CLIArgs(TypedDict):
     help="Shell-style patterns to include.",
 )
 @click.option("--branch", "-b", default=None, help="Branch to clone and ingest")
+@click.option("--tag", default=None, help="Tag to clone and ingest")
 @click.option(
     "--include-gitignored",
     is_flag=True,
@@ -119,7 +121,7 @@ def main(**cli_kwargs: Unpack[_CLIArgs]) -> None:
         $ gitingest --include-pattern "*.js" --exclude-pattern "node_modules/*"
 
     Private repositories:
-        $ gitingest https://github.com/user/private-repo -t ghp_token
+        $ gitingest https://github.com/user/private-repo --token ghp_token
         $ GITHUB_TOKEN=ghp_token gitingest https://github.com/user/private-repo
 
     Include submodules:
@@ -139,6 +141,7 @@ async def _async_main(
     exclude_pattern: tuple[str, ...] | None = None,
     include_pattern: tuple[str, ...] | None = None,
     branch: str | None = None,
+    tag: str | None = None,
     include_gitignored: bool = False,
     include_submodules: bool = False,
     token: str | None = None,
@@ -156,21 +159,29 @@ async def _async_main(
         A directory path or a Git repository URL.
     max_size : int
         Maximum file size in bytes to ingest (default: 10 MB).
+    max_files : int
+        Maximum number of files to ingest (default: 10,000).
+    max_total_size : int
+        Maximum total size of output file in bytes (default: 500 MB).
+    max_directory_depth : int
+        Maximum depth of directory traversal (default: 20).
     exclude_pattern : tuple[str, ...] | None
         Glob patterns for pruning the file set.
     include_pattern : tuple[str, ...] | None
         Glob patterns for including files in the output.
     branch : str | None
-        Git branch to ingest. If ``None``, the repository's default branch is used.
+        Git branch to clone and ingest (default: the default branch).
+    tag : str | None
+        Git tag to clone and ingest. If ``None``, no tag is used.
     include_gitignored : bool
-        If ``True``, also ingest files matched by ``.gitignore`` or ``.gitingestignore`` (default: ``False``).
+        If ``True``, include files ignored by ``.gitignore`` and ``.gitingestignore`` (default: ``False``).
     include_submodules : bool
         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.
     output : str | None
-        The path where the output file will be written (default: ``digest.txt`` in current directory).
+        The path where the output file is written (default: ``digest.txt`` in current directory).
         Use ``"-"`` to write to ``stdout``.
 
     Raises
@@ -197,9 +208,10 @@ async def _async_main(
             max_files=max_files,
             max_total_size_bytes=max_total_size,
             max_directory_depth=max_directory_depth,
-            include_patterns=include_patterns,
             exclude_patterns=exclude_patterns,
+            include_patterns=include_patterns,
             branch=branch,
+            tag=tag,
             include_gitignored=include_gitignored,
             include_submodules=include_submodules,
             token=token,

src/gitingest/config.py

@@ -1,34 +1,16 @@
 """Configuration file for the project."""
 
-import os
 import tempfile
 from pathlib import Path
 
-# Helper function to get environment variables with type conversion
-def _get_env_var(key: str, default, cast_func=None):
-    """Get environment variable with GITINGEST_ prefix and optional type casting."""
-    env_key = f"GITINGEST_{key}"
-    value = os.environ.get(env_key)
-    
-    if value is None:
-        return default
-    
-    if cast_func:
-        try:
-            return cast_func(value)
-        except (ValueError, TypeError):
-            print(f"Warning: Invalid value for {env_key}: {value}. Using default: {default}")
-            return default
-    
-    return value
+from gitingest.utils.config_utils import _get_env_var
 
-# Configuration with environment variable support
-MAX_FILE_SIZE = _get_env_var("MAX_FILE_SIZE", 10 * 1024 * 1024, int)  # Maximum size of a single file to process (10 MB)
-MAX_DIRECTORY_DEPTH = _get_env_var("MAX_DIRECTORY_DEPTH", 20, int)  # Maximum depth of directory traversal
-MAX_FILES = _get_env_var("MAX_FILES", 10_000, int)  # Maximum number of files to process
-MAX_TOTAL_SIZE_BYTES = _get_env_var("MAX_TOTAL_SIZE_BYTES", 500 * 1024 * 1024, int)  # Maximum size of output file (500 MB)
-DEFAULT_TIMEOUT = _get_env_var("DEFAULT_TIMEOUT", 60, int)  # seconds
+MAX_FILE_SIZE = _get_env_var("MAX_FILE_SIZE", 10 * 1024 * 1024, int)  # Max file size to process in bytes (10 MB)
+MAX_FILES = _get_env_var("MAX_FILES", 10_000, int)  # Max number of files to process
+MAX_TOTAL_SIZE_BYTES = _get_env_var("MAX_TOTAL_SIZE_BYTES", 500 * 1024 * 1024, int)  # Max output file size (500 MB)
+MAX_DIRECTORY_DEPTH = _get_env_var("MAX_DIRECTORY_DEPTH", 20, int)  # Max depth of directory traversal
 
-OUTPUT_FILE_NAME = _get_env_var("OUTPUT_FILE_NAME", "digest.txt")
+DEFAULT_TIMEOUT = _get_env_var("DEFAULT_TIMEOUT", 60, int)  # Default timeout for git operations in seconds
 
+OUTPUT_FILE_NAME = _get_env_var("OUTPUT_FILE_NAME", "digest.txt")
 TMP_BASE_PATH = Path(_get_env_var("TMP_BASE_PATH", tempfile.gettempdir())) / "gitingest"

src/gitingest/entrypoint.py

@@ -25,8 +25,8 @@ async def ingest_async(
     max_files: int | None = None,
     max_total_size_bytes: int | None = None,
     max_directory_depth: int | None = None,
-    include_patterns: str | set[str] | None = None,
     exclude_patterns: str | set[str] | None = None,
+    include_patterns: str | set[str] | None = None,
     branch: str | None = None,
     tag: str | None = None,
     include_gitignored: bool = False,
@@ -43,17 +43,23 @@ async def ingest_async(
     Parameters
     ----------
     source : str
-        The source to analyze, which can be a URL (for a Git repository) or a local directory path.
+        A directory path or a Git repository URL.
     max_file_size : int
-        Maximum allowed file size for file ingestion. Files larger than this size are ignored (default: 10 MB).
-    include_patterns : str | set[str] | None
-        Pattern or set of patterns specifying which files to include. If ``None``, all files are included.
+        Maximum file size in bytes to ingest (default: 10 MB).
+    max_files : int | None
+        Maximum number of files to ingest (default: 10,000).
+    max_total_size_bytes : int | None
+        Maximum total size of output file in bytes (default: 500 MB).
+    max_directory_depth : int | None
+        Maximum depth of directory traversal (default: 20).
     exclude_patterns : str | set[str] | None
-        Pattern or set of patterns specifying which files to exclude. If ``None``, no files are excluded.
+        Glob patterns for pruning the file set.
+    include_patterns : str | set[str] | None
+        Glob patterns for including files in the output.
     branch : str | None
-        The branch to clone and ingest (default: the default branch).
+        Git branch to clone and ingest (default: the default branch).
     tag : str | None
-        The tag to clone and ingest. If ``None``, no tag is used.
+        Git tag to 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
@@ -62,7 +68,7 @@ async def ingest_async(
         GitHub personal access token (PAT) for accessing private repositories.
         Can also be set via the ``GITHUB_TOKEN`` environment variable.
     output : str | None
-        File path where the summary and content should be written.
+        File path where the summary and content is written.
         If ``"-"`` (dash), the results are written to ``stdout``.
         If ``None``, the results are not written to a file.
 
@@ -84,8 +90,8 @@ async def ingest_async(
         max_total_size_bytes=max_total_size_bytes,
         max_directory_depth=max_directory_depth,
         from_web=False,
-        include_patterns=include_patterns,
         ignore_patterns=exclude_patterns,
+        include_patterns=include_patterns,
         token=token,
     )
 
@@ -110,8 +116,8 @@ def ingest(
     max_files: int | None = None,
     max_total_size_bytes: int | None = None,
     max_directory_depth: int | None = None,
-    include_patterns: str | set[str] | None = None,
     exclude_patterns: str | set[str] | None = None,
+    include_patterns: str | set[str] | None = None,
     branch: str | None = None,
     tag: str | None = None,
     include_gitignored: bool = False,
@@ -128,23 +134,23 @@ def ingest(
     Parameters
     ----------
     source : str
-        The source to analyze, which can be a URL (for a Git repository) or a local directory path.
+        A directory path or a Git repository URL.
     max_file_size : int
-        Maximum allowed file size for file ingestion. Files larger than this size are ignored (default: 10 MB).
+        Maximum file size in bytes to ingest (default: 10 MB).
     max_files : int | None
-        Maximum number of files to process. If ``None``, uses the default from config (default: 10,000).
+        Maximum number of files to ingest (default: 10,000).
     max_total_size_bytes : int | None
-        Maximum total size of all files to process in bytes. If ``None``, uses the default from config (default: 500 MB).
+        Maximum total size of output file in bytes (default: 500 MB).
     max_directory_depth : int | None
-        Maximum depth of directory traversal. If ``None``, uses the default from config (default: 20).
-    include_patterns : str | set[str] | None
-        Pattern or set of patterns specifying which files to include. If ``None``, all files are included.
+        Maximum depth of directory traversal (default: 20).
     exclude_patterns : str | set[str] | None
-        Pattern or set of patterns specifying which files to exclude. If ``None``, no files are excluded.
+        Glob patterns for pruning the file set.
+    include_patterns : str | set[str] | None
+        Glob patterns for including files in the output.
     branch : str | None
-        The branch to clone and ingest (default: the default branch).
+        Git branch to clone and ingest (default: the default branch).
     tag : str | None
-        The tag to clone and ingest. If ``None``, no tag is used.
+        Git tag to 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
@@ -153,7 +159,7 @@ def ingest(
         GitHub personal access token (PAT) for accessing private repositories.
         Can also be set via the ``GITHUB_TOKEN`` environment variable.
     output : str | None
-        File path where the summary and content should be written.
+        File path where the summary and content is written.
         If ``"-"`` (dash), the results are written to ``stdout``.
         If ``None``, the results are not written to a file.
 
@@ -177,8 +183,8 @@ def ingest(
             max_files=max_files,
             max_total_size_bytes=max_total_size_bytes,
             max_directory_depth=max_directory_depth,
-            include_patterns=include_patterns,
             exclude_patterns=exclude_patterns,
+            include_patterns=include_patterns,
             branch=branch,
             tag=tag,
             include_gitignored=include_gitignored,

src/gitingest/ingestion.py

@@ -5,7 +5,6 @@
 from pathlib import Path
 from typing import TYPE_CHECKING
 
-from gitingest.config import MAX_DIRECTORY_DEPTH, MAX_FILES, MAX_TOTAL_SIZE_BYTES
 from gitingest.output_formatter import format_node
 from gitingest.schemas import FileSystemNode, FileSystemNodeType, FileSystemStats
 from gitingest.utils.ingestion_utils import _should_exclude, _should_include
@@ -113,7 +112,7 @@ def _process_node(node: FileSystemNode, query: IngestionQuery, stats: FileSystem
             if sub_path.stat().st_size > query.max_file_size:
                 print(f"Skipping file {sub_path}: would exceed max file size limit")
                 continue
-            _process_file(path=sub_path, parent_node=node, stats=stats, local_path=query.local_path, query=query)
+            _process_file(path=sub_path, parent_node=node, stats=stats, query=query)
         elif sub_path.is_dir():
             child_directory_node = FileSystemNode(
                 name=sub_path.name,
@@ -167,7 +166,7 @@ def _process_symlink(path: Path, parent_node: FileSystemNode, stats: FileSystemS
     parent_node.file_count += 1
 
 
-def _process_file(path: Path, parent_node: FileSystemNode, stats: FileSystemStats, local_path: Path, query: IngestionQuery) -> None:
+def _process_file(path: Path, parent_node: FileSystemNode, stats: FileSystemStats, query: IngestionQuery) -> None:
     """Process a file in the file system.
 
     This function checks the file's size, increments the statistics, and reads its content.
@@ -181,8 +180,6 @@ def _process_file(path: Path, parent_node: FileSystemNode, stats: FileSystemStat
         The dictionary to accumulate the results.
     stats : FileSystemStats
         Statistics tracking object for the total file count and size.
-    local_path : Path
-        The base path of the repository or directory being processed.
     query : IngestionQuery
         The query object containing the limit configurations.
 
@@ -193,7 +190,9 @@ def _process_file(path: Path, parent_node: FileSystemNode, stats: FileSystemStat
 
     file_size = path.stat().st_size
     if stats.total_size + file_size > query.max_total_size_bytes:
-        print(f"Skipping file {path}: would exceed total size limit")
+        print(
+            f"Skipping file {path}: would exceed total size limit ({query.max_total_size_bytes / 1024 / 1024:.1f}MB)",
+        )
         return
 
     stats.total_files += 1
@@ -204,7 +203,7 @@ def _process_file(path: Path, parent_node: FileSystemNode, stats: FileSystemStat
         type=FileSystemNodeType.FILE,
         size=file_size,
         file_count=1,
-        path_str=str(path.relative_to(local_path)),
+        path_str=str(path.relative_to(query.local_path)),
         path=path,
         depth=parent_node.depth + 1,
     )