vtree-tree

A modern Python CLI application that provides a full-screen, interactive file tree viewer for the terminal. Built with Textual TUI framework and Rich for terminal formatting.

Features

• 🌳 Interactive file tree - Navigate with mouse and keyboard
• 📁 Dual view modes - Toggle between inline files and separate file panel
• 📋 Clipboard integration - Copy paths with a single keystroke
• 🎨 Clean interface - Modern terminal-style dark theme without file type icons for better readability
• 👁️ Hidden file toggle - Show/hide dotfiles and system files
• 📊 File details - Human-readable file sizes and modification dates
• ⚡ Smart filtering - Automatically ignores common development artifacts (.git, pycache, node_modules, etc.)
• 🖱️ Mouse support - Full mouse navigation and selection
• 🔄 Real-time browsing - Refresh capability for dynamic file system viewing
• ✏️ Built-in file editor - Edit text files directly within vtree with syntax highlighting
• 🗑️ Safe file operations - Delete files and folders with confirmation prompts
• ↩️ Undo system - Undo deletions and edits with full file recovery
• 🎯 Multi-selection - Select multiple files/folders using Cmd+Click or Ctrl+Click

Installation

pip install vtree-tree

Usage

# View current directory
vtree

# View specific directory
vtree /path/to/directory

# Development - run from source
python3 -m vtree.main [path]

# Get help
vtree --help

Keyboard Shortcuts

View Modes

Inline Mode (Default)

Files and directories are shown together in a traditional tree structure.

Panel Mode

Press p to toggle panel mode where:

• Left panel shows the directory tree
• Right panel shows files in the selected directory with details (size, date)
• Perfect for browsing large directories with detailed file information

Copy to Clipboard

Press c to copy the current path to your clipboard:

• On a folder: Copies the folder path
• On a file: Copies the complete file path

Great for quickly navigating in terminal sessions:

vtree
# Press 'c' on desired folder/file
cd # Paste path here (for folders) or use file path directly

File Operations

Editing Files

Press e on any text file to open it in the built-in editor:

• Ctrl+S: Save changes
• Esc: Cancel and close editor
• Supports syntax highlighting and handles various encodings
• Automatically creates undo points for edited files

Deleting Files & Folders

Press d to delete selected items:

• Shows confirmation dialog with file count for folders
• Press y to confirm deletion or n to cancel
• Supports multi-selection - delete multiple items at once
• All deletions can be undone with Ctrl+Z / Cmd+Z

Undo System

Press Ctrl+Z / Cmd+Z to undo the last action:

• Restores deleted files and folders completely
• Reverts file edits to their previous content
• Maintains up to 50 undo actions in history
• Automatic cleanup of temporary backup files

Requirements

• Python 3.8+
• Works on macOS, Linux, and Windows
• Terminal with color support

Architecture

Built with a clean, modular architecture:

• VTreeApp: Main Textual application class that orchestrates the UI
• FileTree: Custom Tree widget that handles file system navigation and display
• FileListPanel: DataTable showing files with size and date information
• InfoPanel: Shows details about selected files/directories
• HelpPanel: Displays keyboard shortcuts
• FileNode: Data class for representing file system entries

Dependencies

• textual - Modern TUI framework
• rich - Terminal formatting and colors
• click - Command-line interface

License

MIT License - see LICENSE file for details.

Contributing

Contributions welcome! Please feel free to submit a Pull Request.