> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/sinelaw/fresh/llms.txt
> Use this file to discover all available pages before exploring further.

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

<Steps>
  <Step title="Show sidebar">
    Press `Ctrl+B` to open the file explorer sidebar on the left side of the screen
  </Step>

  <Step title="Navigate files">
    Use arrow keys to browse the file tree
  </Step>

  <Step title="Open a file">
    Press `Enter` to open the selected file (keeps focus on explorer), or double-click to open and focus the editor
  </Step>

  <Step title="Hide sidebar">
    Press `Ctrl+B` again to hide the file explorer
  </Step>
</Steps>

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

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

<CardGroup cols={2}>
  <Card title="Single Click" icon="mouse-pointer">
    Opens the file but keeps focus on the file explorer — useful for quickly previewing multiple files
  </Card>

  <Card title="Double Click" icon="hand-pointer">
    Opens the file and focuses the editor — ready for editing
  </Card>
</CardGroup>

<Note>
  The file explorer uses your terminal's mouse support. If mouse clicks don't work, ensure mouse support is enabled in your terminal emulator.
</Note>

## Git Integration

### Gitignore Support

The file explorer automatically respects your `.gitignore` file:

<Steps>
  <Step title="Default behavior">
    Ignored files (like `node_modules/`, `.env`, build artifacts) are hidden by default
  </Step>

  <Step title="Show ignored files (optional)">
    Open command palette (`Ctrl+P`) and search for "Toggle Gitignored Files"
  </Step>

  <Step title="Persistent setting">
    This preference is saved to your config and persists across sessions
  </Step>
</Steps>

### Hidden Files

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

<Steps>
  <Step title="Toggle hidden files">
    Open command palette and search for "Toggle Hidden Files"
  </Step>

  <Step title="See dotfiles">
    Files like `.gitignore`, `.env`, `.config/` become visible
  </Step>
</Steps>

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

## File Explorer Features

### Directory Tree

The file explorer displays your project as a tree structure:

<CodeGroup>
  ```text Collapsed theme={null}
  ▸ src/
  ▸ tests/
  ▸ docs/
    README.md
    package.json
  ```

  ```text Expanded theme={null}
  ▾ src/
    ▸ components/
    ▸ utils/
      index.ts
      app.ts
  ▾ tests/
      unit.test.ts
  ▸ docs/
    README.md
    package.json
  ```
</CodeGroup>

* `▸` indicates a collapsed directory
* `▾` indicates an expanded directory

### File Decorations

Plugins can add visual decorations to files:

<CardGroup cols={2}>
  <Card title="Git Status" icon="code-branch">
    Show modified, staged, or untracked status (via git plugin)
  </Card>

  <Card title="Error Indicators" icon="triangle-exclamation">
    Highlight files with errors or warnings (via LSP)
  </Card>

  <Card title="Custom Icons" icon="icons">
    Plugins can add custom icons or badges to files
  </Card>

  <Card title="Color Coding" icon="palette">
    Different file types or states can be color-coded
  </Card>
</CardGroup>

<Note>
  File decorations require plugins to be enabled. The default Fresh installation includes git decorations.
</Note>

## Working with the File Explorer

### Opening Files

<Tabs>
  <Tab title="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
  </Tab>

  <Tab title="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
  </Tab>
</Tabs>

### Symlinks

The file explorer handles symbolic links intelligently:

<Steps>
  <Step title="Symlink to file">
    Opening a symlink to a file opens the target file
  </Step>

  <Step title="Symlink to directory">
    Expanding a symlink to a directory shows the contents of the target directory
  </Step>

  <Step title="Broken symlinks">
    Broken symlinks are shown with a special indicator
  </Step>
</Steps>

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

## File Explorer Settings

Customize the file explorer in your `config.json`:

```json config.json theme={null}
{
  "file_explorer": {
    "width": 30,              // Width in columns
    "show_hidden": false,     // Show hidden files (dotfiles)
    "show_gitignored": false  // Show gitignored files
  }
}
```

### Settings Reference

<ParamField path="width" type="number" default="30">
  Width of the file explorer sidebar in terminal columns.
</ParamField>

<ParamField path="show_hidden" type="boolean" default="false">
  Whether to show hidden files (files starting with `.`).
</ParamField>

<ParamField path="show_gitignored" type="boolean" default="false">
  Whether to show files ignored by `.gitignore`.
</ParamField>

## File Explorer vs Command Palette

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

<CardGroup cols={2}>
  <Card title="Use File Explorer When" icon="folder-tree">
    * 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
  </Card>

  <Card title="Use Command Palette When" icon="terminal">
    * 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
  </Card>
</CardGroup>

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

## Workflows

### Workflow 1: Explore New Project

<Steps>
  <Step title="Open file explorer">
    Press `Ctrl+B` to show the sidebar
  </Step>

  <Step title="Expand directories">
    Use `→` to expand folders and see structure
  </Step>

  <Step title="Preview files">
    Press `Enter` on files to preview without losing explorer focus
  </Step>

  <Step title="Edit when ready">
    Double-click or `Ctrl+E` to focus editor and start editing
  </Step>
</Steps>

### Workflow 2: Side-by-Side Reference

<Steps>
  <Step title="Open file explorer">
    `Ctrl+B` to show sidebar
  </Step>

  <Step title="Open first file">
    Navigate to file and press `Enter`
  </Step>

  <Step title="Create split">
    `Ctrl+P` → `>` → "Split Vertical"
  </Step>

  <Step title="Open second file">
    Keep explorer visible and open another file in the second split
  </Step>

  <Step title="Compare or reference">
    Now you have both files open with the explorer still visible
  </Step>
</Steps>

### Workflow 3: Show Hidden Config Files

<Steps>
  <Step title="Toggle hidden files">
    `Ctrl+P` → `>` → "Toggle Hidden Files"
  </Step>

  <Step title="See dotfiles">
    `.gitignore`, `.env`, `.config/` are now visible
  </Step>

  <Step title="Edit config">
    Navigate to the config file and open it
  </Step>

  <Step title="Hide again (optional)">
    Toggle hidden files off to reduce clutter
  </Step>
</Steps>

## Performance

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

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

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

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="File explorer is too narrow/wide">
    **Solution**: Adjust the `file_explorer.width` setting in your config.json.
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

## Related Documentation

<CardGroup cols={3}>
  <Card title="Command Palette" icon="terminal" href="/features/command-palette">
    Fuzzy file finding and commands
  </Card>

  <Card title="Navigation" icon="compass" href="/features/navigation">
    Moving around your codebase
  </Card>

  <Card title="Configuration" icon="gear" href="/configuration">
    Customize Fresh settings
  </Card>
</CardGroup>