TreeExporter
ActionsTags
(1)Automatically generate beautiful repository structure diagrams from your project.
No more manually maintaining folder trees in your README.
Keeping a repository structure up to date is surprisingly annoying.
Every time files or folders change, developers have to manually edit the tree inside the documentation:
src
├── api
├── models
├── utils
└── ...
Which quickly becomes outdated.
TreeExporter scans your project and generates a clean, automatically updated visualization instead.
It can be:
- updated automatically with GitHub Actions
- used as a Python library
- used as a CLI tool
- exported to SVG, JSON or plain text
Look at ./docs/structure.txt.
- Repository scanning
- SVG export
- Plain text export
- JSON export
- Custom SVG icons for directories and files
- Built-in SVG themes
- Configurable excluded directories
- GitHub Actions support
- Python library API
- Fast recursive traversal
More formats are planned.
Using uv (recommended):
uv tool install TreeExporteror install into the current environment:
uv add TreeExporterUsing pip:
pip install TreeExporterGenerate a repository structure:
tree-exporterBy default, this generates:
structure.svg
Generate SVG:
tree-exporter \
--format svg \
--output docs/treeGenerate plain text:
tree-exporter \
--format txt \
--output docs/treeGenerate structured JSON:
tree-exporter \
--format json \
--output docs/treeThe output extension is added automatically. JSON contains each node's name, type, and recursively ordered children.
SVG output supports built-in themes:
tree-exporter \
--format svg \
--output docs/tree \
--theme darkSVG labels use folder and file emojis by default. Replace either icon with any text or emoji:
tree-exporter \
--directory-icon "🗂️" \
--file-icon "📝"Available themes:
light
dark
github-light
github-dark
dracula
monokai
nord
solarized-light
solarized-dark
one-dark
See Themes for previews.
Add directories to the default exclusion list:
tree-exporter \
--exclude ".venv,dist,build"You can also repeat the option:
tree-exporter \
--exclude ".venv,dist" \
--exclude "coverage,node_modules"Use --exclude-overwrite to replace the default exclusion list completely:
tree-exporter \
--exclude-overwrite \
--exclude ".git,.venv"TreeExporter can automatically generate and update your repository structure using GitHub Actions.
The simplest setup is:
name: Generate repository structure
on:
workflow_dispatch:
push:
branches:
- master
permissions:
contents: write
jobs:
generate:
runs-on: ubuntu-latest
steps:
- name: Generate repository structure
uses: mrf0rtuna4/TreeExporter@v0.2.0
with:
format: svg
output: docs/structure
- name: Commit and push
shell: bash
run: |
git config user.name "github-actions[bot]"
git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
git add -A
if git diff --cached --quiet; then
echo "Repository structure is up-to-date."
exit 0
fi
git commit -m "Update repository structure"
git pushThis will generate docs/structure.svg and commit it when the repository structure changes.
| Input | Default | Description |
|---|---|---|
path |
. |
Repository path to scan |
output |
structure |
Output path without extension |
format |
svg |
Export format: svg, txt, or json |
theme |
light |
SVG theme |
directory-icon |
📁 |
Directory icon in SVG output |
file-icon |
📄 |
File icon in SVG output |
exclude |
"" |
Additional excluded directories, separated by commas |
exclude-overwrite |
false |
Replace default exclusions instead of extending them |
commit |
false |
Commit generated files |
commit-message |
Update repository structure |
Commit message |
branch |
"" |
Target branch |
For example, generate a dark-themed structure:
- name: Generate repository structure
uses: mrf0rtuna4/TreeExporter@v0.2.0
with:
format: svg
output: docs/structure
theme: darkOr use Dracula:
- name: Generate repository structure
uses: mrf0rtuna4/TreeExporter@v0.2.0
with:
format: svg
output: docs/structure
theme: draculaAdditional exclusions can be configured directly in the Action:
- name: Generate repository structure
uses: mrf0rtuna4/TreeExporter@v0.2.0
with:
format: svg
output: docs/structure
exclude: ".venv,dist,build,node_modules"To completely replace the default exclusions:
- name: Generate repository structure
uses: mrf0rtuna4/TreeExporter@v0.2.0
with:
format: svg
output: docs/structure
exclude-overwrite: "true"
exclude: ".git,.venv"A more complete workflow can look like this:
name: Generate repository map
on:
workflow_dispatch:
push:
branches:
- master
permissions:
contents: write
jobs:
generate:
runs-on: ubuntu-latest
steps:
- name: Checkout code
uses: actions/checkout@v7
with:
fetch-depth: 0
- name: Generate repository structure
uses: mrf0rtuna4/TreeExporter@v0.2.0
with:
format: svg
output: docs/structure
theme: dark
exclude: ".venv,dist,build"
- name: Commit and push
shell: bash
run: |
git config user.name "github-actions[bot]"
git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
git add -A
if git diff --cached --quiet; then
echo "Repository structure is up-to-date."
exit 0
fi
git commit -m "Update repository structure"
git pushTreeExporter can also be used directly from Python.
from tree_exporter.config import ScanConfig
from tree_exporter.scanner import scan_repository
tree = scan_repository(
".",
ScanConfig(),
)- ✅ Repository scanning
- ✅ Text export
- ✅ SVG export
- ✅ GitHub Action
- ✅ Built-in themes
- 🚧 Mermaid export
- ✅ JSON export
- 🚧 PNG export
- ✅ Custom icons
- 🚧 Ignore file support
- 🧠 Interactive HTML export with collapsible directories
- 🧠 Per-file language icons and syntax-aware colors
- 🧠 Git diff mode for structural changes between revisions
- 🧠 Project config file for reusable defaults
See the LICENSE file for details.
TreeExporter is not certified by GitHub. It is provided by a third-party and is governed by separate terms of service, privacy policy, and support documentation.
Tags
(1)TreeExporter is not certified by GitHub. It is provided by a third-party and is governed by separate terms of service, privacy policy, and support documentation.