### Install Yazi Plugin and Flavors with lazy.nvim

Source: https://github.com/mikavilpas/yazi.nvim/blob/main/documentation/plugin-management.md

Configure lazy.nvim to install the yazi.nvim plugin, a Starship prompt plugin, and an onedark flavor. Includes an example for a flavor from a subdirectory.

```lua
-- this file is: /Users/mikavilpas/.config/nvim/lua/plugins/my-file-manager.lua
--@type LazySpec
return {
  {
    "mikavilpas/yazi.nvim",
    keys = {
      {
        "<up>",
        mode = { "n", "v" },
        "<cmd>Yazi<cr>",
        desc = "Open yazi at the current file",
      },
    },
  },
  {
    -- example: include a plugin
    "Rolv-Apneseth/starship.yazi",
    lazy = true,
    build = function(plugin) 
      require("yazi.plugin").build_plugin(plugin)
    end,
  },
  {
    -- example: include a flavor
    "BennyOe/onedark.yazi",
    lazy = true,
    build = function(plugin) 
      require("yazi.plugin").build_flavor(plugin)
    end,
  },
  {
    -- example: include a flavor from a subdirectory. There are lots of flavors
    -- available in https://github.com/yazi-rs/flavors
    "yazi-rs/flavors",
    name = "yazi-flavor-catppuccin-macchiato",
    lazy = true,
    build = function(spec) 
      require("yazi.plugin").build_flavor(spec, {
        sub_dir = "catppuccin-macchiato.yazi",
      })
    end,
  },
}
```

--------------------------------

### Start Neovim with Minimal Configuration

Source: https://github.com/mikavilpas/yazi.nvim/blob/main/documentation/reproducing-issues.md

Use this command to start Neovim with a minimal configuration defined by repro.lua, useful for isolating issues.

```sh
nvim -u repro.lua -c "lua require('lazy').update()"
```

--------------------------------

### Install Dependencies with Mise

Source: https://github.com/mikavilpas/yazi.nvim/blob/main/documentation/for-developers/developing.md

Installs all project dependencies using the 'mise' tool. Ensure 'mise' is installed before running.

```sh
mise i
```

--------------------------------

### Start Integration Test Environment

Source: https://github.com/mikavilpas/yazi.nvim/blob/main/documentation/for-developers/developing.md

Starts the integration test environment by running 'pnpm dev' in the 'integration-tests' directory. This requires Node.js and PNPM to be set up.

```sh
# start the integration test environment inside the
# [integration-tests](../../integration-tests/) directory:
pnpm dev
```

--------------------------------

### Initialize yazi.nvim Plugin

Source: https://context7.com/mikavilpas/yazi.nvim/llms.txt

Configure yazi.nvim globally during Neovim startup. This setup merges global defaults, registers netrw hijacking, and initializes LSP sync. All configuration options are optional.

```lua
-- ~/.config/nvim/lua/plugins/yazi.lua
---@type LazySpec
return {
  "mikavilpas/yazi.nvim",
  version = "*",
  event = "VeryLazy",
  dependencies = { { "nvim-lua/plenary.nvim", lazy = true } },
  keys = {
    { "<leader>-",  mode = { "n", "v" }, "<cmd>Yazi<cr>",        desc = "Open yazi at current file" },
    { "<leader>cw",                       "<cmd>Yazi cwd<cr>",    desc = "Open yazi in Neovim cwd" },
    { "<c-up>",                           "<cmd>Yazi toggle<cr>", desc = "Resume last yazi session" },
  },
  ---@type YaziConfig
  opts = {
    open_for_directories = false,       -- set true to replace netrw
    open_multiple_tabs   = false,       -- open visible splits as yazi tabs
    change_neovim_cwd_on_close = false, -- cd to yazi's last dir on close

    floating_window_scaling_factor  = 0.9,
    yazi_floating_window_winblend   = 0,
    yazi_floating_window_border     = "rounded",

    highlight_hovered_buffers_in_same_directory = true,
    highlight_groups = {
      hovered_buffer                = { bg = "#1e2030" },
      hovered_buffer_in_same_directory = { bg = "#1a1a2e" },
    },

    keymaps = {
      show_help                           = "<f1>",
      open_file_in_vertical_split         = "<c-v>",
      open_file_in_horizontal_split       = "<c-x>",
      open_file_in_tab                    = "<c-t>",
      grep_in_directory                   = "<c-s>",
      replace_in_directory                = "<c-g>",
      cycle_open_buffers                  = "<tab>",
      copy_relative_path_to_selected_files = "<c-y>",
      send_to_quickfix_list               = "<c-q>",
      change_working_directory            = "<c-\>",
      open_and_pick_window                = "<c-o>",
    },

    integrations = {
      grep_in_directory   = "telescope",   -- or "fzf-lua" | "snacks.picker" | function
      replace_in_directory = function(directory)
        require("grug-far").open({
          prefills = { paths = directory:make_relative(vim.uv.cwd()) },
        })
      end,
      bufdelete_implementation = "bundled-snacks",
    },

    log_level = vim.log.levels.OFF,
  },
  -- Required when open_for_directories = true to prevent netrw from loading
  init = function()
    vim.g.loaded_netrwPlugin = 1
  end,
}

```

--------------------------------

### Install Project Dependencies with PNPM

Source: https://github.com/mikavilpas/yazi.nvim/blob/main/documentation/for-developers/developing.md

Installs project dependencies using PNPM. This command should be run after activating the correct Node.js version and enabling PNPM.

```sh
# install the dependencies
pnpm install # or `pnpm i`
```

--------------------------------

