Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/caffienerd/struct-cli

struct is a smarter tree command built in Rust, focused on presenting clean, meaningful project structure instead of drowning users in dependency directories, build artifacts, and cache clutter. With intelligent ignore defaults, configurable filtering, git-aware views, file size insights, and pattern-based search and struct prioritizes clarity.
https://github.com/caffienerd/struct-cli

cli developer-tools filesystem git linux open-source rust terminal terminal-based tree tree-command utilities

Last synced: about 1 month ago
JSON representation

struct is a smarter tree command built in Rust, focused on presenting clean, meaningful project structure instead of drowning users in dependency directories, build artifacts, and cache clutter. With intelligent ignore defaults, configurable filtering, git-aware views, file size insights, and pattern-based search and struct prioritizes clarity.

Awesome Lists containing this project

README 

          
# struct



Struct: tree with a developer brain.

Stop drowning in site-packages — struct shows you the code you care about.



## The Problem



Running `tree` in a project directory gives you this:



```bash

$ tree -L 3

venv/

├── lib/

│   ├── python3.11/

│   │   ├── site-packages/

│   │   │   ├── pip/

│   │   │   │   ├── __init__.py

│   │   │   │   ├── ... (2000+ files you didn't ask for)

```



I needed something that shows project structure without drowning me in dependency folders.



## What This Does



`struct` shows your project's actual structure while automatically hiding the noise:



```bash

$ struct 3

venv/ (2741 files ignored)

src/

├── main.rs

└── lib.rs

```



The folder still appears, but you get a clean file count instead of thousands of irrelevant paths.



## Installation



### Option 1: Install from crates.io

```bash

cargo install struct-cli

```



