# dep

> This readme is a work in progress.

A versatile, declarative and correct [neovim][2] package manager in [Lua][3].
Originally written for personal use by [luaneko][4]. Adapted by [squibid][5] for
general use.

What does that mean?

1. `versatile` - packages can be declared in any Lua file in any order of your
liking.
2. `declarative` - packages are declared using simple Lua tables.
3. `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][10] for an example of how dep can be used in
practice.

## Requirements

- [Neovim][2] 0.8+
- [Git][6] 2.13+

## Setup

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

```lua
-- ~/.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")
```

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

```lua
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.

```lua
{
  -- [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.

```lua
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.

```lua
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.

```lua
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.

```lua
-- 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.

```lua
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.

```lua
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][7] 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.

```lua
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][9], 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:

```lua
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][7] and [vim-fugitive][8] respectively.

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

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

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

```lua
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.

```lua
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.

```lua
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](LICENSE).

[1]: https://chiya.dev/posts/2021-11-27-why-package-manager
[2]: https://neovim.io/
[3]: https://www.lua.org/
[4]: https://github.com/luaneko
[5]: https://squi.bid
[6]: https://git-scm.com/
[7]: https://github.com/nvim-telescope/telescope.nvim
[8]: https://github.com/tpope/vim-fugitive
[9]: https://github.com/lewis6991/gitsigns.nvim
[10]: https://git.squi.bid/nvim