catdir is a simple CLI utility that traverses directories and concatenates the contents of all files within a folder and its subfolders, similar to the Unix cat command — but for entire directory trees.

This tool is particularly useful for diagnostics, debugging, packaging, or reviewing all source files in a project at once.

Install using pip:

pip install catdir

catdir [OPTIONS] PATH

catdir ./my_project --exclude .env --exclude-noise
catdir ./my_project -e .env -en
catdir ./my_project -e .env -en --output dump.txt
catdir ./my_project -e .env -en --output dump.txt --append

These commands output the contents of all readable files under ./my_project, excluding .env and commonly ignored development artifacts such as .git, node_modules, .venv, and others.

The third example writes the output to a file named dump.txt, overwriting it if it exists.
The fourth example appends the output to dump.txt instead of overwriting.

Each file is prefixed and suffixed with a marker to identify its contents:

# relative/path/to/file.py start file content
<file content here>
# end file content

If a file or directory cannot be read, the tool will emit an inline error comment with the reason.

The --exclude-noise flag excludes the following by default:

.venv, venv, .git, .idea, __pycache__, node_modules, dist, build,
.pytest_cache, .mypy_cache, .cache, .eggs, .coverage, coverage.xml,
.tox, .DS_Store, Thumbs.db, .env

To install and run locally:

git clone https://github.com/yourname/catdir.git
cd catdir
pip install -e .
catdir ./example_project --exclude-noise

We welcome PRs and ideas — see issues, or open a new one.

MIT License. See LICENSE for details.