feat: Change default output to stdout instead of file

Breaking change: TreeMapper now outputs to stdout by default instead of creating a file.
- Default behavior is now to output YAML to stdout
- Use -o/--output-file parameter to write to a file
- Support -o - to explicitly output to stdout
- Update all tests to specify output file where needed

This makes TreeMapper more Unix-friendly and allows for easier piping and redirection.

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>

Author: nikolay-e

.treemapperignore

@@ -5,8 +5,8 @@
 from typing import Optional, Tuple
 
 
-# ---> CHANGE: Return types are correct, no change needed here.
-def parse_args() -> Tuple[Path, Optional[Path], Path, bool, int]:
+# ---> CHANGE: Updated return type to reflect that output_file can now be None.
+def parse_args() -> Tuple[Path, Optional[Path], Optional[Path], bool, int]:
     """Parse command line arguments."""
     parser = argparse.ArgumentParser(
         prog="treemapper",
@@ -18,8 +18,8 @@ def parse_args() -> Tuple[Path, Optional[Path], Path, bool, int]:
 
     parser.add_argument("-i", "--ignore-file", default=None, help="Path to the custom ignore file (optional)")
 
-    # ---> CHANGE: Default output is now explicitly relative to the current directory.
-    parser.add_argument("-o", "--output-file", default="directory_tree.yaml", help="Path to the output YAML file")
+    # ---> CHANGE: Default output is now stdout (None). Only write to file when explicitly specified.
+    parser.add_argument("-o", "--output-file", default=None, help="Path to the output YAML file (default: stdout)")
 
     parser.add_argument(
         "--no-default-ignores", action="store_true", help="Disable default ignores (.treemapperignore, .gitignore, output file)"
@@ -52,7 +52,10 @@ def parse_args() -> Tuple[Path, Optional[Path], Path, bool, int]:
 
     # ---> CHANGE: Resolve output file relative to the current working directory.
     # .resolve() makes the path absolute from CWD if it's relative.
-    output_file = Path(args.output_file).resolve()
+    # If no output file is specified or "-" is used, output_file will be None
+    output_file = None
+    if args.output_file and args.output_file != "-":
+        output_file = Path(args.output_file).resolve()
 
     ignore_file_path: Optional[Path] = None
     if args.ignore_file:

src/treemapper/cli.py

@@ -2,11 +2,12 @@
 
 # os is used for access permission checking
 import os
+import sys
 from pathlib import Path
-from typing import Any, Dict
+from typing import Any, Dict, Optional, TextIO
 
 
-def write_yaml_node(file, node: Dict[str, Any], indent: str = "") -> None:
+def write_yaml_node(file: TextIO, node: Dict[str, Any], indent: str = "") -> None:
     """Write a node of the directory tree in YAML format."""
     # Escape filename with double quotes and handle any special characters
     # This prevents issues with filenames like 'true', 'false', numbers, or names with special chars
@@ -25,40 +26,51 @@ def write_yaml_node(file, node: Dict[str, Any], indent: str = "") -> None:
             write_yaml_node(file, child, indent + "  ")
 
 
-def write_tree_to_file(tree: Dict[str, Any], output_file: Path) -> None:
-    """Write the complete tree to a YAML file."""
-    try:
-        # Create parent directories if they don't exist
-        output_file.parent.mkdir(parents=True, exist_ok=True)
+def write_tree_to_file(tree: Dict[str, Any], output_file: Optional[Path]) -> None:
+    """Write the complete tree to a YAML file or stdout."""
 
-        # For directories, try an early write test
-        if output_file.is_dir():
-            logging.error(f"Unable to write to file '{output_file}': Is a directory")
-            raise IOError(f"Is a directory: {output_file}")
+    def write_tree_content(f: TextIO) -> None:
+        """Write the tree content to the given file handle."""
+        # Properly quote the root name as well
+        name = str(tree["name"]).replace('"', '\\"')
+        f.write(f'name: "{name}"\n')
+        f.write(f"type: {tree['type']}\n")
+        if "children" in tree and tree["children"]:
+            f.write("children:\n")
+            for child in tree["children"]:
+                write_yaml_node(f, child, "  ")
 
-        # Check write permissions using os.access
-        if not os.access(output_file.parent, os.W_OK):
-            logging.error(f"Unable to write to file '{output_file}': Permission denied for directory")
-            raise IOError(f"Permission denied for directory: {output_file.parent}")
-
-        # Test write permissions directly by attempting to open the file
+    if output_file is None:
+        # Write to stdout
+        write_tree_content(sys.stdout)
+        logging.info("Directory tree written to stdout")
+    else:
+        # Write to file
         try:
-            test_handle = output_file.open("w", encoding="utf-8")
-            test_handle.close()
-        except (PermissionError, IOError):
-            logging.error(f"Unable to write to file '{output_file}': Permission denied")
-            raise IOError(f"Permission denied: {output_file}")
+            # Create parent directories if they don't exist
+            output_file.parent.mkdir(parents=True, exist_ok=True)
+
+            # For directories, try an early write test
+            if output_file.is_dir():
+                logging.error(f"Unable to write to file '{output_file}': Is a directory")
+                raise IOError(f"Is a directory: {output_file}")
+
+            # Check write permissions using os.access
+            if not os.access(output_file.parent, os.W_OK):
+                logging.error(f"Unable to write to file '{output_file}': Permission denied for directory")
+                raise IOError(f"Permission denied for directory: {output_file.parent}")
+
+            # Test write permissions directly by attempting to open the file
+            try:
+                test_handle = output_file.open("w", encoding="utf-8")
+                test_handle.close()
+            except (PermissionError, IOError):
+                logging.error(f"Unable to write to file '{output_file}': Permission denied")
+                raise IOError(f"Permission denied: {output_file}")
 
-        with output_file.open("w", encoding="utf-8") as f:
-            # Properly quote the root name as well
-            name = str(tree["name"]).replace('"', '\\"')
-            f.write(f'name: "{name}"\n')
-            f.write(f"type: {tree['type']}\n")
-            if "children" in tree and tree["children"]:
-                f.write("children:\n")
-                for child in tree["children"]:
-                    write_yaml_node(f, child, "  ")
-        logging.info(f"Directory tree saved to {output_file}")
-    except IOError as e:
-        logging.error(f"Unable to write to file '{output_file}': {e}")
-        raise
+            with output_file.open("w", encoding="utf-8") as f:
+                write_tree_content(f)
+            logging.info(f"Directory tree saved to {output_file}")
+        except IOError as e:
+            logging.error(f"Unable to write to file '{output_file}': {e}")
+            raise

src/treemapper/writer.py

@@ -31,7 +31,7 @@ def normalize_tree(tree):
 
 def test_basic_mapping(temp_project, run_mapper):
     """Test basic directory mapping with default settings."""
-    assert run_mapper(["."])
+    assert run_mapper([".", "-o", "directory_tree.yaml"])
     output_file = temp_project / "directory_tree.yaml"
     assert output_file.exists()
     result = load_yaml(output_file)
@@ -49,7 +49,7 @@ def test_basic_mapping(temp_project, run_mapper):
 
 def test_directory_content(temp_project, run_mapper):
     """Test directory structure and content preservation."""
-    assert run_mapper(["."])
+    assert run_mapper([".", "-o", "directory_tree.yaml"])
     result = load_yaml(temp_project / "directory_tree.yaml")
     src_dir = find_node_by_path(result, ["src"])
     assert src_dir is not None and src_dir["type"] == "directory"
@@ -93,7 +93,7 @@ def test_file_content_encoding(temp_project, run_mapper):
     (temp_project / "multiline.txt").write_text(multiline_content_orig)
     (temp_project / "empty.txt").write_text(empty_content_orig)
 
-    assert run_mapper(["."])
+    assert run_mapper([".", "-o", "directory_tree.yaml"])
     result = load_yaml(temp_project / "directory_tree.yaml")
 
     ascii_node = find_node_by_path(result, ["ascii.txt"])
@@ -116,7 +116,7 @@ def test_nested_structures(temp_project, run_mapper):
         contents[i] = content_str
         (current / f"file{i}.txt").write_text(content_str)
 
-    assert run_mapper(["."])
+    assert run_mapper([".", "-o", "directory_tree.yaml"])
     result = load_yaml(temp_project / "directory_tree.yaml")
 
     current_node = result

tests/test_basic.py

@@ -37,7 +37,7 @@ def test_default_python_ignores(temp_project, run_mapper):
     (temp_project / "actual_module.py").touch()
 
     # Run TreeMapper and check results
-    assert run_mapper(["."])
+    assert run_mapper([".", "-o", "directory_tree.yaml"])
     result = load_yaml(temp_project / "directory_tree.yaml")
     all_files = get_all_files_in_tree(result)
 
@@ -76,7 +76,7 @@ def test_git_directory_ignored(temp_project, run_mapper):
     (temp_project / "README.md").touch()
 
     # Run TreeMapper and check results
-    assert run_mapper(["."])
+    assert run_mapper([".", "-o", "directory_tree.yaml"])
     result = load_yaml(temp_project / "directory_tree.yaml")
     all_files = get_all_files_in_tree(result)
 
@@ -101,7 +101,7 @@ def test_default_verbosity(temp_project, run_mapper, capfd):
     capfd.readouterr()
 
     # Run with default verbosity (ERROR)
-    assert run_mapper(["."])
+    assert run_mapper([".", "-o", "directory_tree.yaml"])
     out, err = capfd.readouterr()
 
     # At ERROR level, there should be no INFO messages

tests/test_default_ignores.py

@@ -21,7 +21,7 @@ def test_custom_ignore(temp_project, run_mapper):
 .gitignore
 """
     )
-    assert run_mapper([".", "-i", str(ignore_file)])
+    assert run_mapper([".", "-i", str(ignore_file), "-o", "directory_tree.yaml"])
     result = load_yaml(temp_project / "directory_tree.yaml")
     all_files = get_all_files_in_tree(result)
     assert not any(isinstance(f, str) and f.endswith(".py") for f in all_files)
@@ -38,7 +38,7 @@ def test_gitignore_patterns(temp_project, run_mapper):
     (temp_project / "__pycache__" / "cachefile").touch()
     (temp_project / "src" / "local_only.py").touch()
     (temp_project / "src" / "allowed.py").touch()
-    assert run_mapper(["."])
+    assert run_mapper([".", "-o", "directory_tree.yaml"])
     result = load_yaml(temp_project / "directory_tree.yaml")
     all_files = get_all_files_in_tree(result)
     assert "test.pyc" not in all_files
@@ -77,7 +77,7 @@ def test_symlinks_and_special_files(temp_project, run_mapper):
             can_symlink = False
 
     (temp_project / ".treemapperignore").write_text(".*\n!.gitignore\n")
-    assert run_mapper(["."])
+    assert run_mapper([".", "-o", "directory_tree.yaml"])
     result = load_yaml(temp_project / "directory_tree.yaml")
     all_files = get_all_files_in_tree(result)
     assert ".hidden_dir" not in all_files
@@ -236,7 +236,7 @@ def test_unreadable_ignore_file(temp_project, run_mapper, set_perms, caplog):
     set_perms(ignore_file, 0o000)
 
     with caplog.at_level(logging.WARNING):
-        assert run_mapper(["."])
+        assert run_mapper([".", "-o", "directory_tree.yaml"])
 
     assert any(
         "Could not read ignore file" in rec.message and ignore_file.name in rec.message
@@ -255,7 +255,7 @@ def test_bad_encoding_ignore_file(temp_project, run_mapper, caplog):
         pytest.skip("CP1251 codec not found")
 
     with caplog.at_level(logging.WARNING):
-        assert run_mapper(["."])
+        assert run_mapper([".", "-o", "directory_tree.yaml"])
 
     assert any(
         "Could not decode ignore file" in rec.message and ignore_file.name in rec.message and "UTF-8" in rec.message
@@ -267,7 +267,7 @@ def test_bad_encoding_ignore_file(temp_project, run_mapper, caplog):
 
     (temp_project / "папка_игнор").mkdir()
 
-    assert run_mapper(["."])
+    assert run_mapper([".", "-o", "directory_tree.yaml"])
     result = load_yaml(temp_project / "directory_tree.yaml")
     all_files = get_all_files_in_tree(result)
     assert "папка_игнор" in all_files

tests/test_ignore.py

@@ -15,7 +15,7 @@ def test_ignore_precedence_subdir_over_root(temp_project, run_mapper):
     (temp_project / "subdir" / "ignore.txt").touch()
     (temp_project / "subdir" / "allow.txt").touch()
 
-    assert run_mapper(["."])
+    assert run_mapper([".", "-o", "directory_tree.yaml"])
     result = load_yaml(temp_project / "directory_tree.yaml")
     all_files = get_all_files_in_tree(result)
 
@@ -32,7 +32,7 @@ def test_ignore_precedence_treemapper_over_git(temp_project, run_mapper):
     (temp_project / "file.log").touch()
     (temp_project / "file.txt").touch()
 
-    assert run_mapper(["."])
+    assert run_mapper([".", "-o", "directory_tree.yaml"])
     result = load_yaml(temp_project / "directory_tree.yaml")
     all_files = get_all_files_in_tree(result)
 
@@ -53,7 +53,7 @@ def test_ignore_precedence_custom_over_defaults(temp_project, run_mapper):
     (temp_project / "file.tmp").touch()
     (temp_project / "file.txt").touch()
 
-    assert run_mapper([".", "-i", str(custom_ignore)])
+    assert run_mapper([".", "-i", str(custom_ignore), "-o", "directory_tree.yaml"])
     result = load_yaml(temp_project / "directory_tree.yaml")
     all_files = get_all_files_in_tree(result)