DTREE - Interactive Directory Tree Navigator

DESCRIPTION
  dtree is a lightweight TUI application for interactive directory tree
  navigation. It provides two modes:

  COMPACT MODE (default)
    • Runs inline in 8 rows — does not take over the terminal screen
    • Terminal returns to its exact pre-launch state on exit (no artifacts)
    • Ideal for quick directory navigation without interrupting your workflow

  FULLSCREEN MODE
    • Activated with 's' from compact mode, or via 'dt -v <file>'
    • Full-screen split view with file preview panel
    • File content, search results, and bookmarks panel

KEYBOARD NAVIGATION
  ↑ / k          Navigate up in the tree
  ↓ / j          Navigate down in the tree
  → / l          Expand directory (show subdirectories)
  ← / h          Collapse directory (hide subdirectories)
  u              Go to parent directory (change root)
  Backspace      Go to parent directory (change root)
  Enter          Go into directory (change root to selected directory)
  q              Exit and cd to selected directory
  Esc            Quit without directory change
  s              Switch to fullscreen file-viewer mode (from compact mode)
                 or toggle file viewer panel (in fullscreen mode)
  v              Open file in fullscreen viewer (only for files)
  c              Copy current path to clipboard (files and directories)
  e              Open file in external editor (configurable in config.toml)
  o              Open in file manager (files open parent dir, dirs open themselves)
  d              Open disk/mount point selection panel
  z              Toggle directory size display (shows calculated sizes)
  i              Show/hide this help screen

DIRECTORY SIZE DISPLAY (press 'z' to toggle)
  When enabled:
    • Shows total size for each directory next to its name
    • In file viewer mode (s): also shows individual file sizes
    • Directory sizes are calculated asynchronously in the background
    • File sizes are read from metadata instantly
    • Shows 'calc.' while directory calculation is in progress
    • Format: K (kilobytes), M (megabytes), G (gigabytes), T (terabytes)
    • Directory sizes include all files and subdirectories recursively
    • Results are cached until you toggle off or navigate away

  Safety limits (to prevent hanging on large directories):
    • Maximum calculation time: 5 seconds per directory
    • Maximum files processed: 10,000 files per directory
    • Prefix '>' indicates partial result (e.g., >5.2G)
    • Partial results mean the actual size may be larger

SEARCH
  /              Enter search mode
  Type query     Type your search query (case-insensitive)
  Enter          Execute search and show results panel
  Esc            Cancel search (in search mode) or close results panel

  In Search Results Panel:
  Tab            Switch focus between tree and search results
  ↑↓ / jk        Navigate through search results
  Enter          Select result and jump to it in the tree

  Search features:
  • Search scope: from current root directory and below
  • Normal mode: searches ONLY directories (fast)
  • File viewer mode (s): searches both files and directories
  • Searches through the ENTIRE tree (including collapsed nodes)
  • Shows all results in a separate panel at the bottom
  • Select a result to automatically expand and jump to it in the tree
  • Resizable panel: drag top border with mouse to adjust height
  • Cyan border indicates which panel has focus

  Search modes:
  • Normal search (query):   Case-insensitive substring matching
                             Example: type 'search' to find 'search.rs'

  • Fuzzy search (/query):   Intelligent fuzzy matching with scoring
                             Start query with '/' to activate fuzzy mode
                             Example: type '/srch' to find 'search.rs'
                             Results show score [95] and highlight matches
                             Best matches ranked first by relevance score

