filetype-stats

A CLI tool to visualize the distribution of file types and disk usage in a directory, built with Rich and Typer.

It's helpful to get a picture of all the different filetypes in a directory along with their disk usage, to inform what needs to be added to .gitignore or .gitattributes (for Git LFS). This was the original use-case for this tool.

Features

• Tables: Output with icons for common file types.
• Scanning: Directory scanning with a progress bar.
• Tree View: Hierarchical view of file types.
• Example Files: Lists files contributing to each category.
• JSON Export: Save statistics to JSON.
• Filtering: Options to include/exclude hidden files and limit results.

Installation

Clone the repository and install using uv:

git clone <repository_url>
cd filetype-stats
uv tool install .

Usage

Run the tool in the current directory:

filetype-stats analyze

Analyze a specific directory:

filetype-stats analyze /path/to/directory

CLI Reference

Arguments:

• DIRECTORY: The directory to analyze. Defaults to the current directory (.).

Options:

• --max-ext-length INTEGER: Maximum length for valid file extensions. Default is 10.
• --include-hidden: Include hidden files and directories in the analysis. Default is False (hidden files are ignored).
• --sort [size|count|name]: Sort results by total size, file count, or extension name. Default is size.
• --top INTEGER: Show only the top N file types. If not specified, shows all found types.
• --show-examples: Show example files (up to 3) for each file type in the table. Default is False.
• --tree: Display results as a tree view instead of a table. Default is False.
• --export-json TEXT: Export the analysis results to a JSON file at the specified path.

Example with complex options:

filetype-stats analyze ./src --include-hidden --max-ext-length 5 --sort count --export-json stats.json

Why does filetype-stats say something different to du?

• First check that you have --include-hidden on. filetype-stats ignores hidden files and directories by default, while du by default includes everything.

• Any additional discrepancy between sizes reported by du vs filetype-stats is because du and filetype-stats measure different things.

  • du reports disk usage including block size overhead, blocks taken up by directories, and any files system metadata
  • os.path.getsize() reports actual file size — just the actual number of bytes taken up by each file, ignoring block size overhead. For this reason, du will always report larger sizes than filetype-stats