[![License GPL 3][badge-license]](http://www.gnu.org/licenses/gpl-3.0.txt)
[![Build Status](https://travis-ci.org/clojure-emacs/cider.png?branch=master)](https://travis-ci.org/clojure-emacs/cider)
[![Gittip](http://img.shields.io/gittip/bbatsov.svg)](https://www.gittip.com/bbatsov/)
[![Paypal](https://www.paypalobjects.com/en_US/i/btn/btn_donate_SM.gif)](https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=GRQKNBM6P8VRQ)
`CIDER` (formerly `nrepl.el`) is the Clojure IDE and REPL for Emacs, built on top of
[nREPL](https://github.com/clojure/tools.nrepl), the Clojure networked
REPL server. It's a great alternative to the now deprecated combination
of SLIME + [swank-clojure](https://github.com/technomancy/swank-clojure).
***
- [Installation](#installation)
- [Prerequisites](#prerequisites)
- [Via package.el](#via-packageel)
- [Via el-get](#via-el-get)
- [Manual](#manual)
- [Emacs Prelude](#emacs-prelude)
- [Emacs Live](#emacs-live)
- [Configuration](#configuration)
- [Basic Usage](#basic-usage)
- [Setting up a Leiningen project (optional)](#setting-up-a-leiningen-project-optional)
- [Launch a nREPL server and client from Emacs](#launch-a-nrepl-server-and-client-from-emacs)
- [Connect to a running nREPL server](#connect-to-a-running-nrepl-server)
- [Using the cider minor mode](#using-the-cider-minor-mode)
- [Pretty printing in the REPL](#pretty-printing-in-the-repl)
- [Limiting printed output in the REPL](#limiting-printed-output-in-the-repl)
- [Keyboard shortcuts](#keyboard-shortcuts)
- [cider-mode](#cider-mode)
- [cider-repl-mode](#cider-repl-mode)
- [cider-macroexpansion-mode](#cider-macroexpansion-mode)
- [cider-inspector-mode](#cider-inspector-mode)
- [Managing multiple sessions](#managing-multiple-sessions)
- [Requirements](#requirements)
- [Caveats](#caveats)
- [Documentation](#documentation)
- [Changelog](#changelog)
- [Team](#team)
- [Contributing](#contributing)
- [License](#license)
## Installation
### Prerequisites
You'll need to have Emacs installed (preferably the latest stable
release). If you're new to Emacs you might want to read
[this tutorial](http://clojure-doc.org/articles/tutorials/emacs.html),
dedicated to setting up Emacs for Clojure development, first.
#### Upgrading from nrepl.el
Before installing CIDER make sure you've removed the old `nrepl.el`
package and all packages that depend on it. Use only packages updated to work with CIDER!
You'll also need to adjust your config accordingly, as most settings
were renamed in CIDER. Consult the [Configuration](#configuration) section of the
README for more details.
#### Upgrading from clojure-test-mode
CIDER 0.7 ships a replacement for the deprecated `clojure-test-mode` called `cider-test`.
Please, make sure you've uninstalled `clojure-test-mode` if you're using CIDER 0.7 as `clojure-test-mode`
sometimes interferes with CIDER's REPL initialization.
### Via package.el
`package.el` is the built-in package manager in Emacs.
`CIDER` is available on two major `package.el` community
maintained repos -
[MELPA Stable](http://melpa-stable.milkbox.net) and
[MELPA](http://melpa.milkbox.net).
You can install `CIDER` with the following command:
M-x package-install [RET] cider [RET]
or by adding this bit of Emacs Lisp code to your Emacs initialization file(`.emacs` or `init.el`):
```el
(unless (package-installed-p 'cider)
(package-install 'cider))
```
If the installation doesn't work try refreshing the package list:
M-x package-refresh-contents [RET]
Keep in mind that MELPA packages are built automatically from
the `master` branch, meaning bugs might creep in there from time to
time. Never-the-less, installing from MELPA is the recommended way of
obtaining CIDER, as the `master` branch is normally quite stable and
"stable" (tagged) builds are released somewhat infrequently.
### Via el-get
[el-get](https://github.com/dimitri/el-get) is another popular package manager for Emacs.
If you're an el-get user just do M-x el-get-install.
### Manual
You can install `CIDER` manually by placing `CIDER` on your `load-path`
and `require`ing it. Many people favour the folder `~/.emacs.d/vendor`:
```el
(add-to-list 'load-path "~/emacs.d/vendor")
(require 'cider)
```
Keep in mind that `CIDER` depends on `clojure-mode`, `dash.el` and
`pkg-info` so you'll have to install them as well.
### Emacs Prelude
`CIDER` comes bundled in
[Emacs Prelude](https://github.com/bbatsov/prelude). If you're a
Prelude user you can start using it right away.
### Emacs Live
`CIDER` comes bundled in
[Emacs Live](https://github.com/overtone/emacs-live). If you're using
Emacs Live you're already good to go.
## CIDER nREPL middleware
### Using Leiningen
Much of CIDER's functionality depends on the presence of CIDER's own
[nREPL middleware](https://github.com/clojure-emacs/cider-nrepl).
Use the convenient plugin for defaults, either in your project's
`project.clj` file or in the :user profile in `~/.lein/profiles.clj`.
```clojure
:plugins [[cider/cider-nrepl "x.y.z"]]
```
A minimal `profiles.clj` for CIDER would be:
```clojure
{:user {:plugins [[cider/cider-nrepl "0.7.0"]]}}
```
### Using embedded nREPL server
If you're embedding nREPL in your application you'll have to start the
server with CIDER's own nREPL handler.
```clojure
(ns my-app
(:require [clojure.tools.nrepl.server :as nrepl-server]
[cider.nrepl :refer (cider-nrepl-handler)]))
(defn -main
[]
(nrepl-server/start-server :port 7888 :handler cider-nrepl-handler))
```
It goes without saying that your project should depend on `cider-nrepl`.
***
`x.y.z` should match the version of CIDER you're currently using (say `0.7.1`).
For snapshot releases of CIDER you should use the snapshot of the plugin as well
(say `0.7.1-SNAPSHOT`).
**Note that you need to use at least CIDER 0.7 for the nREPL middleware to work
properly. Don't use cider-nrepl with CIDER 0.6.**
## Configuration
You can certainly use `CIDER` without configuring it any further,
but here are some ways other folks are adjusting their `CIDER`
experience.
### Basic configuration
* Enable `eldoc` in Clojure buffers:
```el
(add-hook 'cider-mode-hook 'cider-turn-on-eldoc-mode)
```
* You can hide the `*nrepl-connection*` and `*nrepl-server*` buffers
from appearing in some buffer switching commands like
`switch-to-buffer`(C-x b) like this:
```el
(setq nrepl-hide-special-buffers t)
```
When using `switch-to-buffer`, pressing SPC after the command will
make the hidden buffers visible. They'll always be visible in
`list-buffers` (C-x C-b).
* You can control the TAB key behavior in the REPL via the
`cider-repl-tab-command` variable. While the default command
`cider-repl-indent-and-complete-symbol` should be an adequate choice for
most users, it's very easy to switch to another command if you wish
to. For instance if you'd like TAB to only indent (maybe
because you're used to completing with M-TAB) use the
following snippet:
```el
(setq cider-repl-tab-command 'indent-for-tab-command)
```
* To prefer local resources to remote (tramp) ones when both are available:
```el
(setq cider-prefer-local-resources t)
```
* Prevent the auto-display of the REPL buffer in a separate window
after connection is established:
```el
(setq cider-repl-pop-to-buffer-on-connect nil)
```
* Configure whether the error buffer with stacktraces should be automatically
shown on error:
- Don't show on error:
```el
(setq cider-show-error-buffer nil)
```
Independently of the value of `cider-show-error-buffer`, the error buffer is
always generated in the background. Use `cider-visit-error-buffer` to visit
this buffer.
- Selective strategies:
```el
(setq cider-show-error-buffer 'except-in-repl) ; or
(setq cider-show-error-buffer 'only-in-repl)
```
* To disable auto-selection of the error buffer when it's displayed:
```el
(setq cider-auto-select-error-buffer nil)
```
* If using the `wrap-stacktrace` middleware from `cider-nrepl`, error buffer
stacktraces may be filtered by default. Valid filter types include `java`,
`clj`, `repl`, `tooling`, and `dup`. Setting this to `nil` will show all
stacktrace frames.
```el
(setq cider-stacktrace-default-filters '(tooling dup))
```
* Error messages may be wrapped for readability. If this value is nil, messages
will not be wrapped; if it is truthy but non-numeric, the default `fill-column`
will be used.
```el
(setq cider-stacktrace-fill-column 80)
```
* The REPL buffer name has the format `*cider-repl project-name*`.
Change the separator from space to something else by overriding `nrepl-buffer-name-separator`.
```el
(setq nrepl-buffer-name-separator "-")
```
* The REPL buffer name can also display the port on which the nREPL server is running.
Buffer name will look like *cider-repl project-name:port*.
```el
(setq nrepl-buffer-name-show-port t)
```
* Make C-c C-z switch to the CIDER REPL buffer in the current window:
```el
(setq cider-repl-display-in-current-window t)
```
* Prevent C-c C-k from prompting to save the file corresponding to
the buffer being loaded, if it's modified:
```el
(setq cider-prompt-save-file-on-load nil)
```
* Change the result prefix for REPL evaluation (by default there's no prefix):
```el
(setq cider-repl-result-prefix ";; => ")
```
And here's the result of that change:
```
user> (+ 1 2)
;; => 3
```
* Change the result prefix for interactive evaluation (by default it's `=> `):
```el
(setq cider-interactive-eval-result-prefix ";; => ")
```
To remove the prefix altogether just set it to an empty string(`""`).
* Normally code you input in the REPL is font-locked with
`cider-repl-input-face` (after you press `RET`) and results are
font-locked with `cider-repl-result-face`. If you want them to be
font-locked as in `clojure-mode` use the following:
```el
(setq cider-repl-use-clojure-font-lock t)
```
* You can control the C-c C-z key behavior of switching to the REPL buffer
with the `cider-switch-to-repl-command` variable. While the default command
`cider-switch-to-relevant-repl-buffer` should be an adequate choice for
most users, `cider-switch-to-current-repl-buffer` offers a simpler alternative
where CIDER will not attempt to match the correct REPL buffer based on
underlying project directories:
```el
(setq cider-switch-to-repl-command 'cider-switch-to-current-repl-buffer)
```
* You can configure known endpoints used by the cider command offered via a
completing read. This is useful if you have a list of common host/ports you
want to establish remote nREPL connections to. Using an optional label is
helpful for identifying each host.
```el
(setq cider-known-endpoints '(("host-a" "10.10.10.1" "7888") ("host-b" "7888")))
```
### REPL History
* To make the REPL history wrap around when its end is reached:
```el
(setq cider-repl-wrap-history t)
```
* To adjust the maximum number of items kept in the REPL history:
```el
(setq cider-repl-history-size 1000) ; the default is 500
```
* To store the REPL history in a file:
```el
(setq cider-repl-history-file "path/to/file")
```
Note that the history is written to the file when you kill the REPL
buffer (which includes invoking `cider-quit`) or you quit Emacs.
### Minibuffer completion
Out-of-the box `CIDER` uses the standard `completing-read` Emacs mechanism. While it's not
fancy it certainly gets the job done (just press `TAB`). There are, however, ways to improve
upon the standard completion if you wish to.
#### icomplete
`icomplete` is bundled with Emacs and enhances the default minubuffer completion:
```el
(require 'icomplete)
```
#### ido
`ido` is also bundled with Emacs and offers more features than `icomplete`.
If you are using `ido`, be sure to use both `ido-everywhere`
and [`ido-ubiquitous`](https://github.com/DarwinAwardWinner/ido-ubiquitous).
You might also want to install [`ido-flex`](https://github.com/lewang/flx).
### Integration with other modes
* Enabling `CamelCase` support for editing commands(like
`forward-word`, `backward-word`, etc) in the REPL is quite useful since
we often have to deal with Java class and method names. The built-in
Emacs minor mode `subword-mode` provides such functionality:
```el
(add-hook 'cider-repl-mode-hook 'subword-mode)
```
* The use of [paredit](http://mumble.net/~campbell/emacs/paredit.html)
when editing Clojure (or any other Lisp) code is highly
recommended. You're probably using it already in your `clojure-mode`
buffers (if you're not you probably should). You might also want to
enable `paredit` in the REPL buffer as well:
```el
(add-hook 'cider-repl-mode-hook 'paredit-mode)
```
* [smartparens](https://github.com/Fuco1/smartparens) is an excellent
alternative to paredit. Many Clojure hackers have adopted it
recently and you might want to give it a try as well. To enable
`smartparens` in the REPL buffer use the following code:
```el
(add-hook 'cider-repl-mode-hook 'smartparens-strict-mode)
```
* [RainbowDelimiters](https://github.com/jlr/rainbow-delimiters) is a
minor mode which highlights parentheses, brackets, and braces
according to their depth. Each successive level is highlighted in a
different color. This makes it easy to spot matching delimiters,
orient yourself in the code, and tell which statements are at a
given depth. Assuming you've already installed RainbowDelimiters you can
enable it in the REPL like this:
```el
(add-hook 'cider-repl-mode-hook 'rainbow-delimiters-mode)
```
* [company-mode](http://company-mode.github.io/) provides in-buffer completion
framework. When `company-mode` is enabled, it will retrieve completion
information from `cider-complete-at-point`, requiring no additional setup (and
no `company-mode` plugins). `CIDER` users are advised to use `company-mode`
instead of `auto-complete-mode` for optimal results.
* [ac-cider](https://github.com/clojure-emacs/ac-cider) provides
completion source for the popular Emacs interactive auto-completion
framework [auto-complete](http://cx4a.org/software/auto-complete/).
Where CIDER provides it, pop-up documentation for completed symbols
will be displayed.
## Basic Usage
The only requirement to use CIDER is to have a nREPL server to
which it may connect. Many Clojurians favour the use of the Leiningen tool
to start a nREPL server, but the use of Leiningen is not a prerequisite to use
CIDER (but it's required if you want to use the `cider-jack-in` command).
### Setting up a Leiningen project (optional)
[Leiningen](http://leiningen.org/) is the de facto standard
build/project management tool for Clojure. It has a similar scope to
the Maven build tool favoured by Java developers (Leiningen actually
reuses many things from the Maven ecosystem).
CIDER features a command called `cider-jack-in` that will start an nREPL server
for a particular Leiningen project and connect to it automatically.
This functionality depends on Leiningen 2. Older versions are not supported. Follow
the installation instructions on Leiningen's web site to get it up and running and afterwards
create a project like this:
```
$ lein new demo
```
The two main ways to obtain an nREPL connection are discussed in the following sections of the manual.
### Launch a nREPL server and client from Emacs
Simply open in Emacs a file belonging to your `lein` project (like
`foo.clj`) and type M-x cider-jack-in. This will start a nREPL with
all the deps loaded in, plus an `CIDER` client connected to it.
Alternative you can use C-u M-x cider-jack-in to specify the name of
a lein project, without having to visit any file in it.
### Connect to a running nREPL server
You can go to your project's dir in a terminal and type there
(assuming you're using Leiningen that is):
```
$ lein repl
```
Alternatively you can start nREPL either manually or by the facilities provided by your
project build tool (Maven, etc).
After you get your nREPL server running go back to Emacs.
Typing there M-x cider-connect will allow you to connect to the running nREPL server.
### Using the cider minor mode
`CIDER` comes with a handy minor mode called `cider-mode` (complementing
`clojure-mode`) that allows you to evaluate code in your Clojure source
files and load it directly in the REPL. A list of all
available commands is available in the `CIDER` menu and in the following
section of this manual.
### Pretty printing in the REPL
Make the REPL always pretty-print the results of your commands. Note
that this will not work correctly with forms such as `(def a 1) (def b2)`
and it expects `clojure.pprint` to have been required already
(the default in more recent versions of Clojure):
M-x cider-repl-toggle-pretty-printing
### Limiting printed output in the REPL
Accidentally printing large objects can be detrimental to your
productivity. Clojure provides the `*print-length*` var which, if set,
controls how many items of each collection the printer will print. You
can supply a default value for REPL sessions via the `global-vars`
section of your Leiningen project's configuration.
```clojure
:global-vars {*print-length* 100}
```
## Keyboard shortcuts
* M-x cider-jack-in: Launch an nREPL server and a REPL client.
Prompts for a project root if given a prefix argument.
* M-x cider: Connect to an already-running nREPL server.
While you're in `clojure-mode`, `cider-jack-in` is bound for
convenience to C-c M-j and `cider-connect` is bound to C-c
M-c.
### cider-mode
Keyboard shortcut | Description
-------------------------------------|-------------------------------
C-x C-e C-c C-e| Evaluate the form preceding point and display the result in the echo area. If invoked with a prefix argument, insert the result into the current buffer.
C-c C-w | Evaluate the form preceding point and replace it with its result.
C-c M-e | Evaluate the form preceding point and output it result to the REPL buffer. If invoked with a prefix argument, takes you to the REPL buffer after being invoked.
C-c M-p | Load the form preceding point in the REPL buffer.
C-c C-p | Evaluate the form preceding point and pretty-print the result in a popup buffer.
C-c C-f | Evaluate the top level form under point and pretty-print the result in a popup buffer.
C-M-x C-c C-c | Evaluate the top level form under point and display the result in the echo area. If invoked with a prefix argument, insert the result into the current buffer.
C-c C-r | Evaluate the region and display the result in the echo area.
C-c C-b | Interrupt any pending evaluations.
C-c C-m | Invoke `macroexpand-1` on the form at point and display the result in a macroexpansion buffer. If invoked with a prefix argument, `macroexpand` is used instead of `macroexpand-1`.
C-c M-m | Invoke `clojure.walk/macroexpand-all` on the form at point and display the result in a macroexpansion buffer.
C-c C-n | Eval the ns form.
C-c M-n | Switch the namespace of the REPL buffer to the namespace of the current buffer.
C-c C-z | Switch to the relevant REPL buffer. Use a prefix argument to change the namespace of the REPL buffer to match the currently visited source file.
C-u C-u C-c C-z | Switch to the REPL buffer based on a user prompt for a directory.
C-c M-d | Display default REPL connection details, including project directory name, buffer namespace, host and port.
C-c M-r | Rotate and display the default nREPL connection.
C-c M-o | Clear the entire REPL buffer, leaving only a prompt. Useful if you're running the REPL buffer in a side by side buffer.
C-c C-k | Load the current buffer.
C-c C-l | Load a file.
C-c C-d d | Display doc string for the symbol at point. If invoked with a prefix argument, or no symbol is found at point, prompt for a symbol.
C-c C-d j | Display JavaDoc (in your default browser) for the symbol at point. If invoked with a prefix argument, or no symbol is found at point, prompt for a symbol.
C-c M-i | Inspect expression. Will act on expression at point if present.
C-c M-t | Toggle var tracing.
C-c C-u | Undefine a symbol. If invoked with a prefix argument, or no symbol is found at point, prompt for a symbol.
C-c , | Run tests for namespace.
C-c C-, | Re-run test failures/errors for namespace.
C-c M-, | Run test at point.
C-c C-t | Show the test report buffer.
M-. | Jump to the definition of a symbol. If invoked with a prefix argument, or no symbol is found at point, prompt for a symbol.
C-c M-. | Jump to the resource referenced by the string at point.
M-, | Return to your pre-jump location.
M-TAB | Complete the symbol at point.
C-c C-d g | Lookup symbol in Grimoire.
C-c C-d a | Apropos search for functions/vars.
C-c C-d A | Apropos search for documentation.
### cider-repl-mode
Keyboard shortcut | Description
-------------------------------------|------------------------------
RET | Evaluate the current input in Clojure if it is complete. If incomplete, open a new line and indent. If invoked with a prefix argument is given then the input is evaluated without checking for completeness.
C-RET | Close any unmatched parenthesis and then evaluate the current input in Clojure.
C-j | Open a new line and indent.
C-c M-o | Clear the entire REPL buffer, leaving only a prompt.
C-c C-o | Remove the output of the previous evaluation from the REPL buffer.
C-c C-u | Kill all text from the prompt to the current point.
C-c C-b C-c C-c| Interrupt any pending evaluations.
C-up C-down | Goto to previous/next input in history.
M-p M-n | Search the previous/next item in history using the current input as search pattern. If M-p/M-n is typed two times in a row, the second invocation uses the same search pattern (even if the current input has changed).
M-s M-r | Search forward/reverse through command history with regex.
C-c C-n C-c C-p | Move between the current and previous prompts in the REPL buffer. Pressing RET on a line with old input copies that line to the newest prompt.
TAB | Complete symbol at point.
C-c C-d d | Display doc string for the symbol at point. If invoked with a prefix argument, or no symbol is found at point, prompt for a symbol
C-c C-d j | Display JavaDoc (in your default browser) for the symbol at point. If invoked with a prefix argument, or no symbol is found at point, prompt for a symbol.
C-c C-d g | Lookup symbol in Grimoire.
C-c C-d a | Apropos search for functions/vars.
C-c C-d A | Apropos search for documentation.
C-c C-z | Switch to the previous Clojure buffer. This complements C-c C-z used in cider-mode.
C-c M-f | Select a function from the current namespace and insert into the REPL buffer.
C-c M-i | Inspect expression. Will act on expression at point if present.
C-c M-n | Select a namespace and switch to it.
C-c M-t | Toggle var tracing.
In the REPL you can also use "shortcut commands" by pressing `,` at the beginning of a REPL line. You'll be presented with a list of commands you can quickly run (like quitting, displaying some info, clearing the REPL, etc). The character used to trigger the shortcuts is configurable via `cider-repl-shortcut-dispatch-char`. Here's how you can change it to `:`:
```el
(setq cider-repl-shortcut-dispatch-char ?\:)
```
### cider-macroexpansion-mode
Keyboard shortcut | Description
--------------------------------|-------------------------------
C-c C-m | Invoke `macroexpand-1` on the form at point and replace the original form with its expansion. If invoked with a prefix argument, `macroexpand` is used instead of `macroexpand-1`.
C-c M-m | Invoke `clojure.walk/macroexpand-all` on the form at point and replace the original form with its expansion.
g | The prior macroexpansion is performed again and the current contents of the macroexpansion buffer are replaced with the new expansion.
C-/ C-x u | Undo the last inplace expansion performed in the macroexpansion buffer.
### cider-inspector-mode
Keyboard shortcut | Description
--------------------------------|-------------------------------
Tab and Shift-Tab | navigate inspectable sub-objects
Return | inspect sub-objects
l | pop to the parent object
g | refresh the inspector (e.g. if viewing an atom/ref/agent)
### cider-test-report-mode
Keyboard shortcut | Description
--------------------------------|-------------------------------
C-c , | Run tests for namespace.
C-c C-, | Re-run test failures/errors for namespace.
C-c M-, | Run test at point.
M-p | Move point to previous test.
M-n | Move point to next test.
t and M-. | Jump to test definition.
d | Display diff of actual vs expected.
e | Display test error cause and stacktrace info.
### cider-stacktrace-mode
Keyboard shortcut | Description
--------------------------------|-------------------------------
M-p | move point to previous cause
M-n | move point to next cause
M-. and Return | navigate to the source location (if available) for the stacktrace frame
Tab | Cycle current cause detail
0 and S-Tab | Cycle all cause detail
1 | Cycle cause #1 detail
2 | Cycle cause #2 detail
3 | Cycle cause #3 detail
4 | Cycle cause #4 detail
5 | Cycle cause #5 detail
j | toggle display of java frames
c | toggle display of clj frames
r | toggle display of repl frames
t | toggle display of tooling frames (e.g. compiler, nREPL middleware)
d | toggle display of duplicate frames
a | toggle display of all frames
### Managing multiple sessions
You can connect to multiple nREPL servers using M-x
cider-jack-in multiple times. To close the current nREPL
connection, use M-x nrepl-close. M-x cider-quit
closes all connections.
CIDER maintains a list of nREPL connections and a single 'default'
connection. When you execute CIDER commands in a Clojure editing
buffer such as to compile a namespace, these commands are executed
against the default connection.
You can display the default nREPL connection using C-c M-d
and rotate the default connection using C-c M-r. Another
option for setting the default connection is to execute the command
M-x nrepl-make-repl-connection-default in the appropriate
REPL buffer.
To switch to the relevant REPL buffer based on the Clojure namespace
in the current Clojure buffer, use: C-c C-z. You can then
use the same key combination to switch back to the Clojure buffer you
came from.
The single prefix C-u C-c C-z, will switch you to the
relevant REPL buffer and set the namespace in that buffer based on
namespace in the current Clojure buffer.
To explicitly choose the REPL buffer that C-c C-z uses
based on project directory, use a double prefix C-u C-u C-c
C-z. This assumes you have `cider-switch-to-relevant-repl`
mapped to the var `cider-switch-to-repl-command` which is the default
configuration.
To change the designation used for CIDER buffers use M-x
cider-change-buffers-designation. This changes the CIDER REPL
buffer, nREPL connection buffer and nREPL server buffer. For example
using `cider-change-buffers-designation` with the string "foo" would
change `*cider-repl localhost*` to `*cider-repl foo*`.
## Requirements
* [Leiningen](http://leiningen.org) 2.x (only for `cider-jack-in`)
* [GNU Emacs](http://www.gnu.org/software/emacs/emacs.html) 24.1+.
* [Clojure](http://clojure.org) 1.5.0+
## Caveats
### Completion
ClojureScript completion is provided by the
[cider-nrepl](https://github.com/clojure-emacs/cider-nrepl) 'complete'
implementation middleware which relies on
[piggieback](https://github.com/cemerick/piggieback). Include it in
your project middlewares and call `(cemerick.piggieback/cljs-repl)` or
another method to start up the ClojureScript REPL.
### Microsoft Windows
On Microsoft Windows the JVM default line separator string is `\r\n`
which can appear in Emacs as `^M` characters at the end of lines
printed out by the JVM. One option is to set the
`buffer-display-table` to not show these characters as detailed
[here](http://stackoverflow.com/questions/10098925/m-character-showing-in-clojure-slime-repl/11787550#11787550)
(changing `slime-repl-mode-hook` to
`cider-repl-mode-hook`). Alternatively, setting the system property
`line.separator` to `\n` at JVM startup will stop the carriage return
from being printed and will fix output in all cider buffers. To do so
add `"-Dline.separator=\"\n\""` to `:jvm-opts` in
`~/.lein/profiles.clj`.
### powershell.el
The powershell inferior shell mode truncates CIDER's REPL output when
loaded. As a workaround remove
```el
(require 'powershell)
```
from your Emacs config.
## Documentation
A single-page quick reference PDF for CIDER commands is available [here](doc/cider-refcard.pdf). This PDF can be created manually by running `pdflatex` on [the CIDER refcard LaTeX file](doc/cider-refcard.tex).
## Changelog
An extensive changelog is available [here](CHANGELOG.md).
## Team
* [Bozhidar Batsov](https://github.com/bbatsov) (maintainer)
* [Tim King](https://github.com/kingtim) (original author)
* [Phil Hagelberg](https://github.com/technomancy)
* [Hugo Duncan](https://github.com/hugoduncan)
* [Steve Purcell](https://github.com/purcell)
* [Jeff Valk](https://github.com/jeffvalk)
## Release policy
We’re following [SemVer](http://semver.org/) (as much as one can be
following it when the major version is 0). At this point bumps of the
minor (second) version number are considered major releases and always
include new features or significant changes to existing features. API
compatibility between major releases is not a (big) concern (although we try
to break the API rarely and only for a good reason).
The development cycle for the next major
release starts immediately after the previous one has been
shipped. Bugfix/point releases (if any) address only serious bugs and
never contain new features.
The versions of CIDER and `cider-nrepl` are always kept in sync. If you're tracking the
`master` branch of CIDER, you should also be tracking the `master` branch of `cider-nrepl`.
## Logo
CIDER's logo was created by [@ndr-qef](https://github.com/ndr-qef). You can find the logo in various
formats [here](https://github.com/clojure-emacs/cider/tree/master/logo).
The logo is licensed under a
[Creative Commons Attribution-NonCommercial 4.0 International License](http://creativecommons.org/licenses/by-nc/4.0/deed.en_GB).
## Contributing
### Discussion
For questions, suggestions and support refer to our [official mailing list](https://groups.google.com/forum/#!forum/cider-emacs)
or the Freenode channel `#clojure-emacs`.
Please, don't report issues there, as this makes them harder to track.
### Issues
Report issues and suggest features and improvements on the
[GitHub issue tracker](https://github.com/clojure-emacs/cider/issues). Don't ask
questions on the issue tracker - the mailing list and the IRC channel are the
places for questions.
### Patches
Patches under any form are always welcome! GitHub pull requests are even better! :-)
Before submitting a patch or a pull request make sure all tests are
passing and that your patch is in line with the [contribution
guidelines](CONTRIBUTING.md).
### Documentation
Consider improving and extending the [community wiki](https://github.com/clojure-emacs/cider/wiki).
### Donations
You can also support CIDER with financial contributions via [gittip](https://www.gittip.com/bbatsov) and PayPal.
[![Support via Gittip](https://rawgithub.com/twolfson/gittip-badge/0.2.0/dist/gittip.png)](https://www.gittip.com/bbatsov)
[![Paypal](https://www.paypalobjects.com/en_US/i/btn/btn_donate_SM.gif)](https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=GRQKNBM6P8VRQ)
### Running the tests in batch mode
Install [cask](https://github.com/rejeep/cask.el) if you haven't
already, then:
```
$ cd /path/to/cider
$ cask
```
Run all tests with:
```
$ make test
```
## License
Copyright © 2012-2014 Tim King, Phil Hagelberg, Bozhidar Batsov, Hugo
Duncan, Steve Purcell and
[contributors](https://github.com/clojure-emacs/cider/contributors).
Distributed under the GNU General Public License, version 3
[badge-license]: https://img.shields.io/badge/license-GPL_3-green.svg