TreeAndDir

A lightweight Python utility for Windows that captures a complete directory listing and file-tree snapshot of the current working directory and saves them to plain-text files.

---

Table of Contents

• Overview
• Features
• Requirements
• Installation
• Usage
• Output Files
• Code Changes & Improvements
• Troubleshooting
• License

---

Overview

TreeAndDir.py automates two common Windows diagnostic tasks:

1. dir /s — Recursively lists every file and folder in the current directory, including file sizes, dates, and totals.
2. tree /F /A — Renders the directory structure as an ASCII tree with all file names shown (/F) using ASCII characters instead of extended line-drawing characters (/A), making the output portable across all editors and terminals.

Both outputs are written to text files in the same directory where the script is run.

---

Features

• Zero external dependencies — uses only the Python standard library.
• Timing & file-size feedback — reports how long each command took and the size of the output file.
• Robust error handling — non-zero exit codes and I/O errors are caught and reported without crashing the script.
• Smart interactive detection — the "Press Enter to exit" pause only appears when the script is run interactively; it is suppressed automatically in automated/piped contexts.
• UTF-8 output with fallback — files are written as UTF-8; any unencodable characters are replaced rather than raising an exception.
• Clean exit codes — exits 0 on full success, 1 if any command produced a warning, making it easy to use in batch/CI pipelines.

---

Requirements

Requirement	Version
Operating System	Windows 10 / 11 (requires cmd.exe)
Python	3.8 or later

No third-party packages are needed. All modules used (os, subprocess, sys, time, pathlib) are part of the Python standard library.

---

Installation

1. Clone or download this repository (or just copy TreeAndDir.py to any folder).

2. Verify Python is installed:

   python --version
   

   If Python is not installed, download it from python.org.

3. No pip install step is required.

---

Usage

Interactive (double-click or Command Prompt)

Navigate to the directory you want to capture, then run:

cd C:\path\to\target\directory
python TreeAndDir.py

Example session output:

Running 'dir /s'...
  Saved to C:\MyProject\DirOutput.txt  (42.3 KB, 0.18s)
Running 'tree /F /A'...
  Saved to C:\MyProject\TreeOutput.txt  (8.1 KB, 0.05s)

Done.

Press Enter to exit...

Automated / Scripted

The script integrates cleanly into batch files or CI pipelines:

cd C:\MyProject
python TreeAndDir.py
IF ERRORLEVEL 1 (
    echo One or more commands produced warnings.
)

The "Press Enter" prompt is suppressed automatically when stdin is not a terminal (e.g., when output is redirected or the script is called from another process).

---

Output Files

Both files are created in the current working directory at the time the script is run.

DirOutput.txt

Contains the full output of dir /s, including:

• File names, sizes (bytes), and last-modified timestamps for every file.
• Subfolder names and their individual file counts.
• A grand total of files and bytes at the end.

Example excerpt:

 Volume in drive C is Windows
 Volume Serial Number is XXXX-XXXX

 Directory of C:\MyProject

02/20/2026  10:00 AM    <DIR>          .
02/20/2026  10:00 AM    <DIR>          ..
02/20/2026  09:55 AM             1,234 TreeAndDir.py
...

TreeOutput.txt

Contains the full output of tree /F /A, rendering the folder hierarchy as an ASCII diagram.

Example excerpt:

C:\MyProject
+---src
|   +---main.py
|   \---utils.py
+---tests
|   \---test_main.py
\---README.md

Note: The /A flag ensures the output uses standard ASCII characters (+, -, \) instead of extended box-drawing characters, making the file readable in all text editors and terminals without encoding issues.

---

Code Changes & Improvements

The following improvements were made over the original version:

Bug Fixes

• Added /A flag to tree — the original tree /F used extended line-drawing characters which can appear as garbled symbols in some editors. /A forces plain ASCII output.

Robustness

• Error handling — subprocess errors (OSError) and non-zero exit codes are now caught and reported to stderr rather than causing an unhandled exception.
• check=False + manual exit-code inspection — prevents subprocess.CalledProcessError from terminating the script unexpectedly; warnings are printed instead.

Performance

• Direct file streaming — the output file handle is passed directly to subprocess.run via stdout=fh, so data flows from cmd.exe straight to disk with no intermediate Python string buffering. This is both faster and more memory-efficient for large directory trees.
• pathlib.Path — replaces os.path.join string manipulation with the more readable and Pythonic Path API.

Usability

• Elapsed time and file-size reporting — each command prints how long it took and how large the output file is, which is useful for diagnosing slow or empty runs.
• Smart pause suppression — sys.stdin.isatty() check means the input("Press Enter…") prompt only appears in interactive sessions, preventing the script from hanging when run from a scheduler or pipeline.
• Clean exit codes — sys.exit(0/1) enables downstream tooling to detect failures.

Code Quality

• Type hints — run_command is annotated for clarity and IDE support.
• Docstrings — functions are documented with Args/Returns sections.
• main() entry-point pattern — logic is encapsulated in main() and guarded by if __name__ == "__main__", making the module importable without side effects.

---

Troubleshooting

python is not recognized Ensure Python is installed and added to your PATH. Try py TreeAndDir.py as an alternative.

Output files are empty Verify you are running the script from a directory that actually contains files. Run dir manually in the same terminal to confirm.

tree is not available tree.com is a built-in Windows utility and should always be available. If it is missing (rare in some stripped-down environments), the script will report a non-zero exit code and the output file will contain the error message from cmd.exe.

Garbled characters in output files Both files are written as UTF-8. Open them in an editor configured for UTF-8 (e.g., VS Code, Notepad++). Windows Notepad on older systems may require selecting the encoding manually.

---

License

This project is released into the public domain. Use, modify, and distribute freely.