feat: add clipboard copy support with -c/--copy and --copy-only flags

Author: nikolay-e

CLAUDE.md

@@ -50,9 +50,28 @@ treemapper . --max-file-bytes 10000   # skip files larger than 10KB
 treemapper . -i custom.ignore         # custom ignore patterns
 treemapper . --no-default-ignores     # disable .gitignore/.treemapperignore (custom -i still works)
 treemapper . -v 2                     # verbose output (0=ERROR, 1=WARNING, 2=INFO, 3=DEBUG)
+treemapper . -c                       # copy output to clipboard (also outputs to stdout)
+treemapper . --copy-only              # copy to clipboard only (no stdout output)
 treemapper --version                  # show version
 ```
 
+## Clipboard Support
+
+Copy output directly to clipboard with `-c` or `--copy`:
+
+```bash
+treemapper . -c                       # copy to clipboard + stdout
+treemapper . -c -o tree.yaml          # copy to clipboard + save to file
+treemapper . --copy-only              # copy to clipboard only
+treemapper . --copy-only -o tree.yaml # copy to clipboard + save to file (no stdout)
+```
+
+**System Requirements:**
+- **macOS:** `pbcopy` (pre-installed)
+- **Windows:** `clip` (pre-installed)
+- **Linux/FreeBSD (Wayland):** `wl-copy` (install: `sudo apt install wl-clipboard`)
+- **Linux/FreeBSD (X11):** `xclip` or `xsel` (install: `sudo apt install xclip`)
+
 ## Python API
 
 ```python

docs/Clipboard Copy.md

@@ -18,6 +18,8 @@ class ParsedArgs:
     max_depth: Optional[int]
     no_content: bool
     max_file_bytes: Optional[int]
