docs: Fix CLI help text accuracy (#332)

* docs: Fix CLI help text accuracy

- Add stdout documentation to --output option help text
- Update default filename to 'digest.txt' consistently
- Enhance docstrings with comprehensive usage examples
- Improve GitHub token documentation with environment variable support
- Fix inconsistencies between help text and actual CLI behavior

Co-authored-by: Filip Christiansen

Author: Sendi0011

src/gitingest/cli.py

@@ -61,10 +61,40 @@ class _CLIArgs(TypedDict):
     "--output",
     "-o",
     default=None,
-    help="Write to PATH (or '-' for stdout, default: <repo>.txt).",
+    help="Output file path (default: digest.txt in current directory). Use '-' for stdout.",
 )
 def main(**cli_kwargs: Unpack[_CLIArgs]) -> None:
-    """Run the CLI entry point to analyze a repo / directory and dump its contents."""
+    """Run the CLI entry point to analyze a repo / directory and dump its contents.
+
+    Parameters
+    ----------
+    **cli_kwargs : Unpack[_CLIArgs]
+        A dictionary of keyword arguments forwarded to ``ingest_async``.
+
+    Notes
+    -----
+    See ``ingest_async`` for a detailed description of each argument.
+
+    Examples
+    --------
+    Basic usage:
+        $ gitingest
+        $ gitingest /path/to/repo
+        $ gitingest https://github.com/user/repo
+
+    Output to stdout:
+        $ gitingest -o -
+        $ gitingest https://github.com/user/repo --output -
+
+    With filtering:
+        $ gitingest -i "*.py" -e "*.log"
+        $ gitingest --include-pattern "*.js" --exclude-pattern "node_modules/*"
+
+    Private repositories:
+        $ gitingest https://github.com/user/private-repo -t ghp_token
+        $ GITHUB_TOKEN=ghp_token gitingest https://github.com/user/private-repo
+
+    """
     asyncio.run(_async_main(**cli_kwargs))
 
 
@@ -88,7 +118,7 @@ async def _async_main(
     Parameters
     ----------
     source : str
-        Directory path or Git repository URL.
+        A directory path or a Git repository URL.
     max_size : int
         Maximum file size in bytes to ingest (default: 10 MB).
     exclude_pattern : tuple[str, ...] | None
@@ -103,7 +133,7 @@ async def _async_main(
         GitHub personal access token (PAT) for accessing private repositories.
         Can also be set via the ``GITHUB_TOKEN`` environment variable.
     output : str | None
-        Destination file path. If ``None``, the output is written to ``<repo_name>.txt`` in the current directory.
+        The path where the output file will be written (default: ``digest.txt`` in current directory).
         Use ``"-"`` to write to ``stdout``.
 
     Raises

src/gitingest/utils/git_utils.py

@@ -102,7 +102,6 @@ async def check_repo_exists(url: str, token: str | None = None) -> bool:
         If the curl command returns an unexpected status code.
 
     """
-    expected_path_length = 2
     if token and is_github_host(url):
         return await _check_github_repo_exists(url, token=token)
 
@@ -121,11 +120,13 @@ async def check_repo_exists(url: str, token: str | None = None) -> bool:
     response = stdout.decode()
     status_line = response.splitlines()[0].strip()
     parts = status_line.split(" ")
+
+    expected_path_length = 2
     if len(parts) >= expected_path_length:
-        status_code_str = parts[1]
-        if status_code_str in ("200", "301"):
+        status = parts[1]
+        if status in ("200", "301"):
             return True
-        if status_code_str in ("302", "404"):
+        if status in ("302", "404"):
             return False
     msg = f"Unexpected status line: {status_line}"
     raise RuntimeError(msg)

src/static/llm.txt

@@ -176,20 +176,20 @@ gitingest https://github.com/user/private-repo -t $GITHUB_TOKEN -o -
 # Specific branch analysis (short flag)
 gitingest https://github.com/user/repo -b main -o -
 
-# Save to file (default: <repo_name>.txt in current directory)
+# Save to file (default: digest.txt in current directory)
 gitingest https://github.com/user/repo -o my_analysis.txt
 
 # Ultra-concise example for small files only
 gitingest https://github.com/user/repo -i "*.py" -s 51200 -o -
 ```
 
 **Key Parameters for AI Agents**:
-- `-o` / `--output`: Stream to STDOUT with `-` (default saves to `<repo_name>.txt`)
 - `-s` / `--max-size`: Maximum file size in bytes to process (default: no limit)
 - `-i` / `--include-pattern`: Include files matching Unix shell-style wildcards
 - `-e` / `--exclude-pattern`: Exclude files matching Unix shell-style wildcards
 - `-b` / `--branch`: Specify branch to analyze (defaults to repository's default branch)
 - `-t` / `--token`: GitHub personal access token for private repositories
+- `-o` / `--output`: Stream to STDOUT with `-` (default saves to `digest.txt`)
 
 ### 4.2 Python Package (Best for Code Integration)
 ```python