CLI tool to flatten directory structures: merge files into a single Markdown file (default) or copy/move to a flat directory with escaped filenames. Respects .gitignore, supports move/overwrite, and more.
npm install flatten-tool
A CLI utility to flatten directory structures, with perfect GitHub Flavored Markdown compatibility including explicit HTML anchors for maximum portability.
Watch the YouTube video for an example of why you might need to flatten project files into a single document for AI discussions and code reviews.
Requires Bun runtime (v1.1+).
``bash`
npm install -g flatten-tool
You can run flatten-tool directly without installing:
`bash`
npx flatten-tool [args]
bunx flatten-tool [args]
#### With devenv (recommended)
Clone the repository and enter the development environment:
`bash`
git clone https://github.com/MBanucu/flatten-tool.git
cd flatten-tool
devenv shell
Inside the devenv shell, dependencies are managed automatically. Run the tool with:
`bash`
bun run index.ts [args]
#### Without devenv
Clone the repository and install dependencies:
`bash`
git clone https://github.com/MBanucu/flatten-tool.git
cd flatten-tool
bun install
Run directly with Bun:
`bash`
bun run index.ts [args]
By default, the tool merges all file contents into a single Markdown file, starting with a project file tree for navigation, followed by each file's content under a header with its full relative path, in a code block with appropriate language highlighting based on the file extension. The tree includes clickable links to file sections using GitHub-compatible anchors. Ignores and filters are applied as usual.
The argument is optional and defaults to the current directory (.). The argument is also optional and defaults to flattened.md (or flattened/ when using --directory).
- --clipboard, -c: Copy the generated Markdown content to clipboard (only for Markdown mode).--directory
- , -d: Flatten to individual files in a directory instead of merging to Markdown.--dry-run
- , -n: Preview changes without modifying the filesystem.--move
- , -m: Move files instead of copying (original files will be deleted).--overwrite
- , -o: Overwrite existing target files.--gitignore
- , -g: Respect .gitignore files (default: true). Use --no-gitignore to disable.--help
- , -h: Show help.--version
- , -v: Show version.
Flatten current directory to flattened.md:
`bash`
flatten-tool
Flatten a specific directory to flattened.md:
`bash`
flatten-tool /path/to/source
Flatten current directory to a custom Markdown file:
`bash`
flatten-tool output.md
Flatten a specific directory to a custom Markdown file:
`bash`
flatten-tool /path/to/source output.md
Flatten to individual files in a directory:
`bash`
flatten-tool --directory
This creates a flattened/ directory with flattened files.
Flatten a specific directory to a custom output directory:
`bash`
flatten-tool /path/to/source output-dir --directory
Move files instead of copying:
`bash`
flatten-tool --move
Overwrite existing files:
`bash`
flatten-tool --overwrite
Combine options:
`bash`
flatten-tool /path/to/source output.md --move --overwrite
Flatten current directory to Markdown and copy to clipboard:
`bash`
flatten-tool --clipboard
Preview flattening without changes:
`bash`
flatten-tool --dry-run
Run all tests:
`bash`
unittest # If using devenv
bun unittest # Otherwise
Run tests in watch mode:
`bash`
bun test --watch
Run a specific test:
`bash`
bun test -t "flattens a simple nested directory"
This project uses Bun for runtime, TypeScript for type safety, and follows the guidelines in AGENTS.md for coding standards.
When using devenv, the following scripts are available:
- check: Format + lint in one goformat
- : Format code with Biomelint
- : Run Biome lintunittest
- : Run all tests with Bun
See CHANGELOG.md for a full list of changes.
This project was created using bun init` in bun v1.3.8. Bun is a fast all-in-one JavaScript runtime.