DOCSEARCHbyAlgolia
Submit Docs

yazi.nvim

repository·main·Indexed 23 days ago

https://github.com/mikavilpas/yazi.nvim

A Neovim plugin that integrates the yazi terminal file manager into a floating window. It provides synchronization between yazi file operations and Neovim buffers/LSP servers, with options to replace netrw for directory browsing and integrations for tools like telescope.nvim, fzf-lua.nvim, and grug-far.nvim.

Tokens
7.6K
Snippets
22
Records
35
Agent score
83%

What's inside yazi.nvim

  1. How LSP file renaming works with yazi.nvim

    main

    The plugin integrates with the Language Server Protocol (LSP) to ensure that when you rename a file within yazi, all references to that file in your project (such as imports) are automatically updated by your LSP server.

    Workflow:

    1. You rename a file inside the yazi terminal file manager.
    2. yazi sends a rename event to Neovim via its Data Distribution Service (DDS).
    3. The plugin triggers the LSP workspace/willRenameFiles request.
    4. The LSP server calculates and provides the necessary changes to related files.
    5. Neovim applies these changes.
    6. The plugin notifies the LSP server that renaming is finished via workspace/didRenameFiles.

    Requirement: An LSP server must be actively running in your Neovim session for this feature to function.

  3. Send custom events from yazi to yazi.nvim

    main

    You can define keymaps in yazi's keymap.toml that send messages to yazi.nvim using the ya pub-to command. This allows you to trigger Neovim actions from within yazi without overriding yazi's internal key handling for all use cases.

    To send an event with no data:

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

    To send an event with JSON data (e.g., the selected file path):

    [[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"
"""
    [[mgr.prepend_keymap]]
on = "<C-p>"
run = """shell 'ya pub-to 0 my-message-no-data'"""

  4. Reporting issues and requesting features

    main

    To report bugs, technical difficulties, or request new features, use the GitHub Issues tracker. This is the appropriate place for:

    • Reporting things that are not working as expected.
    • Requesting specific new functionality.
    • Offering assistance with existing issues.

  5. Read and inspect yazi.nvim logs

    main

    You can access the plugin's log files to inspect internal operations.

    • To open the log file directly within Neovim, use the command: :Yazi logs.
    • To monitor logs in real-time from your terminal, use tail -F on the log file path. For colored output, you can use bat with its custom tailing instructions.
    :Yazi logs

  6. Manage Yazi plugins and flavors with lazy.nvim

    main

    When using lazy.nvim, yazi.nvim allows you to manage Yazi plugins and color scheme (flavor) installations directly from Neovim. This integrates Yazi's ecosystem into your Neovim plugin management workflow, allowing for version locking via lazy-lock.json and easy updates.

    To use this feature, you must add a lazy.nvim plugin specification for the Yazi plugin or flavor and include a build function that calls the appropriate yazi.plugin method to link the files to your Yazi configuration directory.

    -- Example: include a Yazi plugin
{
  "Rolv-Apneseth/starship.yazi",
  lazy = true,
  build = function(plugin)
    require("yazi.plugin").build_plugin(plugin)
  end,
},

-- Example: include a Yazi flavor
{
  "BennyOe/onedark.yazi",
  lazy = true,
  build = function(plugin)
    require("yazi.plugin").build_flavor(plugin)
  end,
},

-- Example: include a flavor from a specific subdirectory
{
  "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,
}

  7. Enable debug logging in yazi.nvim

    main

    To diagnose issues, you can enable detailed logging using one of two methods:

    Method 1: Permanent configuration Set log_level = vim.log.levels.DEBUG within your yazi configuration object.

    Method 2: Manual invocation Call the yazi function directly with the debug log level enabled.

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

  8. Install yazi.nvim via lazy.nvim

    main

    The preferred way to install yazi.nvim is using lazy.nvim. This method automatically handles minimal dependencies. You can customize your keybindings and configuration within the LazySpec return block. If you intend to use yazi.nvim to replace netrw for directory browsing, it is recommended to set vim.g.loaded_netrwPlugin = 1 in the init function to prevent netrw from loading.

    ---@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,
}

  9. Install yazi.nvim without a package manager

    main

    If you are not using lazy.nvim, you must manually install the required dependencies (see lazy.lua for the list). After installing the plugin and its dependencies, map a key to the yazi() function. If you want to replace netrw for directories, set vim.g.loaded_netrwPlugin = 1 and use an autocmd to call setup({ open_for_directories = true }) on UIEnter.

    -- (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,
})

  11. Sharing ideas and feedback via Discussions

    main

    For non-bug-related communication, use GitHub Discussions. This is intended for:

    • Asking general questions.
    • Sharing cool use cases or workflows.
    • Providing feedback on development ideas and upcoming features.

  12. Develop locally using lazy.nvim

    main

    If you are developing changes to yazi.nvim and want to test them in your Neovim configuration without affecting your stable setup, you can use the dir option in lazy.nvim to point to a local clone of the repository.

    1. Fork the project and clone it to a local directory (e.g., ~/git/yazi.nvim/).
    2. Update your lazy.nvim plugin specification to use the dir key pointing to that path.
    3. To revert to the stable version, simply comment out the dir line.
    -- in your Neovim plugin config (e.g., ~/.config/nvim/lua/plugins/my-file-manager.lua)
---@type LazySpec
return {
  {
    "mikavilpas/yazi.nvim",
    -- for development, load from local directory
    dir = "~/git/yazi.nvim/",
  }
}