🌲 Tree Navigator

License & Philosophy

This project is licensed under the Mozilla Public License, v. 2.0. See the LICENSE file for details.

SPDX-License-Identifier: CC-BY-SA-4.0

🎯 Why Tree Navigator?

The Problem: Standard tree commands output thousands of lines for modern projects: - Rust projects: target/ directories with 50,000+ files - Node.js projects: node_modules/ with endless dependencies - Build artifacts cluttering your tree view - Difficulty finding specific file types - No easy way to filter by permissions or file attributes

The Solution: Tree Navigator gives you surgical control: - 🎯 Smart Filtering: Exclude directories/files by name or pattern - 🔍 Type Selection: Show only executables, configs, scripts, or data files - 📊 Statistics: Get file counts, sizes, and exclusion metrics - 💾 Clean Export: Save filtered trees to files for documentation - 🛡️ Robust: Handle permission errors gracefully - ⚡ Fast: Compile-time optimizations via Ada

✨ Features

Core Capabilities

• 🎯 Advanced Filtering - Exclude specific directories and file patterns

• 📂 Type-Based Selection - Filter by file type (executable, config, script, data, etc.)

• 📊 Statistics - Automatic counting of files, directories, and total size

• 💾 File Export - Save tree output to files for documentation or analysis

• 🔍 Hidden File Control - Show or hide dotfiles

• 📏 Depth Limiting - Control how deep to traverse

• 📦 Size Display - Optional file size information

• 🎨 Color-Coded - Visual distinction with emoji icons

• 🛡️ Permission Handling - Graceful handling of access denied errors

• 🔖 Interactive Mode - Navigate and bookmark favorite locations

File Type Detection

Tree Navigator automatically categorizes files: - 📁 Directories - ⚙️ Executables (.exe, .bin, executable permission) - ⚙️ System Configs (.conf, .cfg) - 📜 Shell Scripts (.sh, .bash) - 📄 Data Files (.json, .xml, .yaml, .yml) - 👻 Hidden Files (starting with .) - 📄 Regular Files (everything else)

🚀 Quick Start

Prerequisites

• GNAT Ada Compiler: GCC 12.0+ with Ada 2022 support

• GPRbuild: GNAT Project Manager

Installation

= Clone the repository
git clone https://github.com/yourusername/tree-navigator.git
cd tree-navigator
= Build
gprbuild -P tree_navigator.gpr
= Optionally install system-wide
sudo cp bin/main /usr/local/bin/tree-navigator

📖 Usage

Export Mode (Primary Use Case)

Export directory trees to files with powerful filtering:

= Basic export
tree-navigator --export output.txt
= Export with depth limit
tree-navigator --export output.txt --max-depth 5
= Export specific directory
tree-navigator --export output.txt --dir /path/to/project
= Show file sizes
tree-navigator --export output.txt --show-size

Filtering Options

Exclude Directories

Perfect for ignoring build artifacts and dependencies:

= Rust project - exclude build directory
tree-navigator --export rust-tree.txt --exclude-dirs target
= Node.js - exclude dependencies
tree-navigator --export node-tree.txt --exclude-dirs node_modules
= Multiple exclusions
tree-navigator --export clean-tree.txt --exclude-dirs "target,node_modules,.git,build,dist"
= Ada/GNAT project
tree-navigator --export ada-tree.txt --exclude-dirs obj,bin

Exclude Files

Filter out specific files or patterns:

= Exclude compiled objects
tree-navigator --export source-tree.txt --exclude-files "*.o,*.ali,*.so"
= Exclude temporary files
tree-navigator --export clean-tree.txt --exclude-files "*.tmp,*.log,*.bak,*~"
= Exclude multiple patterns
tree-navigator --export code-tree.txt --exclude-files "*.o,*.exe,*.dll,*.pyc"

Filter by File Type

Show only specific categories of files:

= Only executables
tree-navigator --export bins.txt --only-type executable
= Only configuration files
tree-navigator --export configs.txt --only-type config
= Only shell scripts
tree-navigator --export scripts.txt --only-type script
= Only data files (JSON, XML, YAML)
tree-navigator --export data.txt --only-type data
= Only directories (no files)
tree-navigator --export dirs.txt --no-files
= Only files (no subdirectories)
tree-navigator --export files.txt --no-dirs

Hidden Files

= Include hidden files
tree-navigator --export full-tree.txt --show-hidden
= Show only hidden files
tree-navigator --export hidden-tree.txt --only-type hidden

Real-World Examples

Rust Project Documentation

= Clean tree for README, excluding build artifacts
tree-navigator --export project-structure.txt \
--exclude-dirs "target,.git" \
--exclude-files "*.lock,*.toml" \
--max-depth 4

Node.js Project