### Install Yazi Color Theme using lazy.nvim

Source: https://context7.com/mikavilpas/yazi.nvim/llms.txt

Use `build_flavor` within a lazy.nvim `build` function to symlink a flavor directory into yazi's flavors directory. The `sub_dir` option is required for multi-flavor repositories.

```lua
-- Single flavor repository
{
  "BennyOe/onedark.yazi",
  lazy = true,
  build = function(plugin)
    require("yazi.plugin").build_flavor(plugin)
    -- Then add to ~/.config/yazi/theme.toml:
    -- [flavor]
    -- use = "onedark.yazi"
  end,
},

-- Flavor from a multi-flavor monorepo
{
  "yazi-rs/flavors",
  name = "yazi-flavor-catppuccin-macchiato",
  lazy = true,
  build = function(spec)
    require("yazi.plugin").build_flavor(spec, {
      sub_dir = "catppuccin-macchiato.yazi",
    })
  end,
}

```

--------------------------------

### Build and Install Yazi from Source

Source: https://github.com/mikavilpas/yazi.nvim/blob/main/documentation/installing-yazi-from-source.md

Execute these commands within the cloned yazi repository to build the release version of Yazi and its internal CLI tool 'ya', then move them to your Cargo bin directory for accessibility.

```sh
# in the yazi repository:

# Install `yazi`, the main application as well as `ya`, the command line
# interface that's internally used by yazi.nvim
cargo build --release --locked && mv -v target/release/yazi target/release/ya ~/.cargo/bin/

```

--------------------------------

### Install yazi.nvim with lazy.nvim

Source: https://github.com/mikavilpas/yazi.nvim/blob/main/README.md

Use this configuration with lazy.nvim for automatic dependency management and lazy loading. Customize keymappings and options as needed.

```lua
---@type LazySpec
return {
  "mikavilpas/yazi.nvim",
  version = "*", -- use the latest stable version
  event = "VeryLazy",
  dependencies = {
    { "nvim-lua/plenary.nvim", lazy = true },
  },
  keys = {
    -- 👇 in this section, choose your own keymappings!
    {
      "<leader>-",
      mode = { "n", "v" },
      "<cmd>Yazi<cr>",
      desc = "Open yazi at the current file",
    },
    {
      -- Open in the current working directory
      "<leader>cw",
      "<cmd>Yazi cwd<cr>",
      desc = "Open the file manager in nvim's working directory",
    },
    {
      "<c-up>",
      "<cmd>Yazi toggle<cr>",
      desc = "Resume the last yazi session",
    },
  },
  ---@type YaziConfig | {}
  opts = {
    -- if you want to open yazi instead of netrw, see below for more info
    open_for_directories = false,
    keymaps = {
      show_help = "<f1>",
    },
  },
  -- 👇 if you use `open_for_directories=true`, this is recommended
  init = function()
    -- mark netrw as loaded so it's not loaded at all.
    --
    -- More details: https://github.com/mikavilpas/yazi.nvim/issues/802
    vim.g.loaded_netrwPlugin = 1
  end,
}
```

--------------------------------

### Install yazi.nvim without a package manager

Source: https://github.com/mikavilpas/yazi.nvim/blob/main/README.md

Configure yazi.nvim manually if you are not using a package manager. This involves setting keymaps and optionally configuring autocommands for directory opening.

```lua
-- (Obtain yazi.nvim and its dependencies using your preferred method first)
--
-- Next, map a key to open yazi.nvim
vim.keymap.set("n", "<leader>-", function()
  require("yazi").yazi()
end)

-- 👇 if you use `open_for_directories=true`, this is recommended.
--
-- mark netrw as loaded so it's not loaded at all.
-- More details: https://github.com/mikavilpas/yazi.nvim/issues/802
vim.g.loaded_netrwPlugin = 1
vim.api.nvim_create_autocmd("UIEnter", {
  callback = function()
    require("yazi").setup({
      open_for_directories = true,
    })
  end,
})

```

--------------------------------

### Install Yazi Plugins from Monorepo

Source: https://github.com/mikavilpas/yazi.nvim/blob/main/documentation/plugin-management.md

Use this snippet to install multiple Yazi plugins from a monorepo. Specify the `sub_dir` for each plugin you wish to include. For deeply nested plugins, provide a custom `dir` and `name`.

```lua
-- Example plugins:
---@type LazyPlugin[]
return {
  {
    -- example: a yazi plugin monorepo which provides multiple plugins for
    -- yazi. To use it, you need to specify the sub_dir for the plugin you want
    -- to install.
    -- example: include multiple plugins from a monorepo. There are lots of
    -- plugins available in e.g. https://github.com/yazi-rs/plugins
    "yazi-rs/plugins",
    name = "yazi-rs-plugins",
    lazy = true,
    -- stylua: ignore
    build = function(plugin)
      require("yazi.plugin").build_plugin(plugin, { sub_dir = "git.yazi" })
      require("yazi.plugin").build_plugin(plugin, { sub_dir = "vcs-files.yazi" })

      -- example: installing from a deeply nested subdirectory
      require("yazi.plugin").build_plugin({
        dir = plugin_monorepo_dir,
        name = "yazi-plugins",
      }, {
        yazi_dir = yazi_dir,
        sub_dir = vim.fs.joinpath("deeply", "nested", "plugin.yazi"),
        -- install as ~/.config/yazi/plugins/plugin.yazi
        name = "plugin.yazi",
      })
    end,
  },
  {
    -- Starship prompt plugin for yazi
    -- https://github.com/Rolv-Apneseth/starship.yazi
    "Rolv-Apneseth/starship.yazi",
    lazy = true,
    build = function(plugin)
      -- NOTE: you can customize the yazi directory, by default it is
      -- `~/.config/yazi/`
      require("yazi.plugin").build_plugin(
        plugin,
        { yazi_dir = vim.fs.normalize("~/.config/yazi/") }
      )
    end,
  },
}

-- NOTE: best practice: set `lazy = true` to make neovim not load these
-- plugins (only install them). They are only for Yazi.

```

