findfmt 1.1.0

A .gitignore-aware file discovery and classification suite that locates files by content format, shebang, and MIME tag for automated linting, formatting, and CI pipelines.

1. Why findfmt?

Unlike traditional find or globbing tools that rely strictly on file extensions, findfmt:

• Understands file content: Identifies format by content, shebang (#!/usr/bin/env python3), and MIME types using the identify engine.
• Respects Git: Traverses trees hierarchically while pruning .gitignore and .git/info/exclude paths early before descending into large directories (e.g. node_modules/, .venv/).
• Deterministic: Always returns clean, relative, deterministically sorted paths optimized for subshells, xargs, and automation.

2. Installation

findfmt requires Python 3.11 or newer and is tested on Python 3.11 through 3.15 on Linux, macOS, and Windows. On Python 3.10, pin the 1.0 series with findfmt<1.1; see Upgrading to 1.1.

2.1. With uv (Recommended)

Run directly with uvx:

uvx findfmt --help

Install globally:

uv tool install findfmt

Or add to your project:

uv add findfmt

2.2. With pip

pip install findfmt

2.3. With Docker / Container

docker pull ghcr.io/bdperkin/findfmt:latest
docker run --rm -v "$(pwd)":/workspace -w /workspace ghcr.io/bdperkin/findfmt:latest -t python

3. Usage

3.1. Locate Files by Tag / Format

# Locate all Python files
findfmt -t python

# Locate all YAML and JSON files
findfmt -t yaml,json

# Locate shell scripts
findfmt -t shell

3.2. Shebang Filtering

# Locate files with bash shebang
findfmt --shebang bash

# Locate scripts executing with python
findfmt --shebang python

3.3. Pipe Safely to Linters and Tools

Use -0 for NUL-delimited output with xargs -0:

# Format discovered Python files
findfmt -t python -0 | xargs -0 ruff format

# Lint shell scripts with shellcheck
findfmt -t shell -0 | xargs -r -0 shellcheck

3.4. Inspect Tags & Summaries

# Print matched files and their classification tags
findfmt --list-tags -t python

# Print summary statistics to stderr
findfmt -s

3.5. Structured Data Serialization

Export discovery results to machine-readable formats for pipelines, analysis, and notebooks:

# Export JSON array of file metadata and filter with jq
findfmt -t python --format json | jq '.[] | .path'

# Stream NDJSON (one JSON record per line)
findfmt -f jsonl

# Generate clean YAML document
findfmt -t yaml -f yaml

# Generate Jupyter Notebook with pandas DataFrame ingestion
findfmt -f ipynb > discovery.ipynb

# Export CSV with header row and process with csvkit
findfmt -f csv | csvcut -c path,tags,size_bytes

# Render aligned CSV table in terminal
findfmt -f csv-table --table-style rounded

# Generate Markdown table
findfmt -t python -f markdown

3.6. File Metadata & Presentation Options

Inspect extended Unix-style attributes and customize file presentation:

# Print permissions, ownership, and human-readable sizes
findfmt -p -u -g -h

# Print modification timestamps, sizes, and file type classification indicators
findfmt -D -h -F

# View accumulated recursive directory disk usage in a hierarchical tree
findfmt --tree --du -h

# Print filenames in double quotes, escaping embedded quotes and non-printables
findfmt -Q -q

3.7. Command Aliases & Entry Points

findfmt installs dedicated executable wrappers for frequent operations:

3.8. Programmatic Python Library Usage

Integrate findfmt directly into Python scripts and automated pipelines:

from findfmt import FileInfo, TraversalConfig, find_files, get_formatter

# Configure traversal scope and format filtering
config = TraversalConfig(include_tags={"python"}, root_paths=["src"])

# Discover matching files as FileInfo objects
for file_info in find_files(config):
    print(f"{file_info.path}: {file_info.tags} ({file_info.size_bytes} bytes)")

# Format results using any built-in serializer (e.g. table, json, tree, yaml)
formatter = get_formatter("table")
print(formatter.format(find_files(config)))

4. CLI Options

5. Development & Testing

This project enforces 100% test coverage and strict type checking:

# Clone the repository
git clone https://github.com/bdperkin/findfmt.git
cd findfmt

# Install dependencies with uv
uv sync --all-groups

# Run tests and verify 100% coverage
uv run pytest

# Run linting and typing
uv run ruff check
uv run ty check

# Run full verification suite
uv run python tools/verify_quality.py

6. Governance & Community

• Contributing Guidelines
• Code of Conduct
• Security Policy
• Support Guide
• Accessibility Statement
• Changelog
• Documentation & User Guides
• Upgrading to 1.1

7. License

MIT License © 2026 Brandon Perkins.