DirMeta: Directory Metadata Scanner & Viewer

DirMeta is a command-line utility designed to scan filesystem directory structures, capture detailed metadata about files and folders, and provide both machine-readable (JSON) output saved to a file and a human-readable tree view loaded from that file. It's a general-purpose tool useful for documenting, understanding, or analyzing directory layouts.

Features

• Recursive Scan: Scans directories deeply to capture all nested files, folders, and symbolic links.
• Rich Metadata: Collects essential information:
  • Relative Path
  • Type (file, folder, symlink)
  • Permissions (standard string format)
  • Size (for files)
  • Timestamps (Modification, Access, Metadata Change, and Creation/Birth if available)
  • File Extension (for files)
  • Symlink Target (for symlinks)
• Direct JSON File Output: The scanner (structure-scan) writes the collected metadata directly to a specified or automatically named JSON file.
• Tree Viewer: The viewer (structure-view) loads a scan's JSON file and displays the structure as a formatted tree in the terminal, including key metadata for quick analysis.
• CLI Tools: Installs two easy-to-use commands: structure-scan and structure-view.
• Configurable: Options to include/exclude hidden files (. prefix) and specify the output file path.
• Pure Python: Runs on Python >= 3.7 without requiring any external libraries.
• Cross-Platform: Tested on Linux, macOS, and Windows.

Installation

It is strongly recommended to install dirmeta within a Python virtual environment to avoid conflicts with system packages.

1. Using pip

pip install dirmeta

2. Installing from Source (e.g., after cloning the repository)

# Clone the repository (if needed)
# git clone <repository_url>
# cd dirmeta

# Create and activate a virtual environment (Python 3)
python3 -m venv .venv
source .venv/bin/activate  # On Windows use `.venv\Scripts\activate`

# Install the package
pip install .

Usage

1. Scan a Directory (structure-scan)

The structure-scan command scans the specified directory path and writes the collected metadata as a JSON object to a file.

Command:

structure-scan [OPTIONS] ROOT_DIR

Arguments:

• ROOT_DIR: The path to the directory you want to scan.

Options:

• -i, --include-hidden: Include hidden files and directories (names starting with '.') in the scan. By default, they are excluded.
• -o FILE, --output FILE: Specify the path for the output JSON file. If omitted, defaults to <ROOT_DIR_NAME>.json saved in the directory containing ROOT_DIR. For example, scanning /path/to/mydata would default to saving /path/to/mydata.json. Scanning . would default to saving <CURRENT_DIR_NAME>.json in the parent directory.
• -v, --verbose: Enable debug logging (prints progress/warnings to stderr).

Examples:

# Scan the current directory (excluding hidden files).
# Output saved to '<CURRENT_DIR_NAME>.json' in the parent directory.
structure-scan .

# Scan '/var/log', including hidden files, save to 'log_scan.json' in the current directory
structure-scan --include-hidden --output log_scan.json /var/log

# Scan '~/my_project' verbosely.
# Output saved to '~/my_project.json' (assuming default output location).
structure-scan -v ~/my_project

# Scan 'data_folder' and save output inside it
structure-scan --output data_folder/scan_metadata.json data_folder

2. View Scan Results (structure-view)

The structure-view command reads a JSON file previously generated by structure-scan and displays the directory structure as a formatted tree in your terminal.

Command:

structure-view [OPTIONS] JSON_FILE

Arguments:

• JSON_FILE: The path to the JSON file created by structure-scan.

Options:

• -v, --verbose: Enable debug logging for the viewer (rarely needed).

Examples:

# View the scan results stored in 'project_scan.json'
structure-view project_scan.json

# View the log scan results
structure-view log_scan.json

Example Output (structure-view scan.json)

Scan Root: /path/to/your/directory
Scan Timestamp: 2023-10-30T12:00:00Z
Schema Version: 1.0
------------------------------------------------------------
├── .gitattributes [F] -rw-r--r-- 60 B (Mod: ...)
├── LICENSE [F] -rw-r--r-- 1.1 KB (Cre: ... | Mod: ...)
# ... rest of tree structure ...

Output JSON Schema (structure-scan output file)

The scanner produces a JSON object (written to the output file) with the following top-level keys:

• scanner_version: Version string of the schema (e.g., "1.0" based on the provided script).
• scanned_path: The absolute, resolved path of the directory that was scanned.
• timestamp_utc: ISO 8601 timestamp (UTC, with Z suffix) indicating when the scan finished.
• items: An array of objects, each representing a scanned file, folder, or symlink found within scanned_path.

Each object inside the items array contains the following fields:

• path (String): Path relative to scanned_path, using / separators. The root directory itself is represented as ..
• type (String): The type of the filesystem item: "file", "folder", or "symlink".
• permissions (String): Standard file mode string (e.g., "drwxr-xr-x", "-rw-r--r--").
• modified_utc (String | Null): ISO 8601 timestamp (UTC) of last modification, or null if unavailable.
• accessed_utc (String | Null): ISO 8601 timestamp (UTC) of last access, or null if unavailable.
• metadata_changed_utc (String | Null): ISO 8601 timestamp (UTC) of last metadata change (Unix ctime), or null if unavailable.
• created_utc (String | Null, Optional): ISO 8601 timestamp (UTC) of file creation/birth, if available on the platform/filesystem. Field may be absent if not found.
• size_bytes (Integer, Optional): Size in bytes. Only present for type: "file".
• file_extension (String | Null, Optional): Lowercase file extension without the leading dot (e.g., "txt", "pdf"). null if the file has no extension. Only present for type: "file".
• symlink_target (String | Null, Optional): The target path the symlink points to (can be relative or absolute). null if reading the target failed. Only present for type: "symlink".

License

This project is licensed under the MIT License. See the LICENSE file for details.