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