personal | ||
prelude | ||
snippets | ||
themes | ||
utils | ||
.gitignore | ||
init.el | ||
README.md |
Emacs Prelude
Emacs is probably the best text editor in the world. However, the process of coming up with a useful Emacs configuration is long and difficult. It's this process that separates you from truly taking advantage of Emacs's power. I like to refer to this process as the Prelude. Emacs Prelude has the goal to ease the initial Emacs setup process and to provide you with a much more powerful and productive experience than the one you get out of the box. By using Emacs Prelude you're basically getting a "Get me out of the Prelude, I just want to use Emacs" card.
Emacs Prelude is compatible ONLY with GNU Emacs 24.x.
Fast Forward
Assuming you're using an Unix-like OS (*BSD
, GNU/Linux
, OS X
, Solaris
,
etc), you already have Emacs 24 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://github.com/bbatsov/prelude/raw/master/utils/installer.sh | 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:
$ PRELUDE_INSTALL_DIR="$HOME/.emacs.d" && curl -L https://github.com/bbatsov/prelude/raw/master/utils/installer.sh | sh
To change the source repository:
$ 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.
More goodies
The Prelude Modules
project contains a lot of additional packages for Prelude
(install-able via the package-list-packages
command) - enhanced programming
mode configs, latex config, erc config, etc.
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.
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 - | sh
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 ~/.emacs.d
with the value of
user-emacs-directory
for your OS. You can check the value by doing
C-h v user-emacs-directory
inside Emacs.
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.
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
, nrepl.el
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.
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.
Disable whitespace-mode
Some people find whitespace-mode
too intrusive and might want to
disable it. It come be done from your personal config with the
following bit of code:
(add-hook 'prog-mode-hook 'prelude-turn-off-whitespace t)
Disable flyspell-mode
If you're not fond of spellchecking on the fly:
(add-hook 'text-mode-hook 'turn-off-flyspell t)
(add-hook 'prog-mode-hook 'turn-off-flyspell t)
Prelude Modules
Additional settings for various programming languages are available for installation via MELPA. You might take a look at the Prelude Modules project for further info.
Caveats & Pitfalls
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 --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.
No 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). 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 still like to use the arrow keys just invoke M-x guru-mode
to enable them for the duration of your
current Emacs session or add the following snippet to your
personal Emacs customization to enable them permanently:
(add-hook 'prog-mode-hook 'turn-off-guru-mode t)
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.
Share the knowledge
WikEmacs collects useful resources for working with GNU Emacs. Please, take the time to peruse and improve them as you accumulate knowledge about Emacs. Prelude makes this especially easy, since it bundles MediaWiki support + the settings required to access WikEmacs right away.
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. :-)
Contributors
Here's a list of all the people who have contributed to the development of Emacs Prelude.
Bugs & Improvements
Bug reports and suggestions for improvements are always welcome. GitHub pull requests are even better! :-)
Cheers,
Bozhidar