6/28/2014

bbatsov/prelude

PUBLIC

This repository

Search or type a command

Explore

Gist

Blog

Help

yawo

Watch

bbatsov / prelude

139

Star

Prelude is an enhanced Emacs 24 distribution that should make your experience with Emacs both more
pleasant and more powerful.
874 commits

branch: master

2 branches

0 releases

Merge pull request #587 from swhalen/two-quicklisp-dirs

Fork

Issues

719

33

Pull Requests

Wiki

latest commit 5445a40453

bbatsov authored 3 days ago

Code

67 contributors

prelude /

1,531

core

Prefer advice over remap exchange-point-and-mark

modules

Merge pull request #587 from swhalen/two-quicklisp-dirs

personal

[Fix #451] Add the ability to preload personal code

sample

Add Go module

24 days ago

themes

restored accidentally deleted dirs

2 years ago

utils

Various install-script fixes

20 days ago

vendor

Don't use dash.el during package init

.gitignore

Ignore pcache directory

.projectile

[Fix #447] Extract ido config into a module

CONTRIBUTING.md

added contribution guidelines

2 years ago

README.md

Rename buffer not visiting files

24 days ago

init.el

Add comment documenting load dependency

a month ago

Pulse

20 days ago
3 days ago
7 months ago

Graphs
Network
HTTPS clone URL

https://github.com/b
batsov/prelude
You can clone with HTTPS, SSH,
or Subversion.

a year ago

Clone in Desktop
a month ago
7 months ago

Download ZIP

README.md

license GPL3

tips $11/week

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.x. In general you're advised to always run Prelude with the
latest Emacs - currently 24.3.
Table of Contents
Fast Forward
Installing Emacs 24
Installation
Automated
Via Curl
Via Wget
Manual
Updating Prelude
Manual update
Update all bundled packages
Update Prelude's code
Restart Prelude

https://github.com/bbatsov/prelude

1/11

6/28/2014

bbatsov/prelude
Automatic update
Enabling additional modules
Running
Getting to know Prelude
Keymap
Global
Prelude Mode
OSX modifier keys
Projectile
Key-chords
Disabling key-chords
Automatic package installation
Color Themes
Personalizing
Disabling whitespace-mode
Disable flyspell-mode
Caveats & Pitfalls
Updating bundled packages
Problems with flyspell-mode
Ugly colors in the terminal Emacs version
MELPA error on initial startup
No arrow navigation in editor buffers
Customized C-a behavior
Poor ido matching performance on large datasets
Windows compatibility
Known issues
Support
Contributors
Bugs & Improvements

Fast Forward
Assuming you're using an Unix-like OS (
installed, as well as

git

&

curl

*BSD , GNU/Linux , OS X , Solaris ,

etc), you already have Emacs 24

you can skip the whole manual and just type in your favorite shell the

following command:
curl -L http://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:
export PRELUDE_INSTALL_DIR="$HOME/.emacs.d" && curl -L https://github.com/bbatsov/prelude/raw/master/utils/installer.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/ins

Note that the installer will back up any existing

.emacs.d .
.emacs.d

.emacs

file or

.emacs.d

If you're doing a manual install make sure you don't have a

since it will unpack Prelude's code in

.emacs

file or back up your existing

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.

Installing Emacs 24
Obviously to use the Emacs Prelude you have to install Emacs 24 first. Have a look at the WikEmacs articles
on installing Emacs.

https://github.com/bbatsov/prelude

2/11

6/28/2014

bbatsov/prelude

Installation
Automated
You can install Emacs Prelude via the command line with either

curl

or

wget .

Naturally

git

is also required.

Via Curl
If you're using

curl

type the following command:

curl -L https://github.com/bbatsov/prelude/raw/master/utils/installer.sh | sh

Via Wget
If you're using

wget

type:

wget --no-check-certificate https://github.com/bbatsov/prelude/raw/master/utils/installer.sh -O -

Manual
git clone git://github.com/bbatsov/prelude.git path/to/local/repo
ln -s path/to/local/repo ~/.emacs.d
cd ~/.emacs.d

You'd do well to replace

value by doing

~/.emacs.d

with the value of

C-h v user-emacs-directory

user-emacs-directory

for your OS. You can check the

inside Emacs.

Updating Prelude
Manual update
The update procedure is fairly straightforward and consists of 3 steps:

Update all bundled packages

Just run M-x package-list-packages RET U x .

Update Prelude's code

cd path/to/prelude/installation
git pull

The

path/to/prelude/installation

is usually

~/.emacs.d

(at least on Unix systems).

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

Automatic update
Simply run M-x prelude-update from Emacs itself and restart Emacs afterwards.

Enabling additional modules

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

https://github.com/bbatsov/prelude

3/11

6/28/2014

bbatsov/prelude
(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-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

then you first need to copy the

file once the installation is done. If you are doing a manual install

prelude-modules.el

path/to/prelude/installation

available in the sample directory to the root of

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

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

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
C-M-h
C-x

Description
Kill the previous word(

backward-kill-word ).

(as in Bash/Zsh)

align-regexp

https://github.com/bbatsov/prelude

4/11

6/28/2014

bbatsov/prelude
C-+

Increase font size(

C--

Decrease font size(

C-x O

Go back to previous window (the inverse of

C-^

Join two lines into one(

C-x p

Start

proced

C-x m

Start

eshell .

C-x M-m

Start your default shell.

C-x C-m

Alias for

C-h A

Run

C-h C-m

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

M-/

Run

C-x C-b

Open

F11

Make the window full screen.

F12

Toggle the Emacs menu bar.

C-x g

Open Magit's status buffer.

C-=

Run

expand-region

C-a

Run

prelude-move-beginning-of-line .

text-scale-increase ).
text-scale-decrease ).
other-window

C-x o )).

prelude-top-join-line ).

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

M-x .

apropos

(search in all Emacs symbols).

hippie-expand
ibuffer

(a replacement for the default

(a replacement for the default

dabbrev-expand ).

buffer-list ).

(incremental text selection).

Read this for details.

Prelude Mode
Keybinding

Description

C-c o

Open the currently visited file with an external program.

C-c i

Search for a symbol, only for buffers that contain code

C-c g

Search in Google for the thing under point (or an interactive query).

C-c G

Search in GitHub for the thing under point (or an interactive query).

C-c y

Search in YouTube for the thing under point (or an interactive query).

C-c U

Search in Duckduckgo for the thing under point (or an interactive query).

C-S-RET or Super-o

Insert an empty line above the current line and indent it properly.

S-RET or M-o

Insert an empty line and indent it properly (as in most IDEs).

C-S-up or M-S-up

Move the current line or region up.

C-S-down or M-Sdown

Move the current line or region down.

C-c n

Fix indentation in buffer and strip whitespace.

C-c f

Open recently visited file.

C-M-

Indent region (if selected) or the entire buffer.

C-c u

Open URL in your default browser.

C-c e

Eval a bit of Emacs Lisp code and replace it with its result.

C-c s

Swap two active windows.

C-c D

Delete current file and buffer.

C-c d

Duplicate the current line (or region).

C-c M-d

Duplicate and comment the current line (or region).

https://github.com/bbatsov/prelude

5/11

6/28/2014

bbatsov/prelude
C-c r

Rename the current buffer and its visiting file if any.

C-c t

Open a terminal emulator (

C-c k

Kill all open buffers except the one you're currently in.

C-c TAB

Indent and copy region to clipboard

C-c h

Open Helm (available if you've enabled the

C-c I

Open user's init file.

C-c S

Open shell's init file.

C-c . +

Increment integer at point. Default is +1.

C-c . -

Decrement integer at point. Default is -1.

C-c . *

Multiply integer at point. Default is *2.

C-c . /

Divide integer at point. Default is /2.

C-c . </kbd>

Modulo integer at point. Default is modulo 2.

C-c . ^

Power to the integer at point. Default is ^2.

C-c . <

Left-shift integer at point. Default is 1 position to the left.

C-c . >

Right-shift integer at point. Default is 1 position to the right.

C-c . #

Convert integer at point to specified base. Default is 10.

C-c . %

Replace integer at point with another specified integer.

C-c . '

ansi-term ).

prelude-helm

module).

Perform arithmetic operations on integer at point. User specifies the

operator.

Super-r

Recent files

Super-x

Expand region

Super-j

Join lines

Super-k

Kill whole line

Super-m m

Magit status

Super-m l

Magit log

Super-m f

Magit file log

Super-m b

Magit blame mode

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

Projectile
Here's a list of functionality provided by Projectile:
Keybinding

https://github.com/bbatsov/prelude

Description

6/11

6/28/2014

bbatsov/prelude
C-c p f
C-c p d

Display a list of all files in the project. With a prefix argument it will clear the cache first.
Display a list of all directories in the project. With a prefix argument it will clear the cache
first.

C-c p T

Display a list of all test files(specs, features, etc) in the project.

C-c p g

Run grep on the files in the project.

C-c p b

Display a list of all project buffers currently open.

C-c p o

Runs

C-c p r

Runs interactive query-replace on all files in the projects.

C-c p i

Invalidates the project cache (if existing).

C-c p R

Regenerates the projects

C-c p k

Kills all project buffers.

C-c p D

Opens the root of the project in

C-c p e

Shows a list of recently visited project files.

C-c p a

Runs

C-c p c

Runs a standard compilation command for your type of project.

C-c p p

Runs a standard test command for your type of project.

C-c p z

Adds the currently visited to the cache.

C-c p s

Display a list of known projects you can switch to.

multi-occur

ack

on all project buffers currently open.

file.

TAGS

dired .

on the project. Requires the presence of

ack-and-a-half .

Prelude adds some extra keybindings:

Keybinding

Command

Super-f

Find file in project

Super-d

Find directory in project

Super-g

Run grep on project

Super-p

Switch projects

If you ever forget any of Projectile's keybindings just do a:

C-c p C-h

Key-chords
Key-chords are available only when the
Keybinding

prelude-key-chord

module has been enabled.

Description

jj

Jump to the beginning of a word(

jk

Jump to a character(

jl

Jump to the beginning of a line(

JJ

Jump back to previous buffer(

uu

View edits as a tree(

xx

Executed extended command(

yy

Browse the kill ring(

ace-jump-word-mode )

ace-jump-char-mode )
ace-jump-line-mode )

prelude-switch-to-previous-buffer )

undo-tree-visualize )
execute-extended-command )

browse-kill-ring )

Disabling key-chords

https://github.com/bbatsov/prelude

7/11

6/28/2014

bbatsov/prelude

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
clojure-mode , cider

.clj

file

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 24 ships with a new theming facility that effectively renders the old color-theme package obsolete.
Emacs 24 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 like:

(load-theme 'solarized-dark t)

P.S. Solarized is not available by default - you'll have to install it from MELPA first (

M-x package-install RET

solarized-theme ).

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

Prelude, except a few variables like

https://github.com/bbatsov/prelude

directory. Note that at this point you can't using anything from

prelude-dir ,

etc (since nothing is yet loaded).

8/11

6/28/2014

bbatsov/prelude

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
You can install

aspell

aspell

and the dictionary on OS X with

program and an

homebrew

en

dictionary on your system.

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
contents

M-x package-refresh-

and restart Emacs afterwards.

No arrow navigation in editor buffers

https://github.com/bbatsov/prelude

9/11

6/28/2014

bbatsov/prelude

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). That's why I've disabled all movement
commands with arrows (and keys like page up, page down, etc) - to prevent you from being tempted to use
them.
If you'd like to be able to use the arrow keys (but still be reminded of the alternatives) put this in your personal
config:
(setq guru-warn-only t)

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:
(global-set-key [remap move-beginning-of-line]
'move-beginning-of-line)

Poor ido matching performance on large datasets

Prelude swaps the default

ido

The sorting algorithm

uses is more complex, but yields better results.

flx

flex matching with the more powerful ido-flx.

On slower machines, it may be necessary to lower

flx-ido-threshhold

to ensure a smooth experience.

(setq flx-ido-threshhold 1000)

You can always disable the improved sorting algorithm all together like this:
(flx-ido-mode -1)

Windows compatibility
While everything in Prelude should work fine in Windows, I test it only with Linux & OSX, so there are Windows
related problems from time to time. This situation will probably improve over time.

Known issues
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
Support is available via the Prelude Google Group emacs-prelude@googlegroups.com.
There's also a Freenode channel you can visit -

#prelude-emacs .

Contributors
Here's a list of all the people who have contributed to the development of Emacs Prelude.

Bugs & Improvements

https://github.com/bbatsov/prelude

10/11

6/28/2014

bbatsov/prelude

Bug reports and suggestions for improvements are always welcome. GitHub pull requests are even better! :-)
I'm also accepting financial contributions via gittip.

Cheers,
Bozhidar

2014 GitHub, Inc.

Terms

Privacy

https://github.com/bbatsov/prelude

Security

Contact

Status

API

Training

Shop

Blog

About

11/11