--------------------------------

### Activate Node Version

Source: https://github.com/mikavilpas/yazi.nvim/blob/main/documentation/for-developers/developing.md

Activates the correct Node.js version using 'fnm use'. If the version is not installed, use 'fnm install <version>'. Requires Fast Node Manager (fnm) to be installed.

```sh
# activate the correct version of node
fnm use
# or fnm install <version> if you don't have the correct version installed
```

--------------------------------

### Configure Yazi.nvim Options

Source: https://github.com/mikavilpas/yazi.nvim/blob/main/README.md

Set advanced configuration options for yazi.nvim within your lazy.nvim setup. Defaults are provided and can be customized.

```lua
return {
  -- ... other lazy.nvim configuration from above

  ---@type YaziConfig | {}
  opts = {
    -- Below is the default configuration. It is optional to set these values.
    -- You can customize the configuration for each yazi call by passing it to
    -- yazi() explicitly

    -- enable this if you want to open yazi instead of netrw.
    -- Note that if you enable this, you need to call yazi.setup() to
    -- initialize the plugin. lazy.nvim does this for you in certain cases.
    --
    -- If you are also using neotree, you may prefer not to bring it up when
    -- opening a directory:
    -- {
    --   "nvim-neo-tree/neo-tree.nvim",
    --   opts = {
    --     filesystem = {
    --       hijack_netrw_behavior = "disabled",
    --     },
    --   },
    -- }
    open_for_directories = false,

    -- open visible splits and quickfix items as yazi tabs for easy navigation
    -- https://github.com/mikavilpas/yazi.nvim/pull/359
    open_multiple_tabs = false,

    -- when yazi is closed with no file chosen, change the Neovim working
    -- directory to the directory that yazi was in before it was closed. Defaults
    -- to being off (`false`)
    change_neovim_cwd_on_close = false,

    highlight_groups = {
      -- See https://github.com/mikavilpas/yazi.nvim/pull/180
      hovered_buffer = nil,
      -- See https://github.com/mikavilpas/yazi.nvim/pull/351
      hovered_buffer_in_same_directory = nil,
    },

    -- the floating window scaling factor. 1 means 100%, 0.9 means 90%, etc.
    floating_window_scaling_factor = 0.9,

    -- the transparency of the yazi floating window (0-100). See :h winblend
    yazi_floating_window_winblend = 0,

    -- the type of border to use for the floating window. Can be many values,
    -- including 'none', 'rounded', 'single', 'double', 'shadow', etc. For
    -- more information, see :h nvim_open_win
    yazi_floating_window_border = "rounded",

    -- the zindex of the yazi floating window. Can be used to make the yazi
    -- window fullscreen. See `:h nvim_open_win()` for more information.
    yazi_floating_window_zindex = nil,

    -- the log level to use. Off by default, but can be used to diagnose
    -- issues. You can find the location of the log file by running
    -- `:checkhealth yazi` in Neovim. Also check out the "reproducing issues"
    -- section below
    log_level = vim.log.levels.OFF,

    -- what Neovim should do a when a file was opened (selected) in yazi.
    -- Defaults to simply opening the file.
    open_file_function = function(chosen_file, config, state) end,

    -- customize the keymaps that are active when yazi is open and focused. The
    -- defaults are listed below. Note that the keymaps simply hijack input and
    -- they are never sent to yazi, so only try to map keys that are never
    -- needed by yazi.
    --
    -- Also:
    -- - use e.g. `open_file_in_tab = false` to disable a keymap
    -- - you can customize only some of the keymaps (not all of them)
    -- - you can opt out of all keymaps by setting `keymaps = false`
    keymaps = {
      show_help = "<f1>",
      open_file_in_vertical_split = "<c-v>",
      open_file_in_horizontal_split = "<c-x>",
      open_file_in_tab = "<c-t>",
      grep_in_directory = "<c-s>",
      replace_in_directory = "<c-g>",
      cycle_open_buffers = "<tab>",
      copy_relative_path_to_selected_files = "<c-y>",
      send_to_quickfix_list = "<c-q>",
      change_working_directory = "<c-\>",
      open_and_pick_window = "<c-o>",
    },

    -- completely override the keymappings for yazi. This function will be
    -- called in the context of the yazi terminal buffer.
    set_keymappings_function = function(yazi_buffer_id, config, context) end,

    -- some yazi.nvim commands copy text to the clipboard. This is the register
    -- yazi.nvim should use for copying. Defaults to "*", the system clipboard
    clipboard_register = "*",

    hooks = {
      -- if you want to execute a custom action when yazi has been opened,
      -- you can define it here.
      yazi_opened = function(preselected_path, yazi_buffer_id, config)
        -- you can optionally modify the config for this specific yazi
        -- invocation if you want to customize the behaviour
      end,

      -- when yazi was successfully closed
      yazi_closed_successfully = function(chosen_file, config, state) end,

      -- when yazi opened multiple files. The default is to send them to the

```

--------------------------------

### Manually Start yazi with Debug Logging

Source: https://github.com/mikavilpas/yazi.nvim/blob/main/documentation/reproducing-issues.md

Manually invoke yazi with debug logging enabled for detailed output.

