Add option to output digest to stdout

This change introduces the ability for users to
direct the output of the gitingest tool to
standard output (stdout) instead of writing to a
file. This is useful for piping the output to
other commands or viewing it directly in the
terminal.

Author: cwest

README.md

@@ -77,17 +77,20 @@ Issues and feature requests are welcome to the repo.
 The `gitingest` command line tool allows you to analyze codebases and create a text dump of their contents.
 
 ```bash
-# Basic usage
+# Basic usage (writes to digest.txt by default)
 gitingest /path/to/directory
 
 # From URL
 gitingest https://github.com/cyclotruc/gitingest
 
+# Output to STDOUT instead of a file
+gitingest . -o -
+
 # See more options
 gitingest --help
 ```
 
-This will write the digest in a text file (default `digest.txt`) in your current working directory.
+By default, the digest is written to a text file (`digest.txt`) in your current working directory. Use `-o -` or `--output -` to print to standard output instead.
 
 ## 🐍 Python package usage
 

src/gitingest/cli.py

@@ -37,7 +37,7 @@ def main(
         The source directory or repository to analyze.
     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.
+        to a file named `<repo_name>.txt` in the current directory. Use '-' to output to stdout.
     max_size : int
         The maximum file size to process, in bytes. Files larger than this size will be ignored.
     exclude_pattern : Tuple[str, ...]
@@ -63,15 +63,16 @@ async def _async_main(
     Analyze a directory or repository and create a text dump of its contents.
 
     This command analyzes the contents of a specified source directory or repository, applies custom include and
-    exclude patterns, and generates a text summary of the analysis which is then written to an output file.
+    exclude patterns, and generates a text summary of the analysis which is then written to an output file
+    or printed to stdout.
 
     Parameters
     ----------
     source : str
         The source directory or repository to analyze.
     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.
+        to a file named `<repo_name>.txt` in the current directory. Use '-' to output to stdout.
     max_size : int
         The maximum file size to process, in bytes. Files larger than this size will be ignored.
     exclude_pattern : Tuple[str, ...]
@@ -91,16 +92,33 @@ async def _async_main(
         exclude_patterns = set(exclude_pattern)
         include_patterns = set(include_pattern)
 
-        if not output:
-            output = OUTPUT_FILE_NAME
-        summary, _, _ = await ingest_async(source, max_size, include_patterns, exclude_patterns, branch, output=output)
+        output_target = output
+        if output is None:
+            output_target = OUTPUT_FILE_NAME
+            click.echo(f"Analyzing source, output will be written to '{output_target}'...", err=True)
+        elif output == "-":
+            click.echo("Analyzing source, preparing output for stdout...", err=True)
+        else:
+            click.echo(f"Analyzing source, output will be written to '{output_target}'...", err=True)
+
+
+        summary, _, _ = await ingest_async(
+            source, max_size, include_patterns, exclude_patterns, branch, output=output_target
+        )
+
+        if output != "-":
+            click.echo(f"Analysis complete! Output written to: {output_target}")
+            click.echo("\nSummary:")
+            click.echo(summary)
+        else:
+            click.echo("\n--- Summary ---", err=True)
+            click.echo(summary, err=True)
+            click.echo("--- End Summary ---", err=True)
+            click.echo("Analysis complete! Output sent to stdout.", err=True)
 
-        click.echo(f"Analysis complete! Output written to: {output}")
-        click.echo("\nSummary:")
-        click.echo(summary)
 
     except Exception as exc:
-        click.echo(f"Error: {exc}", err=True)
+        click.echo(f"Error processing '{source}': {exc}", err=True)
         raise click.Abort()
 
 

src/gitingest/entrypoint.py

@@ -3,6 +3,7 @@
 import asyncio
 import inspect
 import shutil
+import sys
 from typing import Optional, Set, Tuple, Union
 
 from gitingest.cloning import clone_repo
@@ -85,7 +86,12 @@ async def ingest_async(
 
         summary, tree, content = ingest_query(query)
 
-        if output is not None:
+        if output == "-":
+            loop = asyncio.get_running_loop()
+            output_data = tree + "\n" + content
+            await loop.run_in_executor(None, sys.stdout.write, output_data)
+            await loop.run_in_executor(None, sys.stdout.flush)
+        elif output is not None:
             with open(output, "w", encoding="utf-8") as f:
                 f.write(tree + "\n" + content)
 

tests/test_cli.py

@@ -39,3 +39,17 @@ def test_cli_with_options():
     assert os.path.exists(OUTPUT_FILE_NAME), f"Output file was not created at {OUTPUT_FILE_NAME}"
 
     os.remove(OUTPUT_FILE_NAME)
+
+
+def test_cli_with_stdout_output():
+    """Test CLI invocation with output directed to STDOUT."""
+    runner = CliRunner(mix_stderr=False)
+    result = runner.invoke(main, ["./", "--output", "-", "--exclude-pattern", "tests/"])
+
+    assert result.exit_code == 0, f"CLI exited with code {result.exit_code}, stderr: {result.stderr}"
+    assert "---" in result.output, "Expected file separator '---' not found in STDOUT"
+    assert "src/gitingest/cli.py" in result.output, "Expected content (e.g., src/gitingest/cli.py) not found in STDOUT"
+    assert not os.path.exists(OUTPUT_FILE_NAME), f"Output file {OUTPUT_FILE_NAME} was unexpectedly created."
+    assert f"Analysis complete!  Output sent to stdout." not in result.output
+    assert "Analysis complete!" in result.stderr, "Expected summary message 'Analysis complete!' not found in STDERR"
+    assert f"Output written to: {OUTPUT_FILE_NAME}" not in result.stderr