A versatile, declarative and correct neovim package manager in Lua. Originally written for personal use by luaneko. Adapted by squibid for general use.

What does that mean?

versatile - packages can be declared in any Lua file in any order of your liking.
declarative - packages are declared using simple Lua tables.
correct - packages are always loaded in a correct and consistent order.

In addition to the above dep has been built to be completely in control of you, the user. With the help of lazy loading you can choose when your plugin loads down to the finest detail (examples may be found below).

See also squibid's neovim-configs for an example of how dep can be used in practice.

Requirements

Neovim 0.8+
Git 2.13+

Setup

Create lua/bootstrap.lua in your neovim config directory.

-- ~/.config/nvim/lua/bootstrap.lua:
-- automatically install `squibid/dep` on startup
local path = vim.fn.stdpath("data") .. "/site/pack/deps/opt/dep"

if vim.fn.empty(vim.fn.glob(path)) > 0 then
  vim.fn.system({ "git", "clone", "--depth=1", "https://git.squi.bid/dep", path })
end

vim.cmd("packadd dep")

In init.lua, call dep with an array of package specifications.

require "bootstrap"
require "dep" {
  -- list of package specs...
}

Commands

:DepSync - installs new packages, updates packages to the latest versions, cleans removed packages and reloads packages as necessary.
:DepClean - cleans removed packages.
:DepReload - reloads all packages.
:DepLog - opens the log file.

Package specification

A package must be declared in the following format.

{
  -- [string] Specifies the full name of the package.
  -- This is the only required field; all other fields are optional.
  "user/package",

  -- [function] Code to run before the package is loaded into neovim.
  setup = function()
    vim.g.package_config = ...
  end,

  -- [function] Code to run after the package is loaded into neovim.
  load = function()
    require "package".setup(...)
  end,

  -- [function] Code to run after the package is installed or updated.
  config = function()
    os.execute(...)
  end,

  -- [function] Code used to determine when the package should be loaded.
  lazy = function(load)
  end,

  -- [string] Overrides the short name of the package.
  -- Defaults to a substring of the full name after '/'.
  as = "custom_package",

  -- [string] Overrides the URL of the git repository to clone.
  -- Defaults to "https://github.com/{full_name}.git".
  url = "https://git.chiya.dev/user/package.git",

  -- [string] Overrides the source in which the package is gotten
  -- from. This is not set by default.
  path = "~/my-local-package/",

  -- [string] Overrides the name of the branch to clone.
  -- Defaults to whatever the remote configured as their HEAD, which is usually "master".
  branch = "develop",

  -- [string] Overrides the commit ref to target
  -- Defaults to the latest commit on the current branch
  commit = "e76cb03",

  -- [boolean] Prevents the package from being loaded.
  disable = true,

  -- [boolean] Prevents the package from being updated.
  pin = true,

  -- [string|array] Specifies requirements that must be loaded before the package.
  -- If given a string, it is wrapped into an array.
  reqs = {...},

  -- [string|array] Specifies dependents that must be loaded after the package.
  -- If given a string, it is wrapped into an array.
  deps = {...}
}

When a string is given where a package specification table is expected, it is assumed to be the package's full name.

require "dep" {
  -- these two are equivalent
  "user/package",
  { "user/package" },
}

A package can be declared multiple times. Multiple declarations of the same package are combined into one. This is useful when declaring dependencies, which is explored later.

require "dep" {
  {
    "user/package",
    reqs = "user/dependency",
    disabled = true,
    config = function()
      print "my config hook"
    end
  },
  {
    "user/package",
    requires = "user/another_dependency",
    deps = "user/dependent",
    disabled = false,
    config = function()
      os.execute("make")
    end
  }
}

-- the above is equivalent to
require "dep" {
  {
    "user/package",
    reqs = { "user/dependency", "user/another_dependency" },
    deps = "user/dependent",
    disabled = true,
    config = function()
      print "my config hook"
      os.execute("make")
    end
  }
}

Declaring dependencies

The dependencies and dependents declared in a package specification are themselves package specifications. If a dependency or dependent is declared multiple times, they are combined into one just like normal package specifications.

require "dep" {
  {
    "user/package",
    reqs = {
      {
        "user/dependency1",
        reqs = "user/dependency2"
      }
    }
  }
}

-- the above is equivalent to
require "dep" {
  {
    "user/dependency2",
    deps = {
      {
        "user/dependency1",
        deps = "user/package"
      }
    }
  }
}

-- which is equivalent to
require "dep" {
  {
    "user/dependency1",
    reqs = "user/dependency2",
    deps = "user/package"
  }
}

-- which is equivalent to
require "dep" {
  {
    "user/dependency1",
    reqs = "user/dependency2"
  },
  {
    "user/package",
    reqs = "user/dependency1"
  }
}

