🌳❌ Treex

简体中文

Treex is a powerful command-line tool for displaying directory structures in different formats. It offers multiple output formats and flexible filtering options, making it easy to visualize and explore your project layout.

✨ Features

• 🎨 Multiple output formats:
  • 🌲 tree: Tree format (default)
  • 📑 indent: Indented list format
  • 📝 md: Markdown format
  • 📊 mermaid: Mermaid format
  • 🔗 json: JSON format
  • 📊 csv: CSV format
• 🔍 Flexible filtering options:
  • 🕵️ -H: Hide hidden files and directories
  • 📁 -D: Show directories only
  • 🚫 -e <rules>: Exclude specific directories or file extensions
  • 📝 -I: Automatically apply .gitignore rules
• 🛠️ Customizable output:
  • 📏 -m <depth> or -L <depth>: Control directory depth
  • 💾 -o <path>: Save output to a file
  • 🎯 -f <format>: Select output format
  • ⭐ -C: Show icons for files (via emoji)
• 📊 File metadata display:
  • 📏 -s: Show file sizes (human-readable format)
  • 👤 -O: Show file owners
  • 🕐 -M: Show file modification times
• 🔧 Enhanced compatibility:
  • 🌍 Improved Windows pipe support with UTF-8 encoding
  • 🎯 -L as alias for -m for better tree command compatibility

📦 Installation

Download the pre-built binary from the releases page and add it to your PATH.

Or, if you want to build it yourself with Go:

go install github.com/shiquda/treex@latest

For windows user, you can use scoop to install treex:

scoop bucket add extras
scoop install treex

📖 Usage

Basic usage:

treex -d <directory>

To generate a tree for the current directory, simply run:

treex

⚙️ Full Options

You can run treex -h to see the help message.

All command-line options are listed in the table below:

Short Option	Long Option	Argument	Description	Default Value
-d	--dir	<directory>	Directory to scan	.
-f	--format	<format>	Output format (tree, indent, md, mermaid, json, csv)	tree
-m	--max-depth	<number>	Maximum directory depth (0 for unlimited)	-
-L	--level	<number>	Maximum directory depth (0 for unlimited, alias for -m)	-
-s	--size	-	Show file sizes (human-readable format)	false
-O	--owner	-	Show file owners	false
-M	--modtime	-	Show file modification times	false
-o	--output	<filepath>	Path to output file	stdout
-e	--exclude	<rules>	Exclude rules (comma-separated: dir/ for dirs, .ext for extensions)	-
-H	--hide-hidden	-	Hide hidden files and directories	false
-D	--dirs-only	-	Show directories only	false
-I	--use-gitignore	-	Exclude files/directories based on .gitignore	false
-C	--icons	-	Show file type icons	false

Format options details:

• tree: Tree structure with branches
• indent: Indented list format
• md: Markdown format
• mermaid: Mermaid format for diagrams
• json: JSON format with structured data
• csv: CSV format for spreadsheet applications

Exclude rules format:

• dir/: Exclude directories matching the specified name
• .ext: Exclude files with the specified extension

📚 Examples

The following examples use the same directory structure.

1. Without hidden files, save output as markdown format:

treex -H -f md -o structure.md

• -H: Hide hidden files and directories
• -f md: Output in Markdown format
• -o structure.md: Save output to structure.md file

Result:

Then in ./structure.md:

- ./
  - 1.go
  - 2.go
  - README.md
  - build/
    - win/
      - output.exe
  - test/
    - 3.go
    - README_test.md

2. Use .gitignore rules to exclude files:

.gitignore:

build/

Run:

treex -IH

• -I: Exclude files/directories based on .gitignore
• -H: Hide hidden files and directories

This will automatically read the .gitignore file in the current directory and exclude matching files and directories.

Result:

.
├── 1.go
├── 2.go
├── README.md
└── test
    ├── 3.go
    └── README_test.md

3. Generate mermaid diagram for visible directories only:

treex -HD -f mermaid

• -H: Hide hidden files and directories
• -D: Show directories only
• -f mermaid: Output in Mermaid diagram format

Result:

graph TD
    N1[./]
    N2[build/]
    N1 --> N2
    N3[win/]
    N2 --> N3
    N4[test/]
    N1 --> N4

Loading

4. Exclude specific directories or extensions:

treex -e ".git/, .md"

• -e ".git/, .md": Exclude .git directory and files with .md extension

Result:

.
├── .gitignore
├── 1.go
├── 2.go
├── build
│   └── win
│       └── output.exe
└── test
    └── 3.go

5. Show files up to depth 2 in indent mode:

treex -m 2 -f indent

• -m 2: Show files up to depth 2
• -f indent: Output in indented list format

Result:

./
    .git/
        HEAD
        config
        description
        hooks/
        info/
        objects/
        refs/
    .gitignore
    1.go
    2.go
    README.md
    build/
        win/
    test/
        3.go
        README_test.md

6. Display the file structure with icons (using a real project structure as an example):

treex -CHI -m 3

• -C: Show file type icons
• -H: Hide hidden files and directories
• -I: Exclude files/directories based on .gitignore
• -m 3: Show files up to depth 3

Result:

📁 ./
├── 📝 CODE_OF_CONDUCT.md
├── 📝 CONTRIBUTING.md
├── 📄 LICENSE
├── 📝 README.md
├── 📁 build/
│   ├── 📄 entitlements.mac.plist
│   ├── 📄 icon.icns
│   ├── 📄 icon.ico
│   ├── 🖼️ icon.png
│   ├── 📁 icons/
│   │   ├── 🖼️ 1024x1024.png
│   │   ├── 🖼️ 128x128.png
│   │   ├── 🖼️ 16x16.png
│   │   ├── 🖼️ 24x24.png
│   │   ├── 🖼️ 256x256.png
│   │   ├── 🖼️ 32x32.png
│   │   ├── 🖼️ 48x48.png
│   │   ├── 🖼️ 512x512.png
│   │   └── 🖼️ 64x64.png
│   ├── 🖼️ logo.png
│   ├── 📄 nsis-installer.nsh
│   ├── 🖼️ tray_icon.png
│   ├── 🖼️ tray_icon_dark.png
│   └── 🖼️ tray_icon_light.png
├── ⚙️ dev-app-update.yml
├── 📁 docs/
│   ├── 📝 README.ja.md
│   ├── 📝 README.zh.md
│   ├── 📝 dev.md
│   ├── 📝 sponsor.md
│   └── 📁 technical/
│       └── 📝 KnowledgeService.md
├── ⚙️ electron-builder.yml
├── 📜 electron.vite.config.ts
├── 📄 eslint.config.mjs
├── 📋 package.json
├── 📁 packages/
│   ├── 📁 artifacts/
│   │   ├── 📝 README.md
│   │   ├── 📋 package.json
│   │   └── 📁 statics/
│   ├── 📁 database/
│   │   ├── 📝 README.md
│   │   ├── 📁 data/
│   │   ├── 📋 package.json
│   │   ├── 📁 src/
│   │   └── 📄 yarn.lock
│   └── 📁 shared/
│       ├── 📜 IpcChannel.ts
│       └── 📁 config/
├── 📁 resources/
│   ├── 📁 cherry-studio/
│   │   ├── 🌐 license.html
│   │   └── 🌐 releases.html
│   ├── 📁 data/
│   │   └── 📋 agents.json
│   ├── 📁 js/
│   │   ├── 📜 bridge.js
│   │   └── 📜 utils.js
│   ├── 📁 scripts/
│   │   ├── 📜 download.js
│   │   ├── 📜 install-bun.js
│   │   └── 📜 install-uv.js
│   └── 📄 textMonitor.swift
├── 📁 scripts/
│   ├── 📜 after-pack.js
│   ├── 📜 build-npm.js
│   ├── 📜 check-i18n.js
│   ├── 📜 check-i18n.ts
│   ├── 📜 cloudflare-worker.js
│   ├── 📜 notarize.js
│   ├── 📜 remove-locales.js
│   ├── 📜 replace-spaces.js
│   ├── 📜 update-i18n.ts
│   ├── 📜 utils.js
│   └── 📜 version.js
├── 📁 src/
│   ├── 📁 components/
│   ├── 📁 main/
│   │   ├── 📜 config.ts
│   │   ├── 📜 constant.ts
│   │   ├── 📜 electron.d.ts
│   │   ├── 📁 embeddings/
│   │   ├── 📜 env.d.ts
│   │   ├── 📜 index.ts
│   │   ├── 📁 integration/
│   │   ├── 📜 ipc.ts
│   │   ├── 📁 loader/
│   │   ├── 📁 mcpServers/
│   │   ├── 📁 reranker/
│   │   ├── 📁 services/
│   │   └── 📁 utils/
│   ├── 📁 preload/
│   │   ├── 📜 index.d.ts
│   │   └── 📜 index.ts
│   └── 📁 renderer/
│       ├── 🌐 index.html
│       └── 📁 src/
├── 📋 tsconfig.json
├── 📋 tsconfig.node.json
├── 📋 tsconfig.web.json
└── 📄 yarn.lock

7. Show file metadata with JSON output:

treex -sM -f json -o structure.json

• -s: Show file sizes
• -M: Show modification times
• -f json: Output in JSON format
• -o structure.json: Save to structure.json file

Result:

{
  "name": "./",
  "isDir": true,
  "depth": 0,
  "size": 4096,
  "modTime": "2024-01-15 10:30:00",
  "children": [
    {
      "name": "README.md",
      "isDir": false,
      "depth": 1,
      "size": 11764,
      "modTime": "2024-01-15 10:30:00"
    },
    {
      "name": "src",
      "isDir": true,
      "depth": 1,
      "size": 4096,
      "modTime": "2024-01-15 10:30:00",
      "children": [
        {
          "name": "main.go",
          "isDir": false,
          "depth": 2,
          "size": 3720,
          "modTime": "2024-01-15 10:30:00"
        }
      ]
    }
  ]
}

📝 To Do

• Support config file, allow user to customize the default output format, filtering options, styles etc.
• Better performance for large directory trees
• Better way to show file/dir types
• Streamline installation process for MacOS & Linux systems(help needed!)
• And more! Tell me in issues if you have any ideas.

♥️ Contribution

The project is in its early stages of development. All contributions are welcome, including raising issues, submitting pull requests, or giving the project a ⭐ star on GitHub!

⭐ Star History