= Show project structure without dependencies
tree-navigator --export app-structure.txt \
--exclude-dirs "node_modules,dist,.next,coverage" \
--exclude-files "*.map,*.log" \
--max-depth 5

Find All Executables

= Locate all binary files in a project
tree-navigator --export executables.txt \
--only-type executable \
--show-size

Configuration Audit

= List all config files for review
tree-navigator --export all-configs.txt \
--only-type config \
--show-hidden

Shell Script Inventory

= Find all shell scripts in the system
tree-navigator --export scripts.txt \
--dir /usr/local/bin \
--only-type script

Interactive Navigation Mode

Navigate directories interactively with depth control:

= Start interactive mode
tree-navigator
= Start with depth limit
tree-navigator 5
= Or
tree-navigator --depth 10

Interactive Commands: - [dirname] - Enter a directory - [..] - Go up one level - [/] - Jump to root - [~] - Go to home - [b] - Show bookmarks - [+] - Add bookmark - [q] - Quit

📋 Command-Line Reference

General Options

-h, --help Show help message
-v, --version Show version information
--no-color Disable colored output
--verbose Enable verbose output

Export Mode Options

--export FILE Export tree to file (enables export mode)
--output FILE Alternative way to specify output file
--dir PATH Root directory to export (default: current)

Filtering Options

--max-depth N Maximum depth to traverse (default: 10)
--show-hidden Include hidden files (starting with .)
--no-files Only show directories
--no-dirs Only show files
--show-size Display file sizes
--exclude-dirs LIST Comma-separated list of directories to exclude
--exclude-files LIST Comma-separated list of files/patterns to exclude
--only-type TYPE Only show specific file type
Types: directory, executable, config, script,
data, hidden, regular

Interactive Mode Options

-d, --depth N Set maximum navigation depth

🎨 Output Format

Example output:

Directory tree: /home/user/project
Generated: 2024-11-06 10:30:45
Max depth: 5
================================================================================
📁 project
├── 📁 src
│ ├── 📄 main.adb
│ ├── 📄 config.ads
│ └── 📄 navigator.adb
├── 📁 bin
│ └── ⚙️ tree-navigator
├── ⚙️ Makefile
└── 📄 README.md
================================================================================
Statistics:
Directories: 2
Files: 5
Total size: 45231 bytes
Excluded dirs: 1

🏗️ Project Structure

tree-navigator/
├── src/
│ ├── main.adb # CLI argument parsing & main logic
│ ├── navigator.ads/adb # Interactive navigation
│ ├── tree_printer.ads/adb # Tree export engine
│ ├── bookmarks.ads/adb # Bookmark management
│ ├── config.ads/adb # Configuration
│ ├── terminal.ads/adb # Terminal I/O
│ └── file_types.ads/adb # File categorization
├── bin/ # Compiled executable
├── obj/ # Build artifacts
├── tree_navigator.gpr # GNAT project file
├── Makefile # Build automation
├── README.md # This file
├── LICENSE # Palimpsest-MPL-1.0 License
├── CONTRIBUTING.md # Contribution guidelines
└── CHANGELOG.md # Version history

🔧 Development

Building from Source

= Clean build
gprclean -P tree_navigator.gpr
gprbuild -P tree_navigator.gpr
= Using Make
make clean
make build
= Run
./bin/main --help

Running Tests

= Test basic export
./bin/main --export test.txt --max-depth 3
= Test with filters
./bin/main --export test.txt --exclude-dirs "obj,bin"
= Test file type filtering
./bin/main --export test.txt --only-type executable

⚙️ Configuration

Tree Navigator stores data in: - Config: ~/.config/tree-navigator/ - Bookmarks: ~/.config/tree-navigator/bookmarks.txt - Cache: ~/.cache/tree-navigator/

🤝 Contributing

Contributions welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

Quick Start

1. Fork the repository

2. Create a feature branch

3. Make your changes

4. Ensure it compiles cleanly

5. Submit a pull request

📝 License

MIT & Palimpsest 0.6 Dual License - see [LICENSE](LICENSE) file for details.

🙏 Acknowledgments

• Ada Community - Excellent language and tools

• GNAT - World-class Ada compiler

• Contributors - See [CONTRIBUTORS.md](CONTRIBUTORS.md)

📚 Additional Resources

• [Ada 2022 Reference](http://www.ada-auth.org/standards/22rm/html/RM-TOC.html)

• [GNAT User’s Guide](https://docs.adacore.com/gnat_ugn-docs/html/gnat_ugn/gnat_ugn.html)

• [Ada Programming](https://en.wikibooks.org/wiki/Ada_Programming)

🐛 Bug Reports & Features

Found a bug or have a feature request? [Open an issue](https://github.com/yourusername/tree-navigator/issues)!

---

Built with Ada 2022 | Solving real problems with compile-time guarantees

Architecture

See TOPOLOGY.md for a visual architecture map and completion dashboard.