findfmt 0.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

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 -l -t python

# Print summary statistics to stderr
findfmt -s

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 Information
• Accessibility Statement

7. License

MIT License © 2026 Brandon Perkins.