View on [crates.io](https://crates.io/crates/struct-cli)



### Option 2: Install from source

```bash

git clone https://github.com/caffienerd/struct-cli.git

cd struct-cli

chmod +x install.sh && ./install.sh

```



## Uninstallation



```bash

git clone https://github.com/caffienerd/struct-cli.git && cd struct-cli

chmod +x uninstall.sh && ./uninstall.sh

```



---



## Quick Start



```bash

struct                          # Full tree (current dir, infinite depth)

struct 0                        # Detailed summary of current directory

struct 3                        # 3 levels deep

struct ~/dir                    # Full tree of a specific directory

struct 2 ~/dir                  # Specific directory, 2 levels deep

struct ~/dir 2                  # Same — order doesn't matter

struct 5 ~/dir -z               # 5 levels with file sizes

```



---



## Complete Usage Guide



### Syntax



```

struct [DEPTH] [PATH] [FLAGS]

struct search "PATTERN" [PATH] [DEPTH] [FLAGS]

struct 0 [PATH]                       → detailed summary view

```



Both `DEPTH` and `PATH` are optional positional arguments — no flags needed.

Order doesn't matter: `struct 2 ~/dir` and `struct ~/dir 2` both work.



---



### struct 0 — Directory Summary Mode



```bash

struct 0

struct 0 ~/projects

```



**Output:**

```

/home/user/projects/myproject (main)



src/

  /home/user/projects/myproject/src

  total:    10 dirs · 45 files · 125.3K

  visible:  8 dirs · 42 files · 120.1K

  types:    rs(30) toml(5) md(3) json(2) txt(2)

  ignored:  target(948 files)



README.md

  12.5K



── ignored (top level) ──

  .git(60 files), target(948 files) · 1008 files · 45.2M

```



---



### Git Integration



Filter output by git status. All git flags can be combined with any other flag.



When multiple git flags conflict, priority is: `--gc` > `--gs` > `--gu` > `-g` > `--gh`



#### `-g, --git` — tracked files only

```bash

struct -g

struct 2 -g ~/git-project

```



#### `--gu` — untracked files only

```bash

struct --gu

struct 2 --gu ~/git-project

```



#### `--gs` — staged files only

```bash

struct --gs

```



#### `--gc` — changed/modified files only

```bash

struct --gc

```



#### `--gh` — last commit per directory

```bash

struct --gh

```



#### Root variants — start from git root regardless of current directory

```bash

struct --gr        # tracked, from git root

struct --gur       # untracked, from git root

struct --gsr       # staged, from git root

struct --gcr       # changed, from git root

struct --ghr       # history, from git root

```



**Examples:**

```bash

struct 3 -g -z                  # Tracked files with sizes

struct --gcr ~/git-project/myapp   # Changed files from repo root

struct 2 --gur                  # Untracked files from git root, 2 levels

```



---



### Flags



#### `-z, --size` — show file sizes

```bash

struct -z

struct 3 -z ~/dir

```



**Output:**

```

main.rs (8.5K)

venv/ (156.3M, 2741 files ignored)

```



#### `-s, --skip-large SIZE` — skip large directories

```bash

struct -s 100                   # Skip dirs > 100MB

struct 3 -s 500 ~/dir

```



#### `-i, --ignore PATTERNS` — inline ignore patterns

Comma-separated, wildcards supported. Merged with config patterns.



```bash

struct -i "*.log"

struct -i "*.tmp,cache*,build"

struct 3 ~/dir -i "*.log,screenshots"

```



#### `-n, --no-ignore TARGET` — un-ignore

Show things that are normally hidden. Can be given multiple times.



| Value | Effect |

|---|---|

| `all` | Disable ALL ignores |

| `defaults` | Disable built-in defaults (venv, node_modules, etc.) |

| `config` | Disable config file patterns only |

| `PATTERN` | Un-ignore one specific name (e.g. `venv`, `__pycache__`) |



```bash

struct -n all                       # Show everything

struct -n defaults                  # Show venv, __pycache__, etc.

struct -n config                    # Show config-ignored items

struct -n venv                      # Peek inside venv only

struct -n __pycache__               # Show __pycache__ contents

struct -n defaults -n config        # Same as -n all

```



---



### Config File Management



Save ignore patterns permanently so you don't have to type `-i` every time.



**Location:** `~/.config/struct/ignores.txt`



```bash

struct add "chrome_profile"     # Add a pattern

struct add "*.log"

struct remove "*.log"           # Remove a pattern

struct list                     # Show all saved patterns

struct clear                    # Delete all saved patterns

```



**Output of `struct list`:**

```

custom ignore patterns:

  chrome_profile

  *.log



config file: /home/user/.config/struct/ignores.txt

```



---



### Search



Find files and directories by pattern. Respects the same ignore rules as the tree view.



```

struct search "PATTERN" [PATH] [DEPTH] [FLAGS]

```



**Pattern matching rules:**

- **Plain text** (no `*` or `?`) → case-insensitive **substring** match

  - `search "gui"` finds `gui.py`, `gui_utils.rs`, `penguin.txt`

  - `search "cache"` finds `__pycache__`, `.cache`, `cache.json`

- **Glob patterns** (has `*` or `?`) → exact glob match

  - `search "*.py"` finds only files ending in `.py`

  - `search "test*"` finds files starting with `test`



**Basic examples:**

```bash

struct search "*.py"                    # All Python files (current dir)

struct search "gui"                     # Anything containing "gui"

struct search "__pycache__"             # Find all __pycache__ dirs

struct search "*.env" ~/dir        # .env files in ~/dir

struct search "config*" ~/dir 2    # Files starting with "config", 2 levels deep

```



**Search flags:**



#### `[DEPTH]` — limit search depth (positional, default: infinite)

```bash

struct search "*.py" . 2                # 2 levels deep

struct search "*.toml" ~/dir 1     # Top level only

```



#### `-f, --flat` — flat list instead of tree

```bash

struct search "*.py" -f

struct search "*.env" ~/dir -f

```



**Tree output (default):**

```

found 6 item(s) matching *.py



timebomb/

└── Linux/

    └── python/

        ├── app_manager.py (11.1K)

        ├── gui.py (19.4K)

        └── timer.py (18.5K)

```



**Flat output (`-f`):**

```

found 6 item(s) matching *.py



timebomb/Linux/python/app_manager.py (11.1K)

timebomb/Linux/python/gui.py (19.4K)

timebomb/Linux/python/timer.py (18.5K)

```



#### `-i, --ignore PATTERNS` — ignore patterns during search

```bash

struct search "*.wav" . -i "windows"

struct search "*.py" ~/dir -i "venv,__pycache__"

```



---



## Auto-Ignored Directories



These are hidden by default (shown with file count instead):



**Python:** `__pycache__`, `.pytest_cache`, `.mypy_cache`, `venv`, `.venv`, `env`, `virtualenv`, `*.egg-info`, `dist`, `build`



**JavaScript:** `node_modules`, `.npm`, `.yarn`



**Version Control:** `.git`, `.svn`, `.hg`



**IDEs:** `.vscode`, `.idea`, `.obsidian`



**Build Artifacts:** `target`, `bin`, `obj`, `.next`, `.nuxt`



**Caches:** `chrome_profile`, `GPUCache`, `ShaderCache`, `Cache`, `blob_storage`



**macOS:** `.DS_Store`



Use `-n all` to show everything, or `-n PATTERN` to peek at one specific folder.



---



## Real-World Examples



```bash

# Check project structure without clutter

struct 3 ~/myproject



# Find all config files in current dir

struct search "*.env"

struct search "config" . 2



# See what's actually tracked in git

struct 2 -g



# Peek inside an ignored folder

struct -n venv

struct -n node_modules



# Find large folders

struct -z                       # Show all sizes

struct -s 100                   # Skip folders > 100MB



# Search with flat output for piping

struct search "*.py" -f | grep test



# Find __pycache__ dirs across your project

struct search "__pycache__" ~/dir -f



# Git: see what you're about to commit

struct --gsr                    # Staged files from repo root

```



---



## Features



- **Clean by default**: hides noise (venv, node_modules, .git, caches, build artifacts)

- **Smart search**: substring match for plain text, glob match for patterns with wildcards

- **Git integration**: filter to tracked / untracked / staged / changed files

- **Size awareness**: show sizes with `-z`, skip large dirs with `-s`

- **Configurable ignores**: save patterns permanently with `struct add`

- **Flexible output**: tree or flat format for search

- **Color-coded**: directories in blue, executables in green

- **Fast**: written in Rust



---



## Why Rust



Started as a learning project. Turned out to be genuinely useful, so it got polished up. The performance is a nice bonus.



## Contributing



Found a bug? Want a feature? Open an issue. PRs welcome.



Drop a star if you find it useful — it helps!



## License



MIT