```vim
:lua require('yazi').yazi({log_level = vim.log.levels.DEBUG})
```

--------------------------------

### Install Yazi Plugin using lazy.nvim

Source: https://context7.com/mikavilpas/yazi.nvim/llms.txt

Use `build_plugin` within a lazy.nvim `build` function to symlink a plugin directory into yazi's plugin directory. Supports monorepos with `sub_dir` and custom yazi directories.

```lua
-- Single plugin from its own repository
{
  "Rolv-Apneseth/starship.yazi",
  lazy = true,
  build = function(plugin)
    require("yazi.plugin").build_plugin(plugin)
    -- Installs to: ~/.config/yazi/plugins/starship.yazi -> <lazy dir>/starship.yazi
  end,
},

-- Multiple plugins from a monorepo (yazi-rs/plugins)
{
  "yazi-rs/plugins",
  name = "yazi-rs-plugins",
  lazy = true,
  build = function(plugin)
    require("yazi.plugin").build_plugin(plugin, { sub_dir = "git.yazi" })
    require("yazi.plugin").build_plugin(plugin, { sub_dir = "vcs-files.yazi" })
  end,
},

-- Plugin with a custom yazi config directory
{
  "some-author/my-yazi-plugin",
  lazy = true,
  build = function(plugin)
    require("yazi.plugin").build_plugin(plugin, {
      yazi_dir = vim.fs.normalize("~/.config/yazi-work/"),
    })
  end,
}

```

--------------------------------

### Start Yazi and Enter Find Mode

Source: https://github.com/mikavilpas/yazi.nvim/blob/main/documentation/emitting-commands-to-yazi.md

This Lua code snippet configures a Neovim keymap to open Yazi and immediately activate its find mode. It uses the `yazi.nvim` plugin and its `hooks.on_yazi_ready` functionality to emit the `find --smart` command to Yazi once it's ready.

```lua
vim.keymap.set("n", "<leader>r", function()
  require("yazi").yazi({
    ---@diagnostic disable-next-line: missing-fields
    hooks = {
      on_yazi_ready = function(_, _, process_api)
        -- https://yazi-rs.github.io/docs/configuration/keymap/#manager.find
        process_api:emit_to_yazi({ "find", "--smart" })
      end,
    },
  })
end)
```

--------------------------------

### Integrate Snacks.nvim with Yazi for Copy Path Action

Source: https://context7.com/mikavilpas/yazi.nvim/llms.txt

Configure snacks.nvim to add a keymap for copying the relative path to selected files, integrating with yazi.nvim's functionality. This setup ensures the `<C-y>` action works within the snacks file picker.

```lua
-- snacks.nvim picker integration: add <C-y> action to copy relative path
-- in the snacks file picker as well
---@type LazySpec
return {
  {
    "folke/snacks.nvim",
    opts = {
      picker = {
        win = {
          input = {
            keys = {
              ["<C-y>"] = { "yazi_copy_relative_path", mode = { "n", "i" } },
            },
          },
        },
      },
    },
  },
  {
    "mikavilpas/yazi.nvim",
    opts = {
      integrations = {
        picker_add_copy_relative_path_action = "snacks.picker",
      },
    },
  },
}
```

--------------------------------

### Check yazi.nvim Health

Source: https://github.com/mikavilpas/yazi.nvim/blob/main/documentation/reproducing-issues.md

Run this command to identify common issues with your yazi.nvim setup.

```vim
:checkhealth yazi
```

--------------------------------

### Customize Relative Path Resolution in yazi.nvim

Source: https://github.com/mikavilpas/yazi.nvim/blob/main/documentation/copy-relative-path-to-files.md

Customize how relative paths are resolved when using the `copy_relative_path_to_selected_files` key. This example resolves paths from Neovim's current working directory instead of the directory yazi was focused on.

```lua
-- Example: when using the `copy_relative_path_to_selected_files` key (default
-- <c-y>) in yazi, change the way the relative path is resolved.
require("yazi").setup({
  integrations = {
    resolve_relative_path_implementation = function(args, get_relative_path)
      -- By default, the path is resolved from the file/dir yazi was focused on
      -- when it was opened. Here, we change it to resolve the path from
      -- Neovim's current working directory (cwd) to the target_file.
      local cwd = vim.fn.getcwd()
      local path = get_relative_path({
        selected_file = args.selected_file,
        source_dir = cwd,
      })
      return path
    end,
  },
})
```

--------------------------------

### require("yazi").setup(opts)

Source: https://context7.com/mikavilpas/yazi.nvim/llms.txt

Initializes the yazi.nvim plugin with optional configuration. This function should be called once during Neovim startup.