+    copy: bool
+    copy_only: bool
 
 
 DEFAULT_IGNORES_HELP = """
@@ -56,6 +58,10 @@ def parse_args() -> ParsedArgs:
     parser.add_argument("--max-depth", type=int, default=None, metavar="N", help="Maximum traversal depth")
     parser.add_argument("--no-content", action="store_true", help="Skip file contents (structure only)")
     parser.add_argument("--max-file-bytes", type=int, default=None, metavar="N", help="Skip files larger than N bytes")
+    parser.add_argument("-c", "--copy", action="store_true", help="Copy output to clipboard")
+    parser.add_argument(
+        "--copy-only", action="store_true", help="Copy to clipboard, suppress stdout (file output with -o still works)"
+    )
     parser.add_argument(
         "-v",
         "--verbosity",
@@ -109,4 +115,6 @@ def parse_args() -> ParsedArgs:
         max_depth=args.max_depth,
         no_content=args.no_content,
         max_file_bytes=args.max_file_bytes,
+        copy=args.copy or args.copy_only,
+        copy_only=args.copy_only,
     )

src/treemapper/cli.py

@@ -0,0 +1,64 @@
+from __future__ import annotations
+
+import os
+import platform
+import shutil
+import subprocess
+
+
+class ClipboardError(Exception):
+    pass
+
+
+def detect_clipboard_command() -> list[str] | None:
+    system = platform.system()
+    if system == "Darwin":
+        if shutil.which("pbcopy"):
+            return ["pbcopy"]
+        return None
+    if system == "Windows":
+        if shutil.which("clip"):
+            return ["clip"]
+        return None
+    if system in ("Linux", "FreeBSD"):
+        if os.environ.get("WAYLAND_DISPLAY") and shutil.which("wl-copy"):
+            return ["wl-copy"]
+        if os.environ.get("DISPLAY"):
+            if shutil.which("xclip"):
+                return ["xclip", "-selection", "clipboard"]
+            if shutil.which("xsel"):
+                return ["xsel", "--clipboard", "--input"]
+        return None
+    return None
+
+
+def copy_to_clipboard(text: str) -> int:
+    cmd = detect_clipboard_command()
+    if cmd is None:
+        raise ClipboardError("No clipboard tool found")
+
+    encoding = "utf-16le" if platform.system() == "Windows" else "utf-8"
+    encoded = text.encode(encoding)
+
+    try:
+        subprocess.run(
+            cmd,
+            input=encoded,
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.PIPE,
+            timeout=5,
+            check=True,
+        )
+    except subprocess.TimeoutExpired as e:
+        raise ClipboardError("Clipboard operation timed out") from e
+    except subprocess.CalledProcessError as e:
+        stderr_msg = e.stderr.decode(errors="replace").strip() if e.stderr else ""
+        raise ClipboardError(stderr_msg or f"Command failed with code {e.returncode}") from e
+    except OSError as e:
+        raise ClipboardError(f"Failed to execute clipboard command: {e}") from e
+
+    return len(encoded)
+
+
+def clipboard_available() -> bool:
+    return detect_clipboard_command() is not None

src/treemapper/clipboard.py

@@ -1,10 +1,17 @@
 import errno
+import logging
 import os
 import sys
 from contextlib import contextmanager
 from typing import Generator
 
 
+def _format_size(size_bytes: int) -> str:
+    if size_bytes < 1024:
+        return f"{size_bytes} B"
+    return f"{size_bytes / 1024:.1f} KB"
+
+
 @contextmanager
 def _handle_broken_pipe() -> Generator[None, None, None]:
     try:
@@ -34,10 +41,11 @@ def _suppress_broken_pipe() -> None:
 
 def main() -> None:
     from .cli import parse_args
+    from .clipboard import ClipboardError, copy_to_clipboard
     from .ignore import get_ignore_specs
     from .logger import setup_logging
     from .tree import TreeBuildContext, build_tree
-    from .writer import write_tree_to_file
+    from .writer import tree_to_string, write_string_to_file, write_tree_to_file
 
     args = parse_args()
     setup_logging(args.verbosity)
@@ -57,7 +65,25 @@ def main() -> None:
         "children": build_tree(args.root_dir, ctx),
     }
 
-    if args.output_file is None:
+    output_content = None
+    if args.copy:
+        output_content = tree_to_string(directory_tree, args.output_format)
+        try:
+            byte_size = copy_to_clipboard(output_content)
+            print(f"Copied to clipboard ({_format_size(byte_size)})", file=sys.stderr)
+        except ClipboardError as e:
+            logging.warning(f"Clipboard: {e}")
+
+    if args.copy_only and args.output_file is None:
+        return
+
+    if output_content is not None:
+        if args.output_file is None:
+            with _handle_broken_pipe():
+                write_string_to_file(output_content, args.output_file, args.output_format)
+        else:
+            write_string_to_file(output_content, args.output_file, args.output_format)
+    elif args.output_file is None:
         with _handle_broken_pipe():
             write_tree_to_file(directory_tree, args.output_file, args.output_format)
     else:

src/treemapper/treemapper.py

@@ -99,6 +99,58 @@ def write_tree_text(file: TextIO, tree: Dict[str, Any]) -> None:
         _write_tree_text_node(file, child, "", i == len(children) - 1)
 
 
+def tree_to_string(tree: Dict[str, Any], output_format: str = "yaml") -> str:
+    buf = io.StringIO()
+    if output_format == "json":
+        write_tree_json(buf, tree)
+    elif output_format == "text":
+        write_tree_text(buf, tree)
+    else:
+        write_tree_yaml(buf, tree)
+    return buf.getvalue()
+
+
+def write_string_to_file(content: str, output_file: Optional[Path], output_format: str = "yaml") -> None:
+    if output_file is None:
+        try:
+            buf = sys.stdout.buffer
+        except AttributeError:
+            buf = None
+
+        try:
+            if buf:
+                utf8_stdout = io.TextIOWrapper(buf, encoding="utf-8", newline="")
+                try:
+                    utf8_stdout.write(content)
+                    utf8_stdout.flush()
+                finally:
+                    utf8_stdout.detach()
+            else:
+                sys.stdout.write(content)
+                sys.stdout.flush()
+        except BrokenPipeError:
+            pass
+
+        logging.info(f"Directory tree written to stdout in {output_format} format")
+    else:
+        try:
+            output_file.parent.mkdir(parents=True, exist_ok=True)
+
+            if output_file.is_dir():
+                logging.error(f"Cannot write to '{output_file}': is a directory")
+                raise IsADirectoryError(f"Is a directory: {output_file}")
+
+            with output_file.open("w", encoding="utf-8") as f:
+                f.write(content)
+            logging.info(f"Directory tree saved to {output_file} in {output_format} format")
+        except PermissionError:
+            logging.error(f"Unable to write to file '{output_file}': Permission denied")
+            raise
+        except OSError as e:
+            logging.error(f"Unable to write to file '{output_file}': {e}")
+            raise
+
+
 def write_tree_to_file(tree: Dict[str, Any], output_file: Optional[Path], output_format: str = "yaml") -> None:
     def write_tree_content(f: TextIO) -> None:
         if output_format == "json":