🌳 TreeExporter

Automatically generate beautiful repository structure diagrams from your project.

No more manually maintaining folder trees in your README.

---

Why?

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 or plain text

---

🖼 Demo

SVG

![Repository Structure](./docs/structure.svg)

Text

Look at ./docs/structure.txt.

---

🚀 Features

• Repository scanning
• SVG export
• Plain text export
• Built-in SVG themes
• Configurable excluded directories
• GitHub Actions support
• Python library API
• Fast recursive traversal

More formats are planned.

---

Installation

Using uv (recommended):

uv tool install TreeExporter

or install into the current environment:

uv add TreeExporter

Using pip:

pip install TreeExporter

---

💻 CLI

Generate a repository structure:

tree-exporter

By default, this generates:

structure.svg

Output format

Generate SVG:

tree-exporter \
    --format svg \
    --output docs/tree

Generate plain text:

tree-exporter \
    --format txt \
    --output docs/tree

The output extension is added automatically.

Themes

SVG output supports built-in themes:

tree-exporter \
    --format svg \
    --output docs/tree \
    --theme dark

Available themes:

light
dark
github-light
github-dark
dracula
monokai
nord
solarized-light
solarized-dark
one-dark

See Themes for previews.

Excluding directories

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"

Replacing default exclusions

Use --exclude-overwrite to replace the default exclusion list completely:

tree-exporter \
    --exclude-overwrite \
    --exclude ".git,.venv"

---

🎨 Themes

TreeExporter includes built-in themes for SVG output.

Choose a theme with the --theme CLI option or the theme GitHub Action input.

Light

tree-exporter --theme light

Dark

tree-exporter --theme dark

GitHub Light

tree-exporter --theme github-light

GitHub Dark

tree-exporter --theme github-dark

Dracula

tree-exporter --theme dracula

Monokai

tree-exporter --theme monokai

Nord

tree-exporter --theme nord

Solarized Light

tree-exporter --theme solarized-light

Solarized Dark

tree-exporter --theme solarized-dark

One Dark

tree-exporter --theme one-dark

The default theme is light.

---

GitHub Actions

TreeExporter can automatically generate and update your repository structure using GitHub Actions.

Basic usage

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 push

This will generate docs/structure.svg and commit it when the repository structure changes.

Action inputs

Input	Default	Description
path	.	Repository path to scan
output	structure	Output path without extension
format	svg	Export format: svg or txt
theme	light	SVG theme
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

Using a theme

For example, generate a dark-themed structure:

- name: Generate repository structure
  uses: mrf0rtuna4/TreeExporter@v0.2.0
  with:
    format: svg
    output: docs/structure
    theme: dark

Or use Dracula:

- name: Generate repository structure
  uses: mrf0rtuna4/TreeExporter@v0.2.0
  with:
    format: svg
    output: docs/structure
    theme: dracula

Excluding directories

Additional 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"

Complete example

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 push

---

Library

TreeExporter can also be used directly from Python.

from tree_exporter.config import ScanConfig
from tree_exporter.scanner import scan_repository

tree = scan_repository(
    ".",
    ScanConfig(),
)

---

Roadmap

• ✅ Repository scanning
• ✅ Text export
• ✅ SVG export
• ✅ GitHub Action
• ✅ Built-in themes
• 🚧 Mermaid export
• 🚧 JSON export
• 🚧 PNG export
• 🚧 Custom icons
• 🚧 Ignore file support

---

License

See the LICENSE file for details.