Installation

Stable Version (Recommended)

The stable branch updates only on releases and provides the most reliable experience.

Using Lazy.nvim:

{
  "A7Lavinraj/fyler.nvim",
  dependencies = { "nvim-mini/mini.icons" },
  branch = "stable",
  opts = {}
}

Using Mini.deps:

add({
  source = "A7Lavinraj/fyler.nvim",
  depends = { "nvim-mini/mini.icons" },
  checkout = "stable",
})

Latest Version

The main branch includes the newest features but may contain bugs.

Using Lazy.nvim with mini.icons:

{
  "A7Lavinraj/fyler.nvim",
  dependencies = { "nvim-mini/mini.icons" },
  opts = {}
}

Using Lazy.nvim with nvim-web-devicons:

{
  "A7Lavinraj/fyler.nvim",
  dependencies = { "nvim-tree/nvim-web-devicons" },
  opts = { icon_provider = "nvim_web_devicons" }
}

Quick Start

Using Commands

:Fyler                    " Open with default options
:Fyler kind=split_left    " Open in specific window layout
:Fyler dir=~/projects     " Open specific directory

Using Lua API

local fyler = require("fyler")

-- Open Fyler with optional settings
fyler.open({
  dir = "~/",              -- (Optional) Start in specific directory
  kind = "split_left_most" -- (Optional) Use custom window layout
})

-- Toggle Fyler with optional settings
fyler.toggle({
  dir = "~/",              -- (Optional) Start in specific directory
  kind = "split_left_most" -- (Optional) Use custom window layout
})

Configuration

Fyler.nvim works out of the box with sensible defaults. Here's the complete configuration reference:

{
  hooks = {
    -- function(path) end
    on_delete = nil,
    -- function(src_path, dst_path) end
    on_rename = nil,
    -- function(hl_groups, palette) end
    on_highlight = nil,
  },
  integrations = {
    icon = "mini_icons",
  },
  views = {
    finder = {
      -- Close explorer when file is selected
      close_on_select = true,
      -- Auto-confirm simple file operations
      confirm_simple = false,
      -- Replace netrw as default explorer
      default_explorer = false,
      -- Move deleted files/directories to the system trash
      delete_to_trash = false,
      -- Git status
      git_status = {
        enabled = true,
        symbols = {
          Untracked = "?",
          Added = "+",
          Modified = "*",
          Deleted = "x",
          Renamed = ">",
          Copied = "~",
          Conflict = "!",
          Ignored = "#",
        },
      },
      -- Icons for directory states
      icon = {
        directory_collapsed = nil,
        directory_empty = nil,
        directory_expanded = nil,
      },
      -- Indentation guides
      indentscope = {
        enabled = true,
        group = "FylerIndentMarker",
        marker = "│",
      },
      -- Key mappings
      mappings = {
        ["q"] = "CloseView",
        ["<CR>"] = "Select",
        ["<C-t>"] = "SelectTab",
        ["|"] = "SelectVSplit",
        ["-"] = "SelectSplit",
        ["^"] = "GotoParent",
        ["="] = "GotoCwd",
        ["."] = "GotoNode",
        ["#"] = "CollapseAll",
        ["<BS>"] = "CollapseNode",
      },
      -- Current file tracking
      follow_current_file = true,
      -- File system watching(includes git status)
      watcher = {
        enabled = false,
      },
      -- Window configuration
      win = {
        border = vim.o.winborder == "" and "single" or vim.o.winborder,
        buf_opts = {
          filetype = "fyler",
          syntax = "fyler",
          buflisted = false,
          buftype = "acwrite",
          expandtab = true,
          shiftwidth = 2,
        },
        kind = "replace",
        kinds = {
          float = {
            height = "70%",
            width = "70%",
            top = "10%",
            left = "15%",
          },
          replace = {},
          split_above = {
            height = "70%",
          },
          split_above_all = {
            height = "70%",
            win_opts = {
              winfixheight = true, -- keep the window height fixed when other windows resize
            },
          },
          split_below = {
            height = "70%",
          },
          split_below_all = {
            height = "70%",
            win_opts = {
              winfixheight = true,
            },
          },
          split_left = {
            width = "70%",
          },
          split_left_most = {
            width = "30%",
            win_opts = {
              winfixwidth = true, -- keep the window width fixed when other windows resize
            },
          },
          split_right = {
            width = "30%",
          },
          split_right_most = {
            width = "30%",
            win_opts = {
              winfixwidth = true,
            },
          },
        },
        win_opts = {
          concealcursor = "nvic",
          conceallevel = 3,
          cursorline = false,
          number = false,
          relativenumber = false,
          winhighlight = "Normal:FylerNormal,NormalNC:FylerNormalNC",
          wrap = false,
        },
      },
    },
  },
}

Enable delete_to_trash to send deletions to your operating system's trash (macOS ~/.Trash, Linux XDG Trash, Windows Recycle Bin) instead of removing files permanently. Fyler automatically performs a permanent delete if the target already lives inside the trash directory.

Note: When moving files across different filesystems (e.g., to a trash directory on a different drive), the operation automatically falls back to copy-then-delete, which may be slower for large files or directories. Windows operations include a 30-second timeout to prevent hanging.

Telescope Extension

Fyler.nvim includes a Telescope extension for enhanced directory navigation:

local telescope = require("telescope")

telescope.setup({
  extensions = {
    fyler = {
      -- Extension configuration
    }
  }
})

telescope.load_extension("fyler")

Documentation

• Wiki: Comprehensive documentation available on the Wiki page
• Live Streams: Development streams on YouTube
• Stable Documentation: Stable branch documentation

Contributing

We welcome contributions! Please read our Contributing Guidelines before submitting pull requests.

Issues and Support

If you encounter any problems:

1. Search existing issues to see if your problem has been reported
2. If no related issue exists, please open a new one with detailed information

Similar Projects

If fyler.nvim doesn't meet your needs, consider these alternatives:

• mini.files
• oil.nvim

Acknowledgments

This project draws inspiration from several excellent Neovim plugins and libraries:

• mini.nvim
• neogit
• plenary.nvim
• snacks.rename
• telescope.nvim

License

This project is licensed under the Apache-2.0 License. See the repository for full license details.