```APIDOC
## `require("yazi").setup(opts)` — Initialize the plugin

Configures yazi.nvim globally. Must be called once during Neovim startup (lazy.nvim does this automatically via `opts`). Sets global defaults merged over the built-in defaults, registers the optional netrw hijack autocommand, and initializes LSP file-operation sync. All configuration keys are optional.

```lua
-- ~/.config/nvim/lua/plugins/yazi.lua
--@type LazySpec
return {
  "mikavilpas/yazi.nvim",
  version = "*",
  event = "VeryLazy",
  dependencies = { { "nvim-lua/plenary.nvim", lazy = true } },
  keys = {
    { "<leader>-",  mode = { "n", "v" }, "<cmd>Yazi<cr>",        desc = "Open yazi at current file" },
    { "<leader>cw",                       "<cmd>Yazi cwd<cr>",    desc = "Open yazi in Neovim cwd" },
    { "<c-up>",                           "<cmd>Yazi toggle<cr>", desc = "Resume last yazi session" },
  },
  --@type YaziConfig
  opts = {
    open_for_directories = false,       -- set true to replace netrw
    open_multiple_tabs   = false,       -- open visible splits as yazi tabs
    change_neovim_cwd_on_close = false, -- cd to yazi's last dir on close

    floating_window_scaling_factor  = 0.9,
    yazi_floating_window_winblend   = 0,
    yazi_floating_window_border     = "rounded",

    highlight_hovered_buffers_in_same_directory = true,
    highlight_groups = {
      hovered_buffer                = { bg = "#1e2030" },
      hovered_buffer_in_same_directory = { bg = "#1a1a2e" },
    },

    keymaps = {
      show_help                           = "<f1>",
      open_file_in_vertical_split         = "<c-v>",
      open_file_in_horizontal_split       = "<c-x>",
      open_file_in_tab                    = "<c-t>",
      grep_in_directory                   = "<c-s>",
      replace_in_directory                = "<c-g>",
      cycle_open_buffers                  = "<tab>",
      copy_relative_path_to_selected_files = "<c-y>",
      send_to_quickfix_list               = "<c-q>",
      change_working_directory            = "<c-\>",
      open_and_pick_window                = "<c-o>",
    },

    integrations = {
      grep_in_directory   = "telescope",   -- or "fzf-lua" | "snacks.picker" | function
      replace_in_directory = function(directory)
        require("grug-far").open({
          prefills = { paths = directory:make_relative(vim.uv.cwd()) },
        })
      end,
      bufdelete_implementation = "bundled-snacks",
    },

    log_level = vim.log.levels.OFF,
  },
  -- Required when open_for_directories = true to prevent netrw from loading
  init = function()
    vim.g.loaded_netrwPlugin = 1
  end,
}
```
```

--------------------------------

### require("yazi").yazi(config?, input_path?, args?)

Source: https://context7.com/mikavilpas/yazi.nvim/llms.txt

Opens yazi in a floating window. Allows overriding configuration, setting the initial path, and revealing a specific file on startup.

```APIDOC
## `require("yazi").yazi(config?, input_path?, args?)` — Open yazi

Opens yazi in a floating window. Merges the optional per-call `config` table over the global configuration. `input_path` overrides the file or directory yazi starts at (defaults to the current buffer's path). `args.reveal_path` instructs yazi to reveal a specific path in its listing after startup.

### Parameters

- **config** (table, optional) - Per-call configuration overrides.
- **input_path** (string, optional) - The initial path for yazi to open.
- **args** (table, optional) - Additional arguments, such as `reveal_path`.

### Request Example

```lua
-- Open yazi at the current file (normal usage via keymap)
require("yazi").yazi()

-- Open yazi at a specific path
require("yazi").yazi({}, "/home/user/projects")

-- Open yazi and immediately reveal a sibling file
local target = vim.fn.expand("%:p:h") .. "/README.md"
require("yazi").yazi({}, target, { reveal_path = target })

-- Override config just for this call (e.g., fullscreen)
require("yazi").yazi({
  floating_window_scaling_factor = 1.0,
  yazi_floating_window_border = "none",
})
```
```

--------------------------------

### Inspect Yazi Configuration at Runtime

Source: https://context7.com/mikavilpas/yazi.nvim/llms.txt

Set up a keymap to print the full merged yazi.nvim configuration at runtime. This is useful for debugging and understanding the active configuration settings.

```lua
-- Inspect the full merged configuration at runtime
vim.keymap.set("n", "<leader>yc", function()
  vim.print(require("yazi").config)
end, { desc = "Print yazi.nvim config" })

```

--------------------------------

### Integrate yazi.nvim with snacks.nvim for Path Copying

Source: https://github.com/mikavilpas/yazi.nvim/blob/main/documentation/copy-relative-path-to-files.md

Configure snacks.nvim to use yazi.nvim's relative path copying functionality within its picker. This involves defining a keymap in snacks.nvim and specifying the integration in yazi.nvim's configuration.

```lua
--@module "lazy"
--@type LazySpec
return {
  {
    "folke/snacks.nvim",
    priority = 1000,
    lazy = false,
    --@type snacks.Config
    opts = {
      picker = {
        win = {
          input = {
            keys = {
              ["<C-y>"] = { "yazi_copy_relative_path", mode = { "n", "i" } },
              -- ↑ add this and customize the keybinding to suit your needs
            },
          },
        },
      },
    },
  },
  {
    "mikavilpas/yazi.nvim",
    -- (more config keys here)
    --@type YaziConfig
    opts = {
      integrations = {
        picker_add_copy_relative_path_action = "snacks.picker",
        -- ↑ add this
      },
    },
  },
}
```

--------------------------------

### Customize Relative Path Resolution

Source: https://context7.com/mikavilpas/yazi.nvim/llms.txt

Override the default behavior of the `copy_relative_path_to_selected_files` keymap (`<c-y>`) by providing a custom function. This function receives the default implementation and can modify how relative paths are computed, for example, resolving them relative to Neovim's current working directory.

```lua
require("yazi").setup({
  integrations = {
    -- Default: resolve relative to the file yazi was opened on.
    -- Override: resolve relative to Neovim's cwd instead.
    resolve_relative_path_implementation = function(args, get_relative_path)
      return get_relative_path({
        selected_file = args.selected_file,
        source_dir    = vim.fn.getcwd(),
      })
    end,
  },
})
```

--------------------------------

### require("yazi").toggle(config?)

Source: https://context7.com/mikavilpas/yazi.nvim/llms.txt