BOOKMARKS
  Interactive mode (inside dtree):
    m            Enter bookmark creation mode
    '            Open bookmark selection menu (tick/apostrophe)

  Bookmark Creation (after pressing 'm'):
    • Bottom panel shows: input bar + list of existing bookmarks
    • Type bookmark name (multi-character names supported)
    • Examples: work, project-123, my_home
    • Ctrl+j/k (or Ctrl+↑↓) scrolls through existing bookmarks list
    • Enter to save, Esc to cancel
    • NOTE: Bookmarks save directories only (if cursor on file, saves parent dir)

  Bookmark Selection (after pressing '''):
    • Bottom panel shows all saved bookmarks with paths
    • Two modes: Navigation (default) and Filter
    • Tab switches between navigation and filter modes

    Navigation mode:
      ↑↓ / jk     Move selection up/down
      d           Delete bookmark (press once to mark, twice to confirm)
      Enter       Jump to selected bookmark
      Tab         Switch to filter mode

    Filter mode:
      Type text   Filter bookmarks by name or path
      Tab         Switch to navigation mode (keeps filter)
      ↑↓ / jk     Navigate through filtered results (in nav mode)
      Enter       Jump to selected bookmark
      Esc         Close bookmarks panel

  Command-line mode (outside dtree):
    dt myproject        Jump to bookmark 'myproject' (if exists)
    dt -bm              List all bookmarks
    dt -bm list         List all bookmarks
    dt -bm add work     Save current directory as 'work'
    dt -bm add work /path   Save specific path as 'work'
    dt -bm remove work  Remove bookmark 'work'

  Storage: ~/.config/dtree/bookmarks.json
  Priority: Bookmark names are checked before directory names

DISK SELECTION (press 'd')
  Opens a panel listing all available mount points with:
    • Mount point path (e.g., /, /home, /mnt/usb)
    • Filesystem type (ext4, btrfs, xfs, ...)
    • Free space and total space
    • Volume label (if different from mount path)

  Navigation:
    ↑↓ / jk     Move selection up/down
    Enter        Navigate to selected mount point root
    Esc          Close disk panel without navigating

  The current mount point is pre-selected when the panel opens.

COMPACT MODE (default, 8 rows)
  When dtree launches without arguments, it starts in compact mode:
    • Header row: shows current root path and key hints
    • Up to 7 rows of directory tree (scrollable)
    • No alternate screen — terminal history is preserved
    • On exit, the 8 rows are erased and terminal is fully restored

  Keys available in compact mode:
    ↑↓ / hjkl     Navigate the directory tree (h: collapse, l: expand)
    u / Backspace  Go to parent directory
    Enter          cd to selected directory and exit
    q              cd to selected directory and exit
    Esc            Exit without changing directory
    s              Switch to fullscreen mode (with file preview panel)
    /              Enter search mode (search bar replaces bottom row)
    m              Create bookmark
    '              Open bookmark selection menu

FILE VIEWER MODE (press 's' to toggle)
  In fullscreen mode (after pressing 's' from compact or using 'dt -v'):
    • Shows files in addition to directories
    • Displays file preview panel on the right
    • Shows file content (up to 10000 lines by default)
    • Displays file information (size, lines, permissions)

  File Preview Navigation:
    Ctrl+j       Scroll down in file preview by line
    Ctrl+k       Scroll up in file preview by line
    Page Down    Scroll down in file preview by page
    Page Up      Scroll up in file preview by page
    Home         Jump to start of file
    End          Jump to end of file
    Scroll wheel Scroll file preview (when mouse over preview area)

BINARY FILE SUPPORT
  When you open a binary file (executables, images, archives, etc.):
    • dtree automatically detects binary files (checks for NULL bytes)
    • Shows informational message with file details instead of raw content
    • Displays file type, size, and permissions
    • Press 'e' to open in hex editor (configurable in config.toml)

  Supported file types:
    • Executables / Libraries (.exe, .dll, .so, .dylib, .bin)
    • Archives (.zip, .tar, .gz, .7z, .rar)
    • Images (.png, .jpg, .gif, .bmp, .webp)
    • Video (.mp4, .mkv, .avi, .mov)
    • Audio (.mp3, .wav, .flac, .ogg)
    • Documents (.pdf, .doc, .xls, .ppt)
    • Databases (.db, .sqlite)
    • And more...

  Hex editor configuration (config.toml):
    [behavior]
    hex_editor = "hexyl"  # Default: hexyl

  Install hexyl: cargo install hexyl
  Or use any other hex editor: xxd, hd, hexdump, etc.

FULLSCREEN VIEWER (press 'v' on a file)
  When viewing a file in fullscreen mode:
    q            Return to tree view (stay in program)
    Esc          Exit program completely (return to terminal)
    l            Toggle line numbers (show/hide)
    w            Toggle line wrapping (wrap/truncate long lines)

  Navigation (fullscreen mode):
    j / ↓        Scroll down by line
    k / ↑        Scroll up by line
    Ctrl+j       Jump to next file in directory
    Ctrl+k       Jump to previous file in directory
    Page Up/Down Scroll by page (fast navigation)
    Home         Switch to HEAD mode (show first 10000 lines)
    End          Switch to TAIL mode (show last 10000 lines)
    Scroll wheel Scroll by line with mouse

  Large File Viewing (HEAD/TAIL modes):
    • Files with more than 10000 lines show HEAD or TAIL mode indicator
    • HEAD mode shows first 10000 lines (default)
    • TAIL mode shows last 10000 lines (useful for logs)
    • Press End to switch to TAIL mode, Home to switch back to HEAD
    • Mode indicator appears in title: [HEAD MODE] or [TAIL MODE]
    • For large files (>1MB), tail mode uses efficient backward reading
    • Example use case: viewing log files - press End to see latest entries

  File Search (fullscreen mode):
    /            Enter file search mode (search within current file)
    Type query   Type your search query (case-insensitive)
    Enter        Execute search and jump to first match
    n            Jump to next match (cycles through results)
    N            Jump to previous match (Shift+n)
    Esc          Clear search and exit search mode

    Search features:
    • Case-insensitive substring matching
    • Highlights matching lines during navigation
    • Shows match counter: "Match 3/15" in the title bar
    • Auto-scrolls to center matched line on screen
    • Works in both HEAD and TAIL modes
    • Results persist until cleared with Esc

  Text Selection (fullscreen mode):
    Shift+Mouse  Select text (bypasses mouse capture)
                 Copy with Ctrl+Shift+C or right-click menu

  Visual Selection Mode (fullscreen mode):
    V            Enter visual selection mode (Vim-style line selection)
                 Default key: Shift+V (configurable in config.toml)

    In Visual Mode:
      j / ↓      Expand selection downward (move cursor down)
      k / ↑      Expand selection upward (move cursor up)
      Page Down  Jump selection down by page
      Page Up    Jump selection up by page
      Home       Jump to start of file
      End        Jump to end of file
      y          Copy selected lines to clipboard and exit visual mode
      Esc / V    Exit visual mode without copying
      Scroll     Move selection cursor with mouse wheel (auto-scroll)

    Visual feedback:
      • Selected lines highlighted with gray background
      • Current cursor position highlighted with blue background
      • Status bar shows selection size (e.g., "VISUAL: 25 lines")
      • Title bar displays [VISUAL MODE] indicator

    Features:
      • Select large blocks of text spanning multiple pages
      • Keyboard-driven selection (no need for mouse)
      • Auto-scroll when cursor reaches screen edge
      • Copy entire selection to system clipboard with 'y'
      • Works seamlessly with syntax highlighting
      • Bidirectional selection (select up or down from start point)

    Use cases:
      • Copying log file sections for analysis
      • Extracting large code blocks
      • Selecting configuration file sections
      • Any scenario requiring multi-page text selection

  Line Wrapping (fullscreen mode):
    w            Toggle line wrapping mode
    • Wrap mode (default): Long lines are wrapped at word boundaries
      - Lines break at spaces to fit the terminal width
      - Very long words are split if needed
      - Ideal for reading text files and documentation
    • Truncate mode: Long lines are truncated with "..." indicator
      - Shows maximum content on one line
      - Better for viewing code with long lines
      - Prevents horizontal scrolling confusion
    • Current mode is shown in the title bar (w: wrap / w: truncate)

  Important notes:
    • In fullscreen mode, ONLY viewer keys work (see above)
    • All other keys are disabled (tree search, bookmarks, tree navigation, etc.)
    • When launched via CLI (dt -v file.txt), file mode is enabled automatically
    • This allows Ctrl+j/k to navigate between files in the same directory
    • File search (/) is different from tree search - it searches within the file

MOUSE SUPPORT
  Click          Select item in tree
  Double-click   Expand/collapse directory
  Scroll wheel   Navigate tree (when mouse over tree area)
                 Scroll file preview (when mouse over preview area)
  Drag           Resize split view (drag the vertical divider)

COMMAND LINE OPTIONS
  dtree [PATH]           Navigate directory tree from PATH
  dtree -v FILE          View FILE directly in fullscreen mode
  dtree --view FILE      View FILE directly in fullscreen mode
  dtree --version        Print version information
  dtree -h / --help      Print this help message

SHELL INTEGRATION
  The 'dt' wrapper function is recommended for shell integration.
  Add to your ~/.bashrc or ~/.zshrc:

dt() {
  # Store current directory before navigation
  local prev_dir="$PWD"

  # Handle special case: dt - (return to previous directory)
  if [ "$1" = "-" ]; then
    if [ -n "$DTREE_PREV_DIR" ] && [ -d "$DTREE_PREV_DIR" ]; then
      cd "$DTREE_PREV_DIR" || return
      export DTREE_PREV_DIR="$prev_dir"
    else
      echo "dt: no previous directory" >&2
      return 1
    fi
    return
  fi

  # If flags or bookmark commands are passed, run dtree directly
  case "$1" in
    -h|--help|--version)
      command dtree "$@"
      return
      ;;
    -bm)
      # Bookmark management - run directly
      command dtree "$@"
      return
      ;;
  esac

  # For navigation: dtree resolves paths/bookmarks
  local result=$(command dtree "$@")
  local exit_code=$?

  if [ $exit_code -ne 0 ]; then
    return $exit_code
  fi

  # Only cd if result is a valid directory
  if [ -n "$result" ] && [ -d "$result" ]; then
    cd "$result" || return
    # Save previous directory for dt -
    export DTREE_PREV_DIR="$prev_dir"
  fi
}

  Usage:
    dt                   Open interactive tree from current directory
    dt /path/to/dir      Jump directly to path (no TUI)
    dt myproject         Jump directly to bookmark 'myproject' (no TUI)
    dt -                 Return to previous directory (like cd -)
    dt -bm               List all bookmarks
    dt -bm add work      Save current directory as 'work'
    dt -bm add work /p   Save specific path as 'work'
    dt -bm remove work   Remove bookmark 'work'
    dt -v file.txt       View file, navigate, cd on exit (with q)
    dt -h                Show help
    dt --version         Show version

  Behavior:
    • dt (no args) = Interactive TUI
    • dt <path/bookmark> = Direct cd (no TUI)
    • dt -v <file> = View file, then cd to selected dir on exit (q)
    • Priority: Bookmark → Path → Error

CONFIGURATION
  dtree uses a configuration file located at:
    ~/.config/dtree/config.toml

  On first run, this file is automatically created with default values.
  You can edit it to customize:
    • Appearance (colors, split position, icons)
    • Behavior (max file lines, show hidden files, double-click timeout)
    • Keybindings (customize keyboard shortcuts)

FILE TYPE ICONS
  File type icons can be enabled in config.toml:
    [appearance]
    show_icons = true

  Requirements:
    • Nerd Fonts installed (https://www.nerdfonts.com/)
    • Terminal with proper glyph support

  Features:
    • Different icons for programming languages (Rust, Python, JS, etc.)
    • Special icons for configuration files (Cargo.toml, package.json, etc.)
    • Directory-specific icons (.git, node_modules, src, etc.)
    • Document and media file icons
    • Fallback to emoji icons if nerd fonts not available

  To reset to defaults: delete the config file, it will be recreated on next run.

