Skip to main content
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

ShortcutAction
Ctrl+BToggle file explorer visibility
Ctrl+ESwitch 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.

​
Keyboard Navigation

ShortcutAction
↑ / ↓Move selection up/down in file tree
EnterOpen selected file (focus stays on explorer)
→Expand directory
←Collapse directory
Ctrl+ESwitch 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: 
▸ 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

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
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

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.
Cause: Mouse support is not enabled in your terminal.Solution: Check your terminal settings and enable mouse reporting. Most modern terminals support this.
Solution: Adjust the file_explorer.width setting in your config.json.

Command Palette

Fuzzy file finding and commands

Navigation

Moving around your codebase

Configuration

Customize Fresh settings

Build docs developers (and LLMs) love

Get started for freeTalk to us