README.md

Emacs Prelude

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.

Fast Forward

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:

curl -L https://git.io/epre | sh

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:

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.

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 C-x C-e.

Running

Nothing fancy here. Just start Emacs as usual. Personally I run Emacs
in daemon mode:

emacs --daemon

Afterwards I connect to the server with either a terminal or a GUI
client like this:

emacsclient -t
emacsclient -c

You'd probably do well to put a few aliases in your .zshrc (or
.bashrc):

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:

emacsclient somefile:1234

This will open file 'somefile' and set cursor on line 1234.

Getting to know Prelude

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.

Keymap

Global

Keybinding

Description

C-x \

align-regexp

C-+

Increase font size(text-scale-increase).

C--

Decrease font size(text-scale-decrease).

C-x O

Go back to previous window (the inverse of other-window (C-x o)).

C-^

Join two lines into one(crux-top-join-line).

C-x p

Start proced (manage processes from Emacs; works only in Linux).

C-x m

Start eshell.

C-x M-m

Start your default shell.

C-x C-m

Alias for M-x.

M-X

Like M-x but limited to commands that are relevant to the active major mode.

C-h A

Run apropos (search in all Emacs symbols).

C-h C-m

Display key bindings of current major mode and descriptions of every binding.

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).

OSX modifier keys

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:

(setq mac-command-modifier 'meta)
(setq mac-option-modifier 'super)

You can also temporarily swap them with C-c w (M-x prelude-swap-meta-and-super).

Helm

You can learn Helm usage and key bindings following the guide. C-c h is Prelude's default prefix key for Helm.
If you don't remember any key binding, append C-h after C-c h 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:

Run helm-locate-library that can search for locations of any file loaded into Emacs.

This key binding is activated in shell-mode:

Key Binding

Description

C-c C-l

Run helm-comint-input-ring that shows shell history using Helm interface.

This key bindings is activated in eshell-mode:

Key Binding

Description

C-c C-l

Run helm-eshell-history that shows eshell history using Helm interface.

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 AFTER 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

Key-chords are available only when the prelude-key-chord module has been enabled.

Keybinding

Description

jj

Jump to the beginning of a word(avy-goto-word-1)

jk

Jump to a character(avy-goto-char)

jl

Jump to the beginning of a line(avy-goto-line)

JJ

Jump back to previous buffer(crux-switch-to-previous-buffer)

uu

View edits as a tree(undo-tree-visualize)

xx

Executed extended command(execute-extended-command)

yy

Browse the kill ring(browse-kill-ring)

Disabling key-chords

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:

(key-chord-define-global "jj"nil)

If you're an evil-mode user you'll probably do well to disable key-chord-mode altogether:

(key-chord-mode -1)

vim emulation

If you want to use vim inside of emacs enable the prelude-evil module which provides
support for evil-mode.

Automatic package installation

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.

Color Themes

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:

(disable-theme 'zenburn)

Or you can use another theme altogether by adding something in personal/preload like:

(setq prelude-theme 'solarized-dark)

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:

(setq prelude-theme nil)

Personalizing

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:

(prelude-require-packages '(some-package some-other-package))

If you require just a single package you can also use:

(prelude-require-package 'some-package)

Preloading personal config

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).

Disabling whitespace-mode

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:

(setq prelude-whitespace nil)

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:

(setq prelude-clean-whitespace-on-save nil)

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.

Disable flyspell-mode

If you're not fond of spellchecking on the fly:

(setq prelude-flyspell nil)

Caveats & Pitfalls

Updating bundled packages

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.

Problems with flyspell-mode

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:

brew install aspell --with-lang=en

On Linux distros - just use your distro's package manager.

Ugly colors in the terminal Emacs version

If your Emacs looks considerably uglier in a terminal (compared to the
GUI version) try adding this to your .bashrc or .zshrc:

export TERM=xterm-256color

Source the .bashrc file and start Emacs again.

MELPA error on initial startup

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.

Warnings on arrow navigation in editor buffers

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:

(setq guru-warn-only nil)

To disable guru-mode completely add the following snippet to your
personal Emacs config:

(setq prelude-guru nil)

Customized C-a behavior

Prelude overrides C-a to behave as described
here. If
you don't like that simply add this to your personal config: