FLATTREE(1) — User Commands

NAME

flattree — flatten or rebuild a directory tree with file contents. Simple CLI tool to generate or reconstruct a flat representation of a directory.

---

SYNOPSIS

Read mode (flatten a directory):

flattree read [-o OUTPUT_FILE] [-d DIRECTORY]
              [--extensions=EXT1,EXT2]
              [--strict-extensions=EXT1,EXT2]
              [-n MAX_LINES]
              [--ignore=IGNORE1,IGNORE2]

Write mode (rebuild a directory):

flattree write -i INPUT_FILE [-d OUTPUT_DIRECTORY]

---

INSTALLATION (RECOMMENDED)

🔹 Prerequisites

• Python ≥ 3.8
• pipx installed (see https://pipx.pypa.io/)

🔹 Install from GitHub

pipx install "git+https://github.com/R-Elias/flattree.git"

After installation, the command flattree is available globally:

flattree --help

🔹 Update to the latest version

pipx upgrade flattree

---

DESCRIPTION

flattree works in two distinct modes:

• READ mode

Traverses a directory and outputs a flat text file describing:

• the directory structure;
• the contents of files that match your filters.

Useful for code analysis, LLM prompts, or version snapshots.

• WRITE mode

Reads a flat file previously generated by flattree and rebuilds the full directory tree, recreating directories and files.

Existing files are overwritten by default.

---

OPTIONS

General

• read or write — choose mode.
• -d, --directory — directory to scan or restore (default: current working directory).

Read mode

• -o, --output — output file (default: stdout).
• --extensions — comma-separated list of extensions to include.
• --strict-extensions — same as above, but only exact matches (e.g. --strict-extensions=js ignores .spec.js).
• -n, --max-lines — only include file content if file ≤ N lines.
• --ignore — comma-separated list of files or directories to ignore.

Write mode

• -i, --input — flat file to rebuild from.

---

EXAMPLES

Flatten a directory:

flattree read -d ./my_project -o project.flat

Rebuild a directory from a flat file:

flattree write -i project.flat -d ./restored_project

Ignore heavy folders:

flattree read -d . --ignore=node_modules,build,dist -o output.flat

Include only .py and .js files:

flattree read --extensions=py,js -o code.flat

---

FILE FORMAT (Minimal Example)

A flat file generated by flattree is plain text divided into blocks separated by:

*----flattree-file-separator----*

Each block begins with a path — a directory (ending with /) or a file — followed by its contents if applicable.

Example of a minimal flat file

*----flattree-file-separator----*
src/
*----flattree-file-separator----*
src/main.py
print("Hello, world!")
*----flattree-file-separator----*
README.md
# Example project

When rebuilt with:

flattree write -i example.flat -d ./restored

It creates:

./restored/
├── src/
│   └── main.py
└── README.md

---

NOTES

• UTF-8 encoding is used for reading and writing.

• Ignored patterns can also be listed in a .flattreeignore file.

• Default separator between entries:

  *----flattree-file-separator----*
  

• Works on Windows, macOS, and Linux.

---

AUTHOR

Elias Aliche https://github.com/R-Elias