neovimcraft

plugins configs about

file-explorer

155

CREATED

2023-04-28

UPDATED

last month

ranger.nvim

Ranger integration plugin for neovim with no dependencies besides ranger.

Dependencies

Ranger

Install

Install using your package manager. This plugin does not set Neovim keymaps by default, you will need to set your own keymaps using the exposed api. See below Lazy configuration for example.

{
  "kelly-lin/ranger.nvim",
  config = function()
    require("ranger-nvim").setup({ replace_netrw = true })
    vim.api.nvim_set_keymap("n", "<leader>ef", "", {
      noremap = true,
      callback = function()
        require("ranger-nvim").open(true)
      end,
    })
  end,
}

Configuration

You can configure ranger.nvim by invoking ranger_nvim.setup() with an options table described below. Note: ranger_nvim.setup() is optional, if you do not invoke ranger_nvim.setup() ranger.nvim will use the default values.

Key	Type	Default	Description
`enable_cmds`	`boolean`	`false`	Set vim commands, see commands.
`keybinds`	`Keybind = table<string, OPEN_MODE>`	See ranger keybindings.	Key bindings set in `ranger` to control how files are opened in neovim. See ranger keybindings.
`replace_netrw`	`boolean`	`false`	Replace `netrw` with `ranger` when neovim is launched with a directory argument.
`ui`	`UI`	See UI Configuration.	Settings for ranger window.

See below code snippet for example configuring ranger.nvim with the default values.

local ranger_nvim = require("ranger-nvim")
ranger_nvim.setup({
  enable_cmds = false,
  replace_netrw = false,
  keybinds = {
    ["ov"] = ranger_nvim.OPEN_MODE.vsplit,
    ["oh"] = ranger_nvim.OPEN_MODE.split,
    ["ot"] = ranger_nvim.OPEN_MODE.tabedit,
    ["or"] = ranger_nvim.OPEN_MODE.rifle,
  },
  ui = {
    border = "none",
    height = 1,
    width = 1,
    x = 0.5,
    y = 0.5,
  }
})

Configuration - UI

Key	Type	Default	Value
`border`	`string`	`"none"`	See `:h nvim_open_win`.
`height`	`number`	`1`	From 0 to 1 (0 = 0% of screen and 1 = 100% of screen).
`width`	`number`	`1`	From 0 to 1 (0 = 0% of screen and 1 = 100% of screen).
`x`	`number`	`0.5`	From 0 to 1 (0 = left most of screen and 1 = right most of screen).
`y`	`number`	`0.5`	From 0 to 1 (0 = top most of screen and 1 = bottom most of screen).

API

`open(select_current_file: boolean)`

Opens ranger in a fullscreen floating window.

When select_current_file is set to true, ranger will focus on the file in the current buffer on load.

You can control how to open these files in Neovim by using the ranger keybindings that ranger.nvim sets.

`enum OPEN_MODE`

Enum to configure keybindings for open modes.

Variant	Action
`vsplit`	Open files in vertical split
`split`	Open files in horizontal split
`tabedit`	Open files in tab
`rifle`	Open files with rifle

Ranger Keybindings

ranger.nvim sets ranger keybindings in order to control how selected files are opened in neovim. You can override the keybindings using ranger_nvim.setup().

See below table for default keybindings.

Note: the keybinding string is in ranger keybinding syntax and not vim syntax (they are bindings for ranger)

Keybinding	Action
`<CR>`, `l` (when selected on file)	Open files in current window
`ov`	Open files in vertical split
`oh`	Open files in horizontal split
`ot`	Open files in tab
`or`	Open files with rifle

Overriding Keybindings

The ranger-nvim module provides an OPEN_MODE enum which is used to control the open modes. To override keybinds, create an entry in the keybinds table with a string key in ranger keybinding syntax (the same syntax you would use in your rc.conf) and assign it a value of an OPEN_MODE variant.

local ranger_nvim = require("ranger-nvim")
ranger_nvim.setup({
  keybinds = {
    ["ov"] = ranger_nvim.OPEN_MODE.vsplit,
    ["oh"] = ranger_nvim.OPEN_MODE.split,
    ["ot"] = ranger_nvim.OPEN_MODE.tabedit,
    ["or"] = ranger_nvim.OPEN_MODE.rifle,
  },
})

Commands

Commands are disabled by default, they can be enabled by setting enable_cmds = true in ranger_nvim.setup().

Below shows the mapping of commands to lua equivalents. See api for more info.

Command	Lua
`Ranger`	`ranger_nvim.open(true)`

Contributing

All feature/pull requests are welcome!