-- which is equivalent to
require "dep" {
  {
    "user/dependency2",
    deps = "user/dependency1"
  },
  {
    "user/dependency1",
    deps = "user/package"
  }
}

-- all of the above are guaranteed to load in the following order: dependency2, dependency1, package

If dep detects a circular dependency cycle, it reports the problematic packages instead of hanging or crashing.

-- this throws an error saying package1 depends on package2 which depends on package1
require "dep" {
  {
    "user/package1",
    reqs = "user/package2"
  },
  {
    "user/package2",
    reqs = "user/package1"
  }
}

A dependency can be marked as disabled, which disables all dependents automatically.

require "dep" {
  {
    "user/dependency",
    disabled = true
  },
  {
    "user/package1",
    disabled = true, -- implied
    reqs = "user/dependency"
  },
  {
    "user/package2",
    disabled = true, -- implied
    reqs = "user/dependency"
  }
}

If a dependency fails to load for some reason, all of its dependents are guaranteed to not load.

require "dep" {
  {
    "user/problematic",
    load = function()
      error("bad hook")
    end
  },
  {
    "user/dependent",
    requires = "user/problematic",
    load = function()
      print "unreachable"
    end
  }
}

Lazy loading

Imagine you're using telescope.nvim and you need to pull it up with a keybind, but you don't want to have it load before that moment. With lazy loading you may choose to only load it when needed using the built in lazy utils which are made available to you as soon as you start using the lazy option.

require "dep" {
  { "nvim-telescope/telescope.nvim",
    lazy = function(load)
      load:keymap("n", "<leader>f")
    end,
    load = function()
      require("telescope").setup {}
      vim.keymap.set("n", "<leader>f", require("telescope.builtin").find_files, {})
    end
  }
}

Say you wanted to use gitsigns.nvim, but only wanted to load it when in a git directory OR when you call the Gitsigns command. With the power of lazy loading this can be accomplished by simply defining an auto command like so:

require "dep" {
  {
    "lewis6991/gitsigns.nvim",
    lazy = function(load)
      -- load gitsigns if we're in a git repository
      load:auto({ "BufEnter", "BufNew" }, {
        callback = function()
          local paths = vim.fs.find({ ".git", }, { upward = true })
          if #paths > 0 then
            load:cleanup()
          end
        end
      })

      -- load gitsigns if the user trys to run the command
      load:cmd("Gitsigns")
    end,
    load = function()
      require("gitsigns").setup {}
    end
  }
}

If you're in the need of a deeper understanding of how the utils work go check out lua/lazy/utils.lua for the source code.

Separating code into modules

Suppose you split your init.lua into two files packages/search.lua and packages/vcs.lua, which declare the packages telescope.nvim and vim-fugitive respectively.

-- ~/.config/nvim/lua/packages/search.lua:
return {
  {
    "nvim-telescope/telescope.nvim",
    reqs = "nvim-lua/plenary.nvim"
  }
}

-- ~/.config/nvim/lua/packages/vcs.lua:
return {
  "tpope/vim-fugitive"
}

Package specifications from other modules can be loaded using the modules option.

require "dep" {
  modules = {
    prefix = "packages.",
    "search",
    "vcs"
  }
}

-- the above is equivalent to
require "dep" {
  modules = {
    "packages.search",
    "packages.vcs"
  }
}

-- which is equivalent to
local packages = {}

for _, package in ipairs(require "packages.search") do
  table.insert(packages, package)
end

for _, package in ipairs(require "packages.vcs") do
  table.insert(packages, package)
end

require("dep")(packages)

-- which is ultimately equivalent to
require "dep" {
  {
    "nvim-telescope/telescope.nvim",
    reqs = "nvim-lua/plenary.nvim"
  },
  "tpope/vim-fugitive"
}

-- all of the above are guaranteed to load plenary.nvim before telescope.nvim.
-- order of telescope.nvim and vim-fugitive is consistent but unspecified.

Entire modules can be marked as disabled, which disables all top-level packages declared in that module.

return {
  disable = true,
  {
    "user/package",
    disabled = true, -- implied by module
    reqs = {
      {
        "user/dependency",
        -- disabled = true -- not implied
      }
    },
    deps = {
      {
        "user/dependent",
        disabled = true -- implied by dependency
      }
    }
  }
}

Miscellaneous configuration

dep accepts configuration parameters as named fields in the package list.

require "dep" {
  -- [string] Specifies when dep should automatically synchronize.
  -- "never": disable this behavior
  -- "new": only install newly declared packages (default)
  -- "always": synchronize all packages on startup
  sync = "new",

  -- [array] Specifies the modules to load package specifications from.
  -- Defaults to an empty table.
  -- Items can be either an array of package specifications,
  -- or a string that indicates the name of the module from which the array of package specifications is loaded.
  modules = {
    -- [string] Prefix string to prepend to all module names.
    prefix = "",
  },

  -- list of package specs...
}

License

dep is licensed under the MIT License.