File Explorer

Browse and navigate your project structure with Fresh’s built-in file explorer sidebar featuring gitignore support and file decorations

Fresh includes a built-in file explorer sidebar for browsing your project structure visually. It integrates seamlessly with git, respects .gitignore, and supports file decorations from plugins.

Basic Usage

Opening and Closing

Shortcut	Action
Ctrl+B	Toggle file explorer visibility
Ctrl+E	Switch focus between file explorer and editor

1. Show sidebar

   Press Ctrl+B to open the file explorer sidebar on the left side of the screen

2. Navigate files

   Use arrow keys to browse the file tree

3. Open a file

   Press Enter to open the selected file (keeps focus on explorer), or double-click to open and focus the editor

4. Hide sidebar

   Press Ctrl+B again to hide the file explorer

Focus Toggle: Ctrl+E is useful when you want to quickly switch between browsing files and editing code without closing the sidebar.

Navigation

Keyboard Navigation

Shortcut	Action
↑ / ↓	Move selection up/down in file tree
Enter	Open selected file (focus stays on explorer)
→	Expand directory
←	Collapse directory
Ctrl+E	Switch focus to editor

Mouse Navigation

Single Click

Opens the file but keeps focus on the file explorer — useful for quickly previewing multiple files

Double Click

Opens the file and focuses the editor — ready for editing

The file explorer uses your terminal’s mouse support. If mouse clicks don’t work, ensure mouse support is enabled in your terminal emulator.

Git Integration

Gitignore Support

The file explorer automatically respects your .gitignore file:

1. Default behavior

   Ignored files (like node_modules/, .env, build artifacts) are hidden by default

2. Show ignored files (optional)

   Open command palette (Ctrl+P) and search for “Toggle Gitignored Files”

3. Persistent setting

   This preference is saved to your config and persists across sessions

Hidden Files

Hidden files (starting with .) can be toggled separately:

1. Toggle hidden files

   Open command palette and search for “Toggle Hidden Files”

2. See dotfiles

   Files like .gitignore, .env, .config/ become visible

Independent Settings: Hidden files and gitignored files are separate toggles. You can show hidden files (.gitignore, .bashrc) while still hiding gitignored files (node_modules/).

File Explorer Features

Directory Tree

The file explorer displays your project as a tree structure:

Collapsed

▸ src/
▸ tests/
▸ docs/
  README.md
  package.json

• ▸ indicates a collapsed directory
• ▾ indicates an expanded directory

File Decorations

Plugins can add visual decorations to files:

Git Status

Show modified, staged, or untracked status (via git plugin)

Error Indicators

Highlight files with errors or warnings (via LSP)

Custom Icons

Plugins can add custom icons or badges to files

Color Coding

Different file types or states can be color-coded

File decorations require plugins to be enabled. The default Fresh installation includes git decorations.

Working with the File Explorer

Opening Files

Quick Preview

Single-click or Enter key opens the file while keeping focus on the file explorer.

Perfect for:

• Quickly previewing multiple files
• Checking file contents without leaving the explorer
• Browsing through search results

Edit Mode

Double-click opens the file and focuses the editor.

Use when:

• You’re ready to edit the file
• You want to navigate the file with keyboard shortcuts
• You’re done browsing the explorer

Symlinks

The file explorer handles symbolic links intelligently:

1. Symlink to file

   Opening a symlink to a file opens the target file

2. Symlink to directory

   Expanding a symlink to a directory shows the contents of the target directory

3. Broken symlinks

   Broken symlinks are shown with a special indicator

Symlinks are resolved when opened, so the editor shows the actual file path, not the symlink path.

File Explorer Settings

Customize the file explorer in your config.json:

config.json

{
  "file_explorer": {
    "width": 30,              // Width in columns
    "show_hidden": false,     // Show hidden files (dotfiles)
    "show_gitignored": false  // Show gitignored files
  }
}

Settings Reference

width · number · default: "30"

Width of the file explorer sidebar in terminal columns.

show_hidden · boolean · default: "false"

Whether to show hidden files (files starting with .).

show_gitignored · boolean · default: "false"

Whether to show files ignored by .gitignore.

File Explorer vs Command Palette

Both tools help you navigate files, but they serve different purposes:

Use File Explorer When

• You want to browse the project structure visually
• You’re exploring an unfamiliar codebase
• You need to see directory hierarchy
• You want context about file locations

Use Command Palette When

• You know the filename you want
• You want to open files quickly without browsing
• You’re navigating by fuzzy search
• You want keyboard-only workflow

Best of Both: Use Ctrl+P (command palette) for quick jumps to known files, and the file explorer for discovery and context.

Workflows

Workflow 1: Explore New Project

1. Open file explorer

   Press Ctrl+B to show the sidebar

2. Expand directories

   Use → to expand folders and see structure

3. Preview files

   Press Enter on files to preview without losing explorer focus

4. Edit when ready

   Double-click or Ctrl+E to focus editor and start editing

Workflow 2: Side-by-Side Reference

1. Open file explorer

   Ctrl+B to show sidebar

2. Open first file

   Navigate to file and press Enter

3. Create split

   Ctrl+P → > → “Split Vertical”

4. Open second file

   Keep explorer visible and open another file in the second split

5. Compare or reference

   Now you have both files open with the explorer still visible

Workflow 3: Show Hidden Config Files

1. Toggle hidden files

   Ctrl+P → > → “Toggle Hidden Files”

2. See dotfiles

   .gitignore, .env, .config/ are now visible

3. Edit config

   Navigate to the config file and open it

4. Hide again (optional)

   Toggle hidden files off to reduce clutter

Performance

Large Projects: The file explorer handles large directory trees efficiently. Even projects with thousands of files render quickly.

Lazy Loading: Directories are only read when expanded, so opening a project with many folders has minimal overhead.

Accessibility

The file explorer works great with keyboard-only workflows:

• Full keyboard navigation with arrow keys
• Screen reader friendly (file names are read as text)
• No mouse required for any operation
• Integrates with terminal accessibility features

Troubleshooting

File explorer doesn't show my files

Possible causes:

• Files are gitignored (use “Toggle Gitignored Files”)
• Files are hidden (use “Toggle Hidden Files”)
• Not in a git repository (Fresh uses git to list files)

Solution: Ensure you’re in a git repository, or use the command palette (Ctrl+P) to open files by path.

Mouse clicks don't work

Cause: Mouse support is not enabled in your terminal.

Solution: Check your terminal settings and enable mouse reporting. Most modern terminals support this.

File explorer is too narrow/wide

Solution: Adjust the file_explorer.width setting in your config.json.

Symlinks show as broken

Cause: The symlink target doesn’t exist or is outside the project.

Solution: Check that the symlink points to a valid file. Fresh resolves symlinks when opening them.

Related Documentation

Command Palette

Fuzzy file finding and commands

Navigation

Moving around your codebase

Configuration

Customize Fresh settings