ftreeview

A lightweight, interactive CLI file explorer with live monitoring and git awareness.

Open source: MIT licensed (see LICENSE). Contributions welcome.

Features

• Interactive Tree Navigation - Browse directories with vim-style keybindings
• Live File Watching - Automatically updates when files change
• Git Status Integration - See modified, added, and untracked files at a glance
• Added/Modified Indicators - File and folder lines show quick A/M change icons (folder status is inherited from changed children)
• Colored File Types - Syntax-highlighted file extensions (JS, TS, Python, Go, Rust, etc.)
• Smart Icons - Nerd Font devicons (optional) with emoji fallback; ASCII mode supported
• Keyboard Navigation - Full keyboard control with arrow keys or vim bindings
• Optional Size Display - Show selected file size in status bar when needed
• Handles Large Directories - Efficient traversal with viewport scrolling
• Terminal Resize Support - Adapts to terminal window size changes
• Clean Exit - Graceful shutdown with proper terminal state restoration

Installation

Global Install (Recommended)

npm install -g ftreeview

Then run from anywhere:

ftreeview

npx (No Install Required)

npx ftreeview

Local Development

git clone https://github.com/chaitanyame/watchout.git
cd watchout
npm install
npm run build
node dist/cli.js

Usage

ftreeview [path] [options]

Arguments

| Argument | Description | |----------|-------------| | [path] | Path to directory to explore (default: current directory) |

Options

| Flag | Description | |------|-------------| | -h, --help | Print help message | | -v, --version | Print version information | | --no-git | Disable git integration | | --no-icons | Use ASCII icons (disable emoji/nerd icons) | | --icon-set <emoji\|nerd\|ascii> | Choose icon set (default: emoji). You can also set FTREE_ICON_SET. | | --theme <vscode> | UI theme (default: vscode). You can also set FTREE_THEME. | | --no-watch | Disable file watching for static view | | --show-size | Show selected file size in status bar (non-recursive, lightweight) |

Examples

# Explore current directory
ftreeview

# Explore specific directory
ftreeview ~/projects

# Explore with git disabled
ftreeview --no-git

 # Explore without icons (ASCII mode)
 ftreeview --no-icons

 # Use Nerd Font icons (requires Nerd Font)
 ftreeview --icon-set nerd

 # WSL / network drive troubleshooting (force polling watcher)
 FTREE_USE_POLLING=1 ftreeview

 # Static view (no live watching)
 ftreeview --no-watch

 # Show selected file size in status bar
 ftreeview --show-size

Environment Variables

| Variable | Description | |---------|-------------| | FTREE_ICON_SET | Default icon set (emoji, nerd, ascii) | | FTREE_THEME | Theme name (currently vscode) | | FTREE_USE_POLLING | Force chokidar polling watcher (1/true to enable, 0/false to disable) |

Keybindings

| Key | Action | |-----|--------| | ↑ / k | Move cursor up | | ↓ / j | Move cursor down | | → / l / Enter | Expand directory or enter | | ← / h | Collapse directory or jump to parent | | Space | Toggle expand/collapse | | g | Jump to first item | | G | Jump to last item | | r | Refresh tree | | ? | Toggle keybinding hints | | q / Ctrl+C | Quit |

Screenshots

Main View

ftreeview v0.1.0 │ ./projects/myapp │ 42 files, 12 dirs │ Watching... │ Git: clean
q:quit ↑↓:nav ←→:expand/collapse r:refresh ?:help

📁 src
  📁 components
    📜 App.jsx
    📜 Header.jsx
  📁 hooks
    📜 useAuth.js
  📁 utils
    📜 helpers.js
📄 package.json
📄 README.md

Git Status View

ftreeview v0.1.0 │ ./projects/myapp │ 42 files, 12 dirs │ Watching... │ Git: 2M 1A
q:quit ↑↓:nav ←→:expand/collapse r:refresh ?:help

📁 src
  📁 components
    📜 App.jsx [M]    ← Modified file
    📜 Header.jsx
  📁 hooks
    📜 useAuth.js [A] ← Newly added file
  📄 package.json [M] ← Modified file

Development

Prerequisites

• Node.js 18 or higher
• npm or yarn

Setup

# Clone the repository
git clone https://github.com/chaitanyame/watchout.git
cd watchout

# Install dependencies
npm install

# Build the project
npm run build

# Run from project root
node dist/cli.js /path/to/explore

# Link globally for testing
npm link
ftreeview

Project Structure

ftreeview/
├── src/
│   ├── cli.js           # CLI entry point
│   ├── App.jsx          # Root React component
│   ├── components/
│   │   ├── TreeView.jsx # Main tree renderer
│   │   ├── TreeLine.jsx # Individual line renderer
│   │   └── StatusBar.jsx# Status bar component
│   ├── hooks/
│   │   ├── useTree.js   # Tree building and management
│   │   ├── useNavigation.js # Keyboard navigation
│   │   ├── useGitStatus.js  # Git status polling
│   │   ├── useWatcher.js     # File system watcher
│   │   └── useIgnore.js     # Gitignore filtering
│   └── lib/
│       ├── icons.js     # Icon and color mappings
│       ├── constants.js # Configuration constants
│       └── connectors.js# Tree line connectors
├── package.json
└── README.md

Tech Stack

• Node.js (>=18.0.0) - Runtime environment
• React - UI component framework
• Ink - React for CLIs
• chokidar - File system watcher
• chalk - Terminal colors
• ignore - Gitignore pattern matching

License

MIT License - see LICENSE file for details

Contributing

Contributions are welcome!

• Bug reports / feature requests: open an issue at https://github.com/chaitanyame/watchout/issues
• Pull requests: keep changes focused, include a clear description, and run npm run build before submitting.

Security

If you believe you’ve found a security issue, please open a GitHub issue with the security label (or contact the maintainers privately if you prefer).

Author

Created with passion for better CLI tools.