Short Story: el-get allows you to install and manage
elisp code for
Emacs. It supports lots of differents types of sources and is able to
install them, update them and remove them, but more importantly it
will init them for you.
That means it will
require the features you need,
necessary files, set the Info paths so that
C-h i shows the new
documentation you now depend on, and finally call your own
:post-init function for you to setup the extension. Or call it a
Status and Version Numbers
el-get status is stable, ready for daily use and packed with extra
features that make life easier. There are some more things we could do, as
always, but they will be about smoothing things further.
Latest released version
el-get version 3.1 is available, with a boatload of features, including
autoloads support, byte-compiling in an external "clean room" Emacs
instance, custom support, lazy initialisation support (defering all init
eval-after-load), and multi repositories
Version String are now inspired by how Emacs itself numbers its versions. First is the major version number, then a dot, then the minor version number. The minor version number is 0 when still developping the next major version. So 3.0 is a developer release while 3.1 will be the next stable release.
Please note that this versioning policy has been picked while backing 1.2~dev, so 1.0 was a "stable" release in fact. Ah, history.
In addition to the version, you can also get the exact git revision by
el-get-self-checksum. You should provide this checksum
when seeking support or reporting a bug, so that the developers will
know exactly which version you are using.
How to Install it?
Here’s the lazy installer:
;; So the idea is that you copy/paste this code into your *scratch* buffer, ;; hit C-j, and you have a working el-get. (url-retrieve "https://raw.github.com/dimitri/el-get/master/el-get-install.el" (lambda (s) (goto-char (point-max)) (eval-print-last-sexp)))
You have to type
C-j with the cursor at the end of the last line, but
still on the line. C-j runs the command eval-print-last-sexp, so it will
evaluate the code you’re looking at, and that will
git clone el-get at the
Note that you can add this elisp code into your emacs init file directly, as
the installer code will detect if
el-get is already installed. Notice
that doing so directly will require internet access to start emacs. You can
avoid this with the following snippet instead:
(add-to-list 'load-path "~/.emacs.d/el-get/el-get") (unless (require 'el-get nil t) (url-retrieve "https://raw.github.com/dimitri/el-get/master/el-get-install.el" (lambda (s) (goto-char (point-max)) (eval-print-last-sexp))))
See next section for details about how to setup you emacs so that it’s able
to benefit from
How to install the developer version (master branch)?
The lazy installer uses the default
el-get-install.el file which targets
2.stable branch. To install el-get directly on the
el-get-master-branch variable into existence:
;; So the idea is that you copy/paste this code into your *scratch* buffer, ;; hit C-j, and you have a working developper edition of el-get. (url-retrieve "https://raw.github.com/dimitri/el-get/master/el-get-install.el" (lambda (s) (let (el-get-master-branch) (goto-char (point-max)) (eval-print-last-sexp))))
el-get is installed, simply use
M-x el-get-install and pick
whatever package you need. Arrange to have
el-get part of your setup, so
that at next emacs startup the installed packages are initialized. Here’s
(add-to-list 'load-path "~/.emacs.d/el-get/el-get") (unless (require 'el-get nil t) (with-current-buffer (url-retrieve-synchronously "https://raw.github.com/dimitri/el-get/master/el-get-install.el") (goto-char (point-max)) (eval-print-last-sexp))) (el-get 'sync)
That’s the basic setup.
Advanced setup with local recipes
Of course, my emacs setup is managed in a private git repository. Some
#emacs are using
git submodules (or was it straight import)
for managing external repositories in there, but all I can say is that I
frown on this idea. I want an easy canonical list of packages I depend on to
run emacs, and I want this documentation to be usable as-is. Enters el-get!
(add-to-list 'load-path "~/.emacs.d/el-get/el-get") (require 'el-get) ;; local sources (setq el-get-sources '((:name magit :after (lambda () (global-set-key (kbd "C-x C-z") 'magit-status))) (:name asciidoc :type elpa :after (lambda () (autoload 'doc-mode "doc-mode" nil t) (add-to-list 'auto-mode-alist '("\\.adoc$" . doc-mode)) (add-hook 'doc-mode-hook '(lambda () (turn-on-auto-fill) (require 'asciidoc))))) (:name lisppaste :type elpa) (:name emacs-goodies-el :type apt-get))) (setq my-packages (append '(cssh el-get switch-window vkill google-maps nxhtml xcscope yasnippet) (mapcar 'el-get-source-name el-get-sources))) (el-get 'sync my-packages)
So now you have a pretty good documentation of the packages you want installed, where to get them, and how to install them. For the advanced methods (such as elpa or apt-get), you basically just need the package name. When relying on a bare git repository, you need to give some more information, such as the URL to clone and the build steps if any. Then also what features to require and maybe where to find the texinfo documentation of the package, for automatic inclusion into your local Info menu.
The good news is that not only you now have a solid readable description of all that in a central place, but this very description is all (el-get) needs to do its magic. This command will check that each and every package is installed on your system (in el-get-dir) and if that’s not the case, it will actually install it. Then, it will init the packages: that means caring about the load-path, the Info-directory-list (and dir texinfo menu building) the loading of the emacs-lisp files, and finally it will require the features.
How to use it?
You see that
el-get-sources example up there? It finishes with a single
(el-get) call. That’s it. It will install new
sources on the list and
only init already installed ones.
The status of each package is tracked into
(by default) and can get the values
Sync or async?
Most often you want
el-get-build to stay out of the
way and be asynchronous, so that you can continue using Emacs while your
new package is getting ready. But imagine you’re starting up Emacs after a
git pull on the other computer (after a commute, say), and there’s some
newer packages for this instance to consider installing.
Now you want a synchronous install, right?
So, by default
(el-get) is asynchronous, but you can ask for it to be
sync, or to still be asynchronous but to wait until it finished before to
give control back:
(el-get 'sync) (el-get 'wait)
You even get a progress report!
See the documentation of the
el-get-sources variable for details. Please
el-get-sources is another source location for recipes, adding to
Note that you can also give a mix of
source lists to
el-get as arguments, and completely bypass the
(el-get 'sync 'package 'name 'list-of-packages-names-or-symbol)
It is still recommended to
(setq el-get-sources '(list of packages)) then
(el-get 'sync), so that commands such as
el-get-update know which
packages to update.
Some sources are contributed to
el-get directly, so that you only have to
put in the
el-get-sources the name of the package you want to
Should you need some local specific setup, you can do that by providing a
partial sources missing the
:type property: your local properties will get
merged into the recipes one.
Also, the variable
el-get-recipe-path allows you to maintain local recipes
in case you either dislike the default one or are crafting some new one not
commited to the main repository yet. But please do consider sending them
We do not intend to provide recipes for advanced types such as
elpa because there’s so little to win here, and maintaining a package list
would take too much time.
The package setup can either go into the
:after function, or in a file
el-get-user-package-directory. Any such named
file will get automatically loaded by
init time, if it exists.
make install, which will usually move files into a
"system location." In our case, you probably just want your package
foo to be all installed into
~/.emacs.d/el-get/foo, right? So, no
el-get will byte compile the elisp for the package when its source
definition includes a
:compile property set to the list of files to byte
compile (or to a single file), or all the
.el files found in the package
when there’s no
el-get offers a variety of specific hooks (read the source), and two
general purposes hooks facilities:
el-get-post-update-hooks, called with the package name as argument.
Some more commands?
- M-x el-get-list-packages
Opens a buffer listing all known packages (those for which you have a recipe). The listing includes the package name, its status (one of "available", "installed", "removed" or "required") and the package description. The description is a free form text and has not been provided for all recipes. Please also note that
el-get-emacswiki-refreshwill create recipes omitting the description as of now.
- M-x el-get-describe
Prompt for a package name, with completion, then open an
Helpwindow with details about the selected package. Those include current status, website, description, installation method, full recipe, and buttons to easily install, update or remove the package.
- M-x el-get-install
Will prompt for a package name, with completion, then install it. It will only propose packages that are not already
installed. Any package that you have a recipe for is a candidate.
Please note that when installing a package that is not in your
el-getcall means that it will not be initialized for you automatically at emacs startup. You get a
WARNINGmessage when that’s the case.
- M-x el-get-cd
Will prompt for an
installedpackage name, with completion, then open its directory with dired.
- M-x el-get-update
Will prompt for an installed package name, with completion, then update it. This will run the
initthe package again.
- M-x el-get-self-update
Update only one package,
- M-x el-get-update-all
Will update all packages used in
el-get-sources. Beware that using this function can lead to hours of settings review: more often than not updating a package requires some adjustments to your setup. Updating all of them at once will require reviewing almost all your setup.
- M-x el-get-reload
Reload the given package files. Happens automatically at update time too.
- M-x el-get-remove
Will prompt for an
installedpackage name, with completion, then remove it. Depending on the
typeof the package, this often means simply deleting the directory where the source package lies. Sometime we have to use external tools instead (
apt-get, e.g.). No effort is made to unload the features.
- M-x el-get-reinstall
This is just a shortcut for
el-get-installof the same package. It is primarily useful when a package has changed types, so the normal
el-get-updateprocess will not work correctly.
- M-x el-get-find-recipe-file
Will prompt for the name of a package, with completion, then
- M-x el-get-make-recipes
Will prompt for an existing directory where to output all your new recipe files: one file for each entry in
el-get-sourcesthat is not just a
symboland that is not found anywhere in
- M-x el-get-checksum
Will prompt for the name of an installed package, with complement, then compute its checksum if the package type supports that feature. The checksum is added to the kill-ring so that you’re ready to yank it into your
el-get-sources:checksum property if you want to.
- M-x el-get-emacswiki-refresh
Will launch a subprocess that connects to EmacsWiki and fetch from there the list of elisp scripts hosted. Then produce a recipe file per script, and store that in the given directory, which default to
~/.emacs.d/el-get/el-get/recipes/emacswiki/if you didn’t change
- el-get-package-types-alist (statuses &rest types)
Return an alist of package names that are of given types. Only consider packages whose status is ‘member’ of STATUSES, which defaults to installed, required and removed.
ELISP> (el-get-package-types-alist "installed" 'cvs 'emacswiki) ((emacs-w3m . cvs) (rect-mark . emacswiki) (icomplete+ . emacswiki) (php-mode-improved . emacswiki) (rainbow-delimiters . emacswiki) (goto-last-change . emacswiki) (emacs-goodies-el . cvs))
- el-get-extra-packages (&rest packages)
Return installed or required packages that are not in given package list.
ELISP> (el-get-extra-packages dim-packages) ((verbiste "installed") (package "installed"))
Please see the documentation for the
el-get-methods and provide a patch!
bzr support for example was only about writing 2 functions, mostly
using copy paste. Here’s the patch: https://github.com/dimitri/el-get/commit/63e9018102bdeb7b6d9136db231adcd983087217#L0R437
Upgrading to 3.1
A change has been included so that
el-get-sources is now only another
source for recipes, and
(el-get '…) will now only install and initialize
known "required" and "installed" packages.
The documentation has been updated to detail the new setup.
If you have packages that have been installed in the past but you no longer want in your setup, here’s how to get them out of the way:
M-: (el-get-save-package-status "package-name-here" "removed")
Please review documentation section Advanced setup with local recipes.