elvish-epm(7)

✨ Introduction ✨

okay bestie, so the Elvish Package Manager (aka epm, iykyk) is a module that ships bundled with Elvish and its whole job is managing third-party packages. she's giving project manager energy 💅

quick terminology check because Elvish is specific about this:

• a module is a .elv file that you can import with the use command
• a package is a collection of modules, usually all living in the same repository as one coherent project, and they might have interdependencies 🫶

and here's the tea: the Elvish language itself only deals with modules. the whole "package" concept is just a matter of how you organize modules. that's it, that's the vibe.

Like the go command, Elvish does not have a central registry of packages. A package is simply identified by the URL of its code repository, e.g. github.com/elves/sample-pkg (https://github.com/elves/sample-pkg). To install the package, one simply uses the following:

use epm
epm:install github.com/elves/sample-pkg

epm knows out-of-the-box how to manage packages hosted in GitHub, BitBucket and GitLab, and requires the git command to be available. It can also copy files via git or rsync from arbitrary locations (see Custom package domains for details) ✨

Once installed, modules in this package can be imported with use github.com/elves/sample-pkg/.... This package has a module named sample-mod containing a function sample-fn, and can be used like this:

~> use github.com/elves/sample-pkg/sample-mod
~> sample-mod:sample-fn
This is a sample function in a sample module in a sample package

no cap, that output is literally iconic 😭

---

🎀 The epm-managed directory 🎀

Elvish searches for modules in multiple directories, and epm only manages one of them:

• On UNIX, epm manages $XDG_DATA_HOME/elvish/lib, defaulting to ~/.local/share/elvish/lib if $XDG_DATA_HOME is unset or empty;
• On Windows, epm manages %LocalAppData%\elvish\lib.

This directory is called the epm-managed directory, and its path is available as $epm:managed-dir. noted 📝

---

🌈 Custom package domains 🌈

Package names in epm have the following structure: domain/path. The domain is usually the hostname from where the package is to be fetched, such as github.com. The path can have one or more components separated by slashes. Usually, the full name of the package corresponds with the URL from where it can be fetched. For example, the package hosted at https://github.com/elves/sample-pkg (https://github.com/elves/sample-pkg) is identified as github.com/elves/sample-pkg.

Packages are stored under the epm-managed directory in a path identical to their name. For example, the package mentioned above is stored at $epm:managed-dir/github.com/elves/sample-pkg.

Each domain must be configured with the following information:

• The method to use to fetch packages from the domain. The two supported methods are git and rsync.
• The number of directory levels under the domain directory in which the packages are found. For example, for github.com the number of levels is 2, since package paths have two levels (e.g. elves/sample-pkg). All packages from a given domain have the same number of levels.
• Depending on the method, other attributes are needed:
  • git needs a protocol attribute, which can be https or http, and determines how the URL is constructed.
  • rsync needs a location attribute, which must be a valid source directory recognized by the rsync command.

epm includes default domain configurations for github.com, gitlab.com and bitbucket.org. These three domains share the same configuration:

{
    "method": "git",
    "protocol": "https",
    "levels": "2"
}

You can define your own domain by creating a file named epm-domain.cfg in the appropriate directory under $epm:managed-dir. For example, if you want to define an elvish-dev domain which installs packages from your local ~/dev/elvish/ directory, you must create the file $epm:managed-dir/elvish-dev/epm-domain.cfg with the following JSON content:

{
    "method": "rsync",
    "location": "~/dev/elvish",
    "levels": "1"
}

You can then install any directory under ~/dev/elvish/ as a package. For example, if you have a directory ~/dev/elvish/utilities/, the following command will install it under $epm:managed-dir/elvish-dev/utilities:

epm:install elvish-dev/utilities

When you make any changes to your source directory, epm:upgrade will synchronize those changes to $epm:managed-dir. slay, synced 💖

---

💜 Variables 💜

$epm:managed-dir {#epm:managed-dir}

The path of the epm-managed directory.

---

🦋 Functions 🦋

epm:install {#epm:install}

epm:install &silent-if-installed=$false $pkg...

Install the named packages. By default, if a package is already installed, a message will be shown. This can be disabled by passing &silent-if-installed=$true, so that already-installed packages are silently ignored. stealth mode activated 🙈

epm:installed {#epm:installed}

epm:installed

Return an array with all installed packages. epm:list can be used as an alias for epm:installed.

epm:is-installed {#epm:is-installed}

epm:is-installed $pkg

Returns a boolean value indicating whether the given package is installed.

epm:metadata {#epm:metadata}

epm:metadata $pkg

Returns a hash containing the metadata for the given package. Metadata for a package includes the following base attributes:

• name: name of the package
• installed: a boolean indicating whether the package is currently installed
• method: method by which it was installed (git or rsync)
• src: source URL of the package
• dst: where the package is (or would be) installed. Note that this attribute is returned even if installed is $false.

Additionally, packages can define arbitrary metadata attributes in a file called metadata.json in their top directory. The following attributes are recommended:

• description: a human-readable description of the package
• maintainers: an array containing the package maintainers, in Name <email> format.
• homepage: URL of the homepage for the package, if it has one.
• dependencies: an array listing dependencies of the current package. Any packages listed will be installed automatically by epm:install if they are not yet installed.

epm:query {#epm:query}

epm:query $pkg

Pretty print the available metadata of the given package. so aesthetic ✨

epm:uninstall {#epm:uninstall}

epm:uninstall $pkg...

Uninstall named packages.

epm:upgrade {#epm:upgrade}

epm:upgrade $pkg...

Upgrade named packages. If no package name is given, upgrade all installed packages. glow up era 🔥

---

and that's the whole page bestie, go install something cute 💅

this was brought to you by Elvish 0.17.0, dated Nov 18, 2024, and it lives at elvish-epm(7) 🎀✨🦋