Last updated: 2024-01-17 13:29:58 +0000
Upstream URL: git clone http://chriswarbo.net/git/warbo-emacs-d.git
Contents of README.md follows
Prelude is an Emacs distribution that aims to enhance the default Emacs experience. Prelude alters a lot of the default settings, bundles a plethora of additional packages and adds its own core library to the mix. The final product offers an easy to use Emacs configuration for Emacs newcomers and lots of additional power for Emacs power users.
Prelude is compatible ONLY with GNU Emacs 24.4+. In general you’re advised to always run Prelude with the latest Emacs - currently 25.1.
You can support the development of Prelude via Salt and Gratipay.
Table of Contents
<ul> <li>Fast Forward</li> <li>Installing Emacs</li> <li>Installation <ul> <li>Automated <ul> <li>Via Curl</li> <li>Via Wget</li> </ul></li> <li>Manual</li> </ul></li> <li>Updating Prelude <ul> <li>Manual update <ul> <li>Update all bundled packages</li> <li>Update Prelude’s code</li> <li>Restart Prelude</li> </ul></li> <li>Automatic update</li> </ul></li> <li>Enabling additional modules</li> <li>Running</li> <li>Getting to know Prelude <ul> <li>Keymap <ul> <li>Global</li> <li>Prelude Mode</li> <li>OSX modifier keys</li> <li>Projectile</li> <li>Helm</li> <li>Key-chords <ul> <li>Disabling key-chords</li> </ul></li> </ul></li> </ul></li> <li>Automatic package installation <ul> <li>Color Themes</li> <li>Personalizing <ul> <li>Disabling whitespace-mode</li> <li>Disable flyspell-mode</li> </ul></li> </ul></li> <li>Caveats & Pitfalls <ul> <li>Updating bundled packages</li> <li>Problems with flyspell-mode</li> <li>Ugly colors in the terminal Emacs version</li> <li>MELPA error on initial startup</li> <li>Warnings on arrow navigation in editor buffers</li> <li>Customized C-a behavior</li> <li>Poor ido matching performance on large datasets</li> <li>Windows compatibility</li> </ul></li> <li>Known issues</li> <li>Support</li> <li>Contributors</li> <li>Bugs & Improvements</li> </ul>Assuming you’re using an Unix-like OS (*BSD
,
GNU/Linux
, OS X
, Solaris
, etc),
you already have Emacs 24.4+ installed, as well as git
& curl
you can skip the whole manual and just type in
your favorite shell the following command:
You can now power up your Emacs, sit back and enjoy Prelude, forgetting about the rest of this manual.
There are two environment variables you can use to control the source repository and the installation directory. To change the installation directory:
export PRELUDE_INSTALL_DIR="$HOME/.emacs.d" && curl -L https://github.com/bbatsov/prelude/raw/master/utils/installer.sh | sh
To change the source repository:
export PRELUDE_URL="https://github.com/yourname/prelude.git" && curl -L https://github.com/bbatsov/prelude/raw/master/utils/installer.sh | sh
Note that the installer will back up any existing .emacs
file or .emacs.d
since it will unpack Prelude’s code in
.emacs.d
. If you’re doing a manual install make sure you
don’t have a .emacs
file or back up your existing
.emacs.d
directory manually.
Don’t forget to adjust your prelude-modules.el
file once
the installation is done. By default most of the modules that ship with
Prelude are not loaded.
Obviously to use the Emacs Prelude you have to install Emacs first. Have a look at the WikEmacs articles on installing Emacs.
You can install Emacs Prelude via the command line
with either curl
or wget
. Naturally
git
is also required.
If you’re using curl
type the following command:
If you’re using wget
type:
wget --no-check-certificate https://github.com/bbatsov/prelude/raw/master/utils/installer.sh -O - | sh
git clone git://github.com/bbatsov/prelude.git path/to/local/repo
ln -s path/to/local/repo ~/.emacs.d
cd ~/.emacs.d
If you are using Windows, you should check what Emacs thinks the
~
directory is by running Emacs and typing
C-x d ~/<RET>
, and then adjust the command
appropriately.
The update procedure is fairly straightforward and consists of 3 steps:
Just run <kbd>M-x package-list-packages RET U x</kbd>.
The path/to/prelude/installation
is usually
~/.emacs.d
(at least on Unix systems).
It’s generally a good idea to stop Emacs after you do the update. The next time Prelude starts it will install any new dependencies (if there are such).
Simply run <kbd>M-x prelude-update</kbd> from Emacs itself and restart Emacs afterwards.
By default most of the modules that ship with Prelude are not loaded. For more information on the functionality provided by these modules visit the docs.
;;; Uncomment the modules you'd like to use and restart Prelude afterwards
(require 'prelude-c)
;; (require 'prelude-clojure)
;; (require 'prelude-coffee)
;; (require 'prelude-common-lisp)
(require 'prelude-css)
(require 'prelude-emacs-lisp)
(require 'prelude-erc)
;; (require 'prelude-erlang)
;; (require 'prelude-elixir)
(require 'prelude-haskell)
(require 'prelude-js)
(require 'prelude-latex)
(require 'prelude-lisp)
;; (require 'prelude-mediawiki)
(require 'prelude-org)
;; (require 'prelude-perl)
(require 'prelude-python)
;; (require 'prelude-ruby)
;; (require 'prelude-scala)
(require 'prelude-scheme)
;; (require 'prelude-scss)
(require 'prelude-web)
(require 'prelude-xml)
You’ll need to adjust your prelude-modules.el
file once
the installation is done. If you are doing a manual install then you
first need to copy the prelude-modules.el
available in the
sample directory to the root of
path/to/prelude/installation
and then adjust that one.
After you’ve uncommented a module you should either restart Emacs or
evaluate the module require
expression with <kbd>C-x
C-e</kbd>.
Nothing fancy here. Just start Emacs as usual. Personally I run Emacs in daemon mode:
Afterwards I connect to the server with either a terminal or a GUI client like this:
You’d probably do well to put a few aliases in your
.zshrc
(or .bashrc
):
alias e='emacsclient -t'
alias ec='emacsclient -c'
alias vim='emacsclient -t'
alias vi='emacsclient -t'
The last two aliases are helpful if you’re used to editing files from
the command line using vi(m)
.
Also you can open a file with cursor on choosen line:
This will open file ‘somefile’ and set cursor on line 1234.
Certainly the best way to understand how Prelude enhances the default
Emacs experience is to peruse Prelude’s source code (which is obviously
written in Emacs Lisp). Understanding the code is not necessary of
course. Prelude includes a prelude-mode
minor Emacs mode
which collects some of the additional functionality added by Prelude. It
also adds an additional keymap that binds many of those extensions to
keybindings.
align-regexp
</td>
</tr>
<tr class="even">
<td><kbd>C-+</kbd></td>
<td>Increase font size(text-scale-increase
).</td>
</tr>
<tr class="odd">
<td><kbd>C–</kbd></td>
<td>Decrease font size(text-scale-decrease
).</td>
</tr>
<tr class="even">
<td><kbd>C-x O</kbd></td>
<td>Go back to previous window (the inverse of other-window
(C-x o
)).</td>
</tr>
<tr class="odd">
<td><kbd>C-^</kbd></td>
<td>Join two lines into one(crux-top-join-line
).</td>
</tr>
<tr class="even">
<td><kbd>C-x p</kbd></td>
<td>Start proced
(manage processes from Emacs; works only
in Linux).</td>
</tr>
<tr class="odd">
<td><kbd>C-x m</kbd></td>
<td>Start eshell
.</td>
</tr>
<tr class="even">
<td><kbd>C-x M-m</kbd></td>
<td>Start your default shell.</td>
</tr>
<tr class="odd">
<td><kbd>C-x C-m</kbd></td>
<td>Alias for M-x
.</td>
</tr>
<tr class="even">
<td><kbd>M-X</kbd></td>
<td>Like M-x
but limited to commands that are relevant to
the active major mode.</td>
</tr>
<tr class="odd">
<td><kbd>C-h A</kbd></td>
<td>Run apropos
(search in all Emacs symbols).</td>
</tr>
<tr class="even">
<td><kbd>C-h C-m</kbd></td>
<td>Display key bindings of current major mode and descriptions of every
binding.</td>
</tr>
<tr class="odd">
<td><kbd>M-/</kbd></td>
<td>Run hippie-expand
(a replacement for the default
dabbrev-expand
).</td>
</tr>
<tr class="even">
<td><kbd>C-x C-b</kbd></td>
<td>Open ibuffer
(a replacement for the default
buffer-list
).</td>
</tr>
<tr class="odd">
<td><kbd>F11</kbd></td>
<td>Make the window full screen.</td>
</tr>
<tr class="even">
<td><kbd>F12</kbd></td>
<td>Toggle the Emacs menu bar.</td>
</tr>
<tr class="odd">
<td><kbd>C-x g</kbd></td>
<td>Open Magit’s status buffer.</td>
</tr>
<tr class="even">
<td><kbd>C-x M-g</kbd></td>
<td>Open Magit’s popup of popups.</td>
</tr>
<tr class="odd">
<td><kbd>M-Z</kbd></td>
<td>Zap up to char.</td>
</tr>
<tr class="even">
<td><kbd>C-=</kbd></td>
<td>Run expand-region
(incremental text selection).</td>
</tr>
<tr class="odd">
<td><kbd>C-a</kbd></td>
<td>Run crux-move-beginning-of-line
. Read this
for details.</td>
</tr>
</tbody>
</table>
ansi-term
).</td>
</tr>
<tr class="even">
<td><kbd>C-c k</kbd></td>
<td>Kill all open buffers except the one you’re currently in.</td>
</tr>
<tr class="odd">
<td><kbd>C-c TAB</kbd></td>
<td>Indent and copy region to clipboard</td>
</tr>
<tr class="even">
<td><kbd>C-c I</kbd></td>
<td>Open user’s init file.</td>
</tr>
<tr class="odd">
<td><kbd>C-c S</kbd></td>
<td>Open shell’s init file.</td>
</tr>
<tr class="even">
<td><kbd>C-c . +</kbd></td>
<td>Increment integer at point. Default is +1.</td>
</tr>
<tr class="odd">
<td><kbd>C-c . -</kbd></td>
<td>Decrement integer at point. Default is -1.</td>
</tr>
<tr class="even">
<td><kbd>C-c . *</kbd></td>
<td>Multiply integer at point. Default is *2.</td>
</tr>
<tr class="odd">
<td><kbd>C-c . /</kbd></td>
<td>Divide integer at point. Default is /2.</td>
</tr>
<tr class="even">
<td><kbd>C-c . \</kbd></td>
<td>Modulo integer at point. Default is modulo 2.</td>
</tr>
<tr class="odd">
<td><kbd>C-c . ^</kbd></td>
<td>Power to the integer at point. Default is ^2.</td>
</tr>
<tr class="even">
<td><kbd>C-c . <</kbd></td>
<td>Left-shift integer at point. Default is 1 position to the left.</td>
</tr>
<tr class="odd">
<td><kbd>C-c . ></kbd></td>
<td>Right-shift integer at point. Default is 1 position to the
right.</td>
</tr>
<tr class="even">
<td><kbd>C-c . #</kbd></td>
<td>Convert integer at point to specified base. Default is 10.</td>
</tr>
<tr class="odd">
<td><kbd>C-c . %</kbd></td>
<td>Replace integer at point with another specified integer.</td>
</tr>
<tr class="even">
<td><kbd>C-c . ’</kbd></td>
<td>Perform arithmetic operations on integer at point. User specifies
the operator.</td>
</tr>
<tr class="odd">
<td><kbd>Super-g</kbd></td>
<td>Toggle between God mode and non-God mode</td>
</tr>
<tr class="even">
<td><kbd>Super-r</kbd></td>
<td>Recent files</td>
</tr>
<tr class="odd">
<td><kbd>Super-j</kbd></td>
<td>Join lines</td>
</tr>
<tr class="even">
<td><kbd>Super-k</kbd></td>
<td>Kill whole line</td>
</tr>
<tr class="odd">
<td><kbd>Super-m m</kbd></td>
<td>Magit status</td>
</tr>
<tr class="even">
<td><kbd>Super-m l</kbd></td>
<td>Magit log</td>
</tr>
<tr class="odd">
<td><kbd>Super-m f</kbd></td>
<td>Magit file log</td>
</tr>
<tr class="even">
<td><kbd>Super-m b</kbd></td>
<td>Magit blame mode</td>
</tr>
</tbody>
</table>
Note: For various arithmetic operations, the prefix
C-c .
only needs to be pressed once for the first
operation. For subsequent operations, only the appropriate operations
(i.e. +
, -
, *
, /
…
needs to be pressed).
Prelude does not mess by default with the standard mapping of
Command
(to Super
) and Option
(to
Meta
).
If you want to swap them add this to your personal config:
You can also temporarily swap them with C-c w
(M-x prelude-swap-meta-and-super
).
Here’s a list of functionality provided by Projectile:
<table> <colgroup> <col style="width: 24%" /> <col style="width: 75%" /> </colgroup> <thead> <tr class="header"> <th>Keybinding</th> <th>Description</th> </tr> </thead> <tbody> <tr class="odd"> <td><kbd>C-c p f</kbd></td> <td>Display a list of all files in the project. With a prefix argument it will clear the cache first.</td> </tr> <tr class="even"> <td><kbd>C-c p d</kbd></td> <td>Display a list of all directories in the project. With a prefix argument it will clear the cache first.</td> </tr> <tr class="odd"> <td><kbd>C-c p T</kbd></td> <td>Display a list of all test files(specs, features, etc) in the project.</td> </tr> <tr class="even"> <td><kbd>C-c p s g</kbd></td> <td>Run grep on the files in the project.</td> </tr> <tr class="odd"> <td><kbd>M– C-c p s g</kbd></td> <td>Run grep onprojectile-grep-default-files
in the
project.</td>
</tr>
<tr class="even">
<td><kbd>C-c p b</kbd></td>
<td>Display a list of all project buffers currently open.</td>
</tr>
<tr class="odd">
<td><kbd>C-c p o</kbd></td>
<td>Runs multi-occur
on all project buffers currently
open.</td>
</tr>
<tr class="even">
<td><kbd>C-c p r</kbd></td>
<td>Runs interactive query-replace on all files in the projects.</td>
</tr>
<tr class="odd">
<td><kbd>C-c p i</kbd></td>
<td>Invalidates the project cache (if existing).</td>
</tr>
<tr class="even">
<td><kbd>C-c p R</kbd></td>
<td>Regenerates the projects TAGS
file.</td>
</tr>
<tr class="odd">
<td><kbd>C-c p k</kbd></td>
<td>Kills all project buffers.</td>
</tr>
<tr class="even">
<td><kbd>C-c p D</kbd></td>
<td>Opens the root of the project in dired
.</td>
</tr>
<tr class="odd">
<td><kbd>C-c p e</kbd></td>
<td>Shows a list of recently visited project files.</td>
</tr>
<tr class="even">
<td><kbd>C-c p s a</kbd></td>
<td>Runs ack
on the project. Requires the presence of
ack-and-a-half
.</td>
</tr>
<tr class="odd">
<td><kbd>C-c p s s</kbd></td>
<td>Runs ag
on the project. Requires the presence of
ag.el
.</td>
</tr>
<tr class="even">
<td><kbd>C-c p a</kbd></td>
<td>Switch between files with the same name but different
extensions.</td>
</tr>
<tr class="odd">
<td><kbd>C-c p c</kbd></td>
<td>Runs a standard compilation command for your type of project.</td>
</tr>
<tr class="even">
<td><kbd>C-c p P</kbd></td>
<td>Runs a standard test command for your type of project.</td>
</tr>
<tr class="odd">
<td><kbd>C-c p z</kbd></td>
<td>Adds the currently visited to the cache.</td>
</tr>
<tr class="even">
<td><kbd>C-c p p</kbd></td>
<td>Display a list of known projects you can switch to.</td>
</tr>
</tbody>
</table>
Prelude adds an extra keymap prefix S-p
(S
stands for Super
), so you can use S-p
instead
of C-c p
.
If you ever forget any of Projectile’s keybindings just do a:
<kbd>C-c p C-h</kbd>
Helm is setup according to this guide: A Package in a league of its own: Helm.
You can learn Helm usage and key bindings following the guide. <kbd>C-c h</kbd> is Prelude’s default prefix key for Helm. If you don’t remember any key binding, append <kbd>C-h</kbd> after <kbd>C-c h</kbd> for a list of key bindings in Helm.
If you love Helm and want to use Helm globally with enhanced
helm-find-files
, helm-buffer-lists
…, you will
have to also add (require 'prelude-helm-everywhere)
. When
prelude-helm-everywhere
is activated, Helm enables these
global key bindings:
kill-ring
.</td>
</tr>
<tr class="odd">
<td><kbd>C-x b </kbd></td>
<td>Run helm-mini, an
interactive version of C-x b
with more features.</td>
</tr>
<tr class="even">
<td><kbd>C-x C-f</kbd></td>
<td>Run helm-find-files,
an interactive version of find-file
with more
features.</td>
</tr>
<tr class="odd">
<td><kbd>C-h f </kbd></td>
<td>Run helm-apropos,
an interactive version of apropos-command
.</td>
</tr>
<tr class="even">
<td><kbd>C-h r</kbd></td>
<td>Run helm-info-emacs,
an interactive version of info-emacs-manual
.</td>
</tr>
<tr class="odd">
<td><kbd>C-h C-l </kbd></td>
<td>Run helm-locate-library
that can search for locations
of any file loaded into Emacs.</td>
</tr>
</tbody>
</table>
This key binding is activated in shell-mode
:
helm-comint-input-ring
that shows
shell
history using Helm interface.</td>
</tr>
</tbody>
</table>
This key bindings is activated in eshell-mode
:
helm-eshell-history
that shows eshell
history using Helm interface.</td>
</tr>
</tbody>
</table>
If you prefer Ido in everywhere, you should not add
prelude-helm-everywhere
, so you can use Helm along with Ido
and Prelude’s default commands.
You can always reactivate Helm with
(prelude-global-helm-global-mode-on)
.
NOTICE: In helm-M-x
, you have to pass
prefix argument <em>AFTER</em> you run helm-M-x
, because
your prefix argument will be displayed in the modeline when in
helm-M-x
buffer. Passing prefix argument
BEFORE =helm-M-x= has no effect.
Key-chords are available only when the
prelude-key-chord
module has been enabled.
avy-goto-word-1
)</td>
</tr>
<tr class="even">
<td><kbd>jk</kbd></td>
<td>Jump to a character(avy-goto-char
)</td>
</tr>
<tr class="odd">
<td><kbd>jl</kbd></td>
<td>Jump to the beginning of a line(avy-goto-line
)</td>
</tr>
<tr class="even">
<td><kbd>JJ</kbd></td>
<td>Jump back to previous
buffer(crux-switch-to-previous-buffer
)</td>
</tr>
<tr class="odd">
<td><kbd>uu</kbd></td>
<td>View edits as a tree(undo-tree-visualize
)</td>
</tr>
<tr class="even">
<td><kbd>xx</kbd></td>
<td>Executed extended
command(execute-extended-command
)</td>
</tr>
<tr class="odd">
<td><kbd>yy</kbd></td>
<td>Browse the kill ring(browse-kill-ring
)</td>
</tr>
</tbody>
</table>
<h5 id="disabling-key-chords">Disabling key-chords</h5>
In some cases you may not want to have a key-chord that is defined by
prelude, in which case you can disable the binding in your
personal.el
file by setting its command to
nil
. For example, to disable the jj
key-chord
add the following line:
If you’re an evil-mode
user you’ll probably do well to
disable key-chord-mode
altogether:
If you want to use vim inside of emacs enable the
prelude-evil
module which provides support for
evil-mode
.
The default Prelude installation comes with a bare minimum of
functionality. It will however install add-ons for various programming
languages and frameworks on demand. For instance - if you try to open a
.clj
file clojure-mode
, cider
and
Prelude’s enhanced Lisp configuration will be installed automatically
for you.
You can, of course, install anything you wish manually as well.
Emacs provides a dozen of built-in themes you can use out-of-the-box
by invoking the M-x load-theme
command.
Zenburn is the default color theme in Prelude, but you can change it at your discretion. Why Zenburn? I (and lots of hackers around the world) find it pretty neat for some reason. Personally I find the default theme pretty tiresome for the eyes, that’s why I took that “controversial” decision to replace it. You can, of course, easily go back to the default (or select another theme entirely).
To disable Zenburn just put in your personal config the following line:
Or you can use another theme altogether by adding something in
personal/preload
like:
P.S. Solarized is not available by default - you’ll
have to install it from MELPA first
(M-x package-install RET solarized-theme
).
Finally, if you don’t want any theme at all, you can add this to your
personal/preload
:
Fork the official Prelude repo and add your own touch to it. You’re advised to avoid changing stuff outside of the personal folder to avoid having to deal with git merge conflicts in the future.
If you’d like to add some auto installation of packages in your personal config use the following code:
If you require just a single package you can also use:
Sometimes you might want to load code before Prelude has started
loading. Prelude will automatically preload all Emacs Lisp files in your
personal/preload
directory. Note that at this point you
can’t using anything from Prelude, except a few variables like
prelude-dir
, etc (since nothing is yet loaded).
Although whitespace-mode
is awesome some people might
find it too intrusive. You can disable it in your personal config with
the following bit of code:
If you like whitespace-mode
but prefer it to not
automatically cleanup your file on save, you can disable that behavior
by setting prelude-clean-whitespace-on-save to nil in your config file
with:
The prelude-clean-whitespace-on-save setting can also be set on a per-file or directory basis by using a file variable or a .dir-locals.el file.
If you’re not fond of spellchecking on the fly:
Generally it’s a good idea to do a package update before running updating Prelude, since the latest Prelude code might depend on newer versions of the bundled packages than you would currently have installed.
If you’re doing manual Prelude updates you should always do a package update first.
M-x package-list-packages RET U x
That’s not necessary if you’re using M-x prelude-update
,
since it will automatically update the installed packages.
Prelude makes heavy use of the flyspell-mode package for spell
checking of various things. The proper operation of flyspell depends on
the presence of the aspell
program and an en
dictionary on your system. You can install aspell
and the
dictionary on OS X with homebrew
like this:
On Linux distros - just use your distro’s package manager.
If your Emacs looks considerably uglier in a terminal (compared to
the GUI version) try adding this to your .bashrc
or
.zshrc
:
Source the .bashrc
file and start Emacs again.
If you get some http connection error related to the MELPA repo just
do a manual M-x package-refresh-contents
and restart Emacs
afterwards.
This is not a bug - it’s a feature! I firmly believe that the one true way to use Emacs is by using it the way it was intended to be used (as far as navigation is concerned at least).
If you’d like to be take this a step further and disable the arrow key navigation completely put this in your personal config:
To disable guru-mode
completely add the following
snippet to your personal Emacs config:
Prelude overrides C-a
to behave as described here.
If you don’t like that simply add this to your personal config:
Prelude swaps the default ido
flex matching with the
more powerful ido-flx.
The sorting algorithm flx
uses is more complex, but
yields better results.
On slower machines, it may be necessary to lower
flx-ido-threshold
to ensure a smooth experience.
You can always disable the improved sorting algorithm all together like this:
While everything in Prelude should work fine in Windows, I test it only with Linux & OS X, so there are Windows related problems from time to time. This situation will probably improve over time.
Check out the project’s issue list a list of unresolved issues. By the way - feel free to fix any of them and send me a pull request. :-)
Support is available via the Prelude Google Group emacs-prelude@googlegroups.com.
There’s also a Freenode channel you can visit -
#prelude-emacs
.
Here’s a list of all the people who have contributed to the development of Emacs Prelude.
Bug reports and suggestions for improvements are always welcome. GitHub pull requests are even better! :-)
Cheers,<br/> Bozhidar