Project Rooter

AstroNvim comes with a built in project root detection utility that can be used to update your current working directory manually or automatically. The user can customize the detection methods, configure language servers and directories to be ignored, the scope of the working directory change, as well as toggle automatic directory changing. We also provide a few user commands for interacting with the rooter:

Command	Description
:AstroRoot	Update current working directory to detected project root
:AstroRootInfo	Check the current root detection information

Default Configuration

lua/plugins/astrocore_rooter.lua

return {
  "AstroNvim/astrocore",
  ---@type AstroCoreOpts
  opts = {
    -- Configure project root detection, check status with `:AstroRootInfo`
    rooter = {
      -- list of detectors in order of prevalence, elements can be:
      --   "lsp" : lsp detection
      --   string[] : a list of directory patterns to look for
      --   fun(bufnr: integer): string|string[] : a function that takes a buffer number and outputs detected roots
      detector = {
        "lsp", -- highest priority is getting workspace from running language servers
        { ".git", "_darcs", ".hg", ".bzr", ".svn" }, -- next check for a version controlled parent directory
        { "lua", "MakeFile", "package.json" }, -- lastly check for known project root files
      },
      -- ignore things from root detection
      ignore = {
        servers = {}, -- list of language server names to ignore (Ex. { "efm" })
        dirs = {}, -- list of directory patterns (Ex. { "~/.cargo/*" })
      },
      -- automatically update working directory (update manually with `:AstroRoot`)
      autochdir = false,
      -- scope of working directory to change ("global"|"tab"|"win")
      scope = "global",
      -- show notification on every working directory change
      notify = false,
    },
  },
}

What is a “Rooter”?

A rooter automatically changes Neovim’s working directory based on the context of your current file. Instead of staying in the directory where you launched Neovim, it can detect and switch to the root of your project. This concept has been popular in the Vim ecosystem for many years with the autochdir option, and with plugins like vim-rooter being among the first implementations.

Why Use a Rooter?

The working directory in Neovim affects many operations:

• File searching: Tools like Telescope will search relative to your working directory
• Command execution: Shell commands run from Neovim use the working directory as their context
• Project navigation: Moving between files is easier when your working directory is at the project root

Without a rooter, you might encounter these scenarios:

• Opening a file from a deeply nested directory makes it difficult to search for other project files
• Moving between files in different parts of a project changes your context unpredictably
• Running commands against your project requires manually changing directories

AstroRoot vs. autochdir

Neovim has a built-in autochdir option that automatically changes the working directory to match the current file’s directory. However, this is rarely ideal for project work, since autochdir always sets the directory to the file’s immediate parent directory. This feature aims to intelligently find the project root, which can be several levels up from individual files by applying more rules for detecting the root of the project.

Practical Use Cases:

• Cross-project navigation: When opening files from different projects, the rooter ensures your working context switches appropriately
• Telescope optimization: Limits searches to the relevant project rather than including unrelated files
• Consistent command context: Shell commands and LSP operations work against the proper project root
• Improved file navigation: Makes it easier to navigate between related files in a project