Re-opens yazi focused on the last file that was hovered before yazi was closed. Falls back to the default path if no previous hover state exists.

```APIDOC
## `require("yazi").toggle(config?)` — Resume the last yazi session

Re-opens yazi focused on the last file that was hovered before yazi was closed. Falls back to the default path if no previous hover state exists. Useful for quickly jumping back into the file manager after editing.

### Parameters

- **config** (table, optional) - Configuration overrides for the session.

### Request Example

```lua
-- Map to toggle/resume yazi
require("yazi").toggle()

-- Toggle with a custom config override
require("yazi").toggle({
  change_neovim_cwd_on_close = true,
})

-- Access the last hovered path directly
local last = require("yazi").previous_state.last_hovered
if last then
  print("Last hovered: " .. last)
else
  print("No previous yazi hover state")
end
```
```

--------------------------------

### Tail Log File for Real-time Updates

Source: https://github.com/mikavilpas/yazi.nvim/blob/main/documentation/reproducing-issues.md

Use the tail command to monitor the log file in real-time, showing new messages as they arrive.

```sh
tail -F /path/to/logfile
```

--------------------------------

### Replace netrw with Yazi

Source: https://context7.com/mikavilpas/yazi.nvim/llms.txt

Configure yazi.nvim to open directories instead of netrw by setting `open_for_directories = true`. Prevent netrw from loading by setting `vim.g.loaded_netrwPlugin = 1` early.

```lua
-- Ensure the plugin loads early so the netrw hijack is set up in time
{
  "mikavilpas/yazi.nvim",
  version = "*",
  lazy = false,
  priority = 50,
  init = function()
    -- Prevent netrw from ever loading
    vim.g.loaded_netrwPlugin = 1
  end,
  opts = {
    open_for_directories = true,
  },
}

-- If also using neo-tree, prevent it from hijacking netrw as well:
-- {
--   "nvim-neo-tree/neo-tree.nvim",
--   opts = {
--     filesystem = { hijack_netrw_behavior = "disabled" },
--   },
-- }

-- Without a plugin manager: manual setup
vim.g.loaded_netrwPlugin = 1
vim.api.nvim_create_autocmd("UIEnter", {
  callback = function()
    require("yazi").setup({ open_for_directories = true })
  end,
})

```

--------------------------------

### Load Yazi.nvim from Local Directory for Development

Source: https://github.com/mikavilpas/yazi.nvim/blob/main/documentation/for-developers/developing.md

Use the 'dir' option in your lazy.nvim plugin specification to load yazi.nvim from a local directory for development. This allows you to make source code changes and test them without publishing.

```lua
-- this file is /Users/mikavilpas/.config/nvim/lua/plugins/my-file-manager.lua
---
--@type LazySpec
return {
  {
    "mikavilpas/yazi.nvim",
    -- if you want to use a specific branch, tag, or commit, you can specify it too

    -- for development, load from local directory
    dir = "~/git/yazi.nvim/",
    -- (... Many more settings)
  }
}
```

--------------------------------

### Configure Grep in Directory Integration

Source: https://context7.com/mikavilpas/yazi.nvim/llms.txt

Set up the `grep_in_directory` integration to use Telescope, fzf-lua, snacks.picker, or a custom Lua function. This feature scopes the search to selected files/directories if multiple are chosen before triggering the search.

```lua
require("yazi").setup({
  integrations = {
    -- Use telescope (default)
    grep_in_directory = "telescope",

    -- Use fzf-lua
    grep_in_directory = "fzf-lua",

    -- Use snacks.picker
    grep_in_directory = "snacks.picker",

    -- Custom implementation
    grep_in_directory = function(directory)
      require("telescope.builtin").live_grep({
        search_dirs = { tostring(directory) },
        prompt_title = "Search in " .. vim.fn.fnamemodify(tostring(directory), ":t"),
      })
    end,

    grep_in_selected_files = function(selected_files, relative_paths)
      require("telescope.builtin").live_grep({
        search_dirs = vim.tbl_map(tostring, selected_files),
      })
    end,
  },
})
```

--------------------------------

### Watch and Run Unit Tests

Source: https://github.com/mikavilpas/yazi.nvim/blob/main/documentation/for-developers/developing.md

Uses 'watchexec' via 'mise watch test' to automatically run unit tests when files change. This requires 'watchexec' to be bundled with Mise.

```sh
mise watch test
```

--------------------------------

### Enable Debug Logging in yazi.nvim

Source: https://github.com/mikavilpas/yazi.nvim/blob/main/documentation/reproducing-issues.md

Enable detailed logging for yazi.nvim by setting the log level to DEBUG in your configuration.

```lua
log_level = vim.log.levels.DEBUG,
```

--------------------------------

### process_api:emit_to_yazi(args)

Source: https://context7.com/mikavilpas/yazi.nvim/llms.txt

Sends commands to the running yazi instance from within the `on_yazi_ready` hook.

```APIDOC
## `process_api:emit_to_yazi(args)` — Send commands to yazi

Available inside the `on_yazi_ready` hook via the `process_api` argument. Sends a `ya emit-to` command to the running yazi instance, triggering any yazi action documented in the [yazi keymap configuration](https://yazi-rs.github.io/docs/configuration/keymap).

### Parameters

- **args** (table or string) - The command and its arguments to send to yazi.

### Request Example

```lua
require("yazi").setup({
  hooks = {
    on_yazi_ready = function(_, _, process_api) 
      -- Enter "find next" mode immediately when yazi opens
      -- https://yazi-rs.github.io/docs/configuration/keymap/#manager.find
      process_api:emit_to_yazi({ "find", "--smart" })
    end,
  },
})

-- Alternative: bind a keymap that opens yazi in find mode
vim.keymap.set("n", "<leader>rf", function() 
  require("yazi").yazi({
    --@diagnostic disable-next-line: missing-fields
    hooks = {
      on_yazi_ready = function(_, _, process_api) 
        process_api:emit_to_yazi({ "find", "--smart" })
      end,
    },
  })
end, { desc = "Open yazi in find mode" })
```
```

--------------------------------

### LSP File Renaming Sequence Diagram

Source: https://github.com/mikavilpas/yazi.nvim/blob/main/documentation/for-developers/lsp-renaming.md

Illustrates the interaction flow between Neovim, yazi, and the LSP server during a file rename operation. This diagram helps understand the sequence of events and requests involved.

```mermaid
sequenceDiagram

participant lsp
participant neovim
participant yazi

neovim->>yazi: open yazi inside neovim
yazi->>yazi: rename files and close
yazi->>neovim: provide rename events
neovim->>lsp: send rename request (willRenameFiles)
lsp->>neovim: changes to related files
neovim->>neovim: apply changes to related files
neovim->>lsp: send 'renaming finished' notification (didRenameFiles)
neovim->>neovim: user saves changes
```

--------------------------------

### Open yazi.nvim Log File

Source: https://github.com/mikavilpas/yazi.nvim/blob/main/documentation/reproducing-issues.md

Execute this command to open the yazi.nvim log file within Neovim.

```vim
:Yazi logs
```

--------------------------------

### Yazi Integrations: Grep and Replace

Source: https://github.com/mikavilpas/yazi.nvim/blob/main/README.md

Configure how yazi.nvim handles directory and selected file searching (grep) and replacement operations. These functions can be customized to use specific tools like telescope or grug-far.nvim.

```lua
grep_in_directory = function(directory)
        -- the default implementation uses telescope if available, otherwise nothing
      end,
```

```lua
grep_in_selected_files = function(selected_files)
        -- similar to grep_in_directory, but for selected files
      end,
```

```lua
replace_in_directory = function(directory)
        -- default: grug-far.nvim
      end,
```

```lua
replace_in_selected_files = function(selected_files)
        -- default: grug-far.nvim
      end,
```

--------------------------------

### Run All Unit Tests

Source: https://github.com/mikavilpas/yazi.nvim/blob/main/documentation/for-developers/developing.md

Executes all unit tests using the 'mise test' command. If 'busted.runner' is not found, a LuaRocks path command may be required.

```sh
# run all tests
mise test
# NOTE: if you get an error about "busted.runner" not being found, you may need
# to run the following command:
eval $(luarocks path --no-bin --lua-version 5.1)
```

--------------------------------

### Send Commands to Yazi via Process API

Source: https://context7.com/mikavilpas/yazi.nvim/llms.txt

Send commands to the running Yazi instance from within the `on_yazi_ready` hook using the `process_api`. This allows programmatic interaction with Yazi's actions.

```lua
require("yazi").setup({
  hooks = {
    on_yazi_ready = function(buffer, config, process_api)
      -- Enter "find next" mode immediately when yazi opens
      -- https://yazi-rs.github.io/docs/configuration/keymap/#manager.find
      process_api:emit_to_yazi({ "find", "--smart" })
    end,
  },
})

-- Alternative: bind a keymap that opens yazi in find mode
vim.keymap.set("n", "<leader>rf", function()
  require("yazi").yazi({
    ---@diagnostic disable-next-line: missing-fields
    hooks = {
      on_yazi_ready = function(_, _, process_api)
        process_api:emit_to_yazi({ "find", "--smart" })
      end,
    },
  })
end, { desc = "Open yazi in find mode" })
```

--------------------------------

### Define Yazi Keymap to Send Event with No Data

Source: https://github.com/mikavilpas/yazi.nvim/blob/main/documentation/yazi-keymappings.md

Configure a keymap in `keymap.toml` to send a simple event message to Yazi.nvim without any associated data. This is useful for triggering basic actions.

```toml
# keymap.toml
#
# send an event with no data
[[mgr.prepend_keymap]]
on = "<C-p>"
run = "'shell "ya pub-to 0 my-message-no-data"'"
```

--------------------------------

### Define Yazi Keymap to Send Event with JSON Data

Source: https://github.com/mikavilpas/yazi.nvim/blob/main/documentation/yazi-keymappings.md

Configure a keymap in `keymap.toml` to send an event with JSON data. This allows passing structured information, such as the selected file, to Yazi.nvim. It utilizes shell variables and the `ya pub-to` command.

```toml
# send an event that also has json data.
# yazi allows using shell variables like $0, see the documentation here
# https://yazi-rs.github.io/docs/configuration/keymap/#mgr.shell
[[mgr.prepend_keymap]]
on = "<C-h>"
run = "'shell --
json=$(printf '{"selected_file": "%s"}' "$0")
ya pub-to 0 my-change-working-directory-command --json "$json"
'"
```

--------------------------------

### Configure Yazi.nvim to Forward Custom Events

Source: https://github.com/mikavilpas/yazi.nvim/blob/main/documentation/yazi-keymappings.md

In your Neovim configuration, specify which custom Yazi events Yazi.nvim should listen for by adding them to `config.forwarded_dds_events`. This prepares Yazi.nvim to receive and process these events.

```lua
-- e.g. init.lua
---@module "yazi"

require("yazi").config.forwarded_dds_events =
  { "my-message-no-data", "my-change-working-directory-command" }
```

--------------------------------

### Custom Yazi Keymaps with NVIM_CWD

Source: https://context7.com/mikavilpas/yazi.nvim/llms.txt

Define custom keymaps in `keymap.toml` that leverage the `NVIM_CWD` environment variable set by yazi.nvim. This allows keymap behavior to differ based on whether yazi is running inside Neovim or standalone.

```toml
# ~/.config/yazi/keymap.toml

# Change working directory: go to Neovim's cwd when inside Neovim,
# otherwise go to the git root
[[mgr.prepend_keymap]]
on = ["g", "r"]
run = '''
  shell 'ya pub dds-cd --str "${NVIM_CWD:-$(git rev-parse --show-toplevel 2>/dev/null)}"'
'''

# Send a custom event with JSON data to a yazi.nvim handler
[[mgr.prepend_keymap]]
on = "<C-h>"
run = """shell --
json=$(printf '{"selected_file": "%s"}' "$0")
ya pub-to 0 my-change-working-directory-command --json "$json"
"""

# Send a simple event with no data
[[mgr.prepend_keymap]]
on = "<C-p>"
run = """shell 'ya pub-to 0 my-message-no-data'"""

```

--------------------------------

### Create Autocmd to Handle Yazi Custom Events in Neovim

Source: https://github.com/mikavilpas/yazi.nvim/blob/main/documentation/yazi-keymappings.md

Set up a Neovim `User` autocmd to catch `YaziDDSCustom` events. This callback function processes the received event data, allowing you to perform actions in Neovim based on Yazi events, such as changing the current working directory.

```lua
vim.api.nvim_create_autocmd("User", {
  pattern = "YaziDDSCustom",
  -- see `:help event-args`
  ---@param event yazi.AutoCmdEvent
  callback = function(event)
    -- printing the messages will allow seeing them with `:messages` in tests
    print(vim.inspect({
      string.format(
        "Just received a YaziDDSCustom event '%s'!",
        event.data.type
      ),
      event.data,
    }))

    if event.data.type == "my-change-working-directory-command" then
      local json = vim.json.decode(event.data.raw_data)
      local selected_file = assert(json.selected_file)

      local new_cwd = vim.fn.fnamemodify(selected_file, ":p:h")

      -- change Neovim's current working directory
      vim.cmd("cd " .. new_cwd)
    end
  end,
})
```

--------------------------------

### Define Conditional Yazi Keymap Based on Neovim Environment

Source: https://github.com/mikavilpas/yazi.nvim/blob/main/documentation/yazi-keymappings.md

Configure a keymap in `keymap.toml` that checks for the presence of the `NVIM_CWD` environment variable. This allows the keymap to execute different logic depending on whether Yazi is running within a Yazi.nvim session or as a standalone application.

```toml
# Augment https://yazi-rs.github.io/docs/tips/#cd-to-git-root - go to the nvim
# cwd when neovim is open, and to the git root when it is not
[[mgr.prepend_keymap]]
on = ["g", "r"]
run = '''
  shell 'ya pub dds-cd --str "${NVIM_CWD:-$(git rev-parse --show-toplevel 2>/dev/null)}"'
'''
```

--------------------------------

### Open Yazi in a Floating Window

Source: https://context7.com/mikavilpas/yazi.nvim/llms.txt

Opens Yazi in a floating window. Allows overriding global configuration, specifying an input path, or revealing a specific file. Useful for normal usage via keymaps.

```lua
-- Open yazi at the current file (normal usage via keymap)
vim.keymap.set("n", "<leader>-", function()
  require("yazi").yazi()
end)

-- Open yazi at a specific path
vim.keymap.set("n", "<leader>p", function()
  require("yazi").yazi({}, "/home/user/projects")
end)

-- Open yazi and immediately reveal a sibling file
vim.keymap.set("n", "<leader>r", function()
  local target = vim.fn.expand("%:p:h") .. "/README.md"
  require("yazi").yazi({}, target, { reveal_path = target })
end)

-- Override config just for this call (e.g., fullscreen)
vim.keymap.set("n", "<leader>Y", function()
  require("yazi").yazi({
    floating_window_scaling_factor = 1.0,
    yazi_floating_window_border = "none",
  })
end)

-- Open visual-mode selected file path in yazi
-- (select a path in visual mode, then press the keymap)
vim.keymap.set("v", "<leader>-", "<cmd>Yazi<cr>")
```

--------------------------------

### Resume Last Yazi Session

Source: https://context7.com/mikavilpas/yazi.nvim/llms.txt

Re-opens Yazi focused on the last hovered file. Falls back to the default path if no previous hover state exists. Useful for quickly returning to the file manager after editing.

```lua
-- Map to toggle/resume yazi
vim.keymap.set("n", "<c-up>", function()
  require("yazi").toggle()
end, { desc = "Resume last yazi session" })

-- Toggle with a custom config override
vim.keymap.set("n", "<leader>T", function()
  require("yazi").toggle({
    change_neovim_cwd_on_close = true,
  })
end, { desc = "Resume yazi and cd on close" })

-- Access the last hovered path directly
vim.keymap.set("n", "<leader>lh", function()
  local last = require("yazi").previous_state.last_hovered
  if last then
    print("Last hovered: " .. last)
  else
    print("No previous yazi hover state")
  end
end)
```

--------------------------------

### Custom Path Resolution Implementation

Source: https://github.com/mikavilpas/yazi.nvim/blob/main/README.md

Customize the implementation for resolving relative paths. This allows for alternative methods to be used instead of the default, potentially for compatibility or specific project needs.

```lua
resolve_relative_path_implementation = function(args, get_relative_path)
      end,
```