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](#fast-forward) - [Installing Emacs 24](#installing-emacs-24) - [Installation](#installation) - [Automated](#automated) - [Via Curl](#via-curl) - [Via Wget](#via-wget) - [Manual](#manual) - [Updating Prelude](#updating-prelude) - [Manual update](#manual-update) - [Update all bundled packages](#update-all-bundled-packages) - [Update Prelude's code](#update-preludes-code) - [Restart Prelude](#restart-prelude) - [Automatic update](#automatic-update) - [Enabling additional modules](#enabling-additional-modules) - [Running](#running) - [Getting to know Prelude](#getting-to-know-prelude) - [Keymap](#keymap) - [Global](#global) - [Prelude Mode](#prelude-mode) - [OSX modifier keys](#osx-modifier-keys) - [Projectile](#projectile) - [Key-chords](#key-chords) - [Disabling key-chords](#disabling-key-chords) - [Automatic package installation](#automatic-package-installation) - [Color Themes](#color-themes) - [Personalizing](#personalizing) - [Disabling whitespace-mode](#disabling-whitespace-mode) - [Disable flyspell-mode](#disable-flyspell-mode) - [Caveats & Pitfalls](#caveats--pitfalls) - [Updating bundled packages](#updating-bundled-packages) - [Problems with flyspell-mode](#problems-with-flyspell-mode) - [Ugly colors in the terminal Emacs version](#ugly-colors-in-the-terminal-emacs-version) - [MELPA error on initial startup](#melpa-error-on-initial-startup) - [No arrow navigation in editor buffers](#no-arrow-navigation-in-editor-buffers) - [Customized C-a behavior](#customized-c-a-behavior) - [Poor ido matching performance on large datasets](#poor-ido-matching-performance-on-large-datasets) - [Windows compatibility](#windows-compatibility) - [Share the knowledge](#share-the-knowledge) - [Known issues](#known-issues) - [Support](#support) - [Contributors](#contributors) - [Bugs & Improvements](#bugs--improvements) ## 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: ```bash 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: ```bash 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: ```bash 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. ## 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](http://wikemacs.org/wiki/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: ```bash curl -L https://github.com/bbatsov/prelude/raw/master/utils/installer.sh | sh ``` #### Via Wget If you're using `wget` type: ```bash wget --no-check-certificate https://github.com/bbatsov/prelude/raw/master/utils/installer.sh -O - | sh ``` ### Manual ```bash 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. ## 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 ```bash 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](modules/doc/README.md). ```lisp ;;; 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-haskell) (require 'prelude-js) ;; (require 'prelude-latex) (require 'prelude-lisp) ;; (require 'prelude-markdown) ;; (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 C-x C-e. ## Running Nothing fancy here. Just start Emacs as usual. Personally I run Emacs in daemon mode: ```bash emacs --daemon ``` Afterwards I connect to the server with either a terminal or a GUI client like this: ```bash emacsclient -t emacsclient -c ``` You'd probably do well to put a few aliases in your `.zshrc` (or `.bashrc`): ```bash 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 | Description -------------------|------------------------------------------------------------ C-M-h | Kill the previous word(`backward-kill-word`). (as in Bash/Zsh) 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(`prelude-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`. C-h A | Run `apropos` (search in all Emacs symbols). M-/ | Run `hippie-expand` (a replacement for the default `dabbrev-expand`). C-x C-b | Open `ibuffer` (a replacement for the default `buffer-list`). F11 | Make the window full screen. F12 | Toggle the Emacs menu bar. C-x g | Open Magit's status buffer. C-= | Run `expand-region` (incremental text selection). C-a | Run `prelude-move-beginning-of-line`. Read [this](http://emacsredux.com/blog/2013/05/22/smarter-navigation-to-the-beginning-of-a-line/) 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-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-S-down| 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 | Duplicate the current line (or region). C-c M-d | Duplicate and comment the current line (or region). C-c r | Rename the currently visited file and buffer. C-c t | Open a terminal emulator (`ansi-term`). C-c k | Kill all open buffers except the one you're currently in. C-c h | Open Helm (available if you've enabled the `prelude-helm` module). C-c + | Increment integer at point. C-c - | Decrement integer at point. 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 #### 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: ```lisp (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](https://github.com/bbatsov/projectile): Keybinding | Description -------------------|------------------------------------------------------------ C-c p f | Display a list of all files in the project. With a prefix argument it will clear the cache first. C-c p d | 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 `multi-occur` on all project buffers currently open. 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 `TAGS` file. C-c p k | Kills all project buffers. C-c p D | Opens the root of the project in `dired`. C-c p e | Shows a list of recently visited project files. C-c p a | Runs `ack` on the project. Requires the presence of `ack-and-a-half`. 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. 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 `prelude-key-chord` module has been enabled.** Keybinding | Description -------------------|---------------------------------------------- jj | Jump to the beginning of a word(`ace-jump-word-mode`) jk | Jump to a character(`ace-jump-char-mode`) jl | Jump to the beginning of a line(`ace-jump-line-mode`) JJ | Jump back to previous buffer(`prelude-switch-to-previous-buffer`) uu | View edits as a tree(`undo-tree-visualize`) ##### 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: ```lisp (key-chord-define-global "jj" nil) ``` If you're an `evil-mode` user you'll probably do well to disable `key-chord-mode` altogether: ```lisp (key-chord-mode -1) ``` ## 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 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](https://github.com/bbatsov/zenburn-emacs) 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: ```lisp (disable-theme 'zenburn) ``` Or you can use another theme altogether by adding something like: ```lisp (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: ```lisp (prelude-require-packages '(some-package some-other-package)) ``` If you require just a single package you can also use: ```lisp (prelude-require-package 'some-package) ``` #### 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: ```lisp (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: ```lisp (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: ```lisp (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: ```bash 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`: ```bash 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: ```lisp (setq prelude-guru nil) ``` ### Customized C-a behavior Prelude overrides `C-a` to behave as described [here](http://emacsredux.com/blog/2013/05/22/smarter-navigation-to-the-beginning-of-a-line/). If you don't like that simply add this to your personal config: ```lisp (global-set-key [remap move-beginning-of-line] 'move-beginning-of-line) ``` ### Poor ido matching performance on large datasets Prelude swaps the default `ido` flex matching with the more powerful [ido-flx](https://github.com/lewang/flx). The sorting algorithm `flx` uses is more complex, but yields better results. On slower machines, it may be necessary to lower `flx-ido-threshhold` to ensure a smooth experience. ```lisp (setq flx-ido-threshhold 1000) ``` You can always disable the improved sorting algorithm all together like this: ```lisp (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. ## Share the knowledge [EmacsWiki](http://emacswiki.org) 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 ## Known issues Check out the project's [issue list](https://github.com/bbatsov/prelude/issues?sort=created&direction=desc&state=open) 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 . ## Contributors Here's a [list](https://github.com/bbatsov/prelude/contributors) 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](https://twitter.com/bbatsov)