= Basic Configuration
:experimental:

Like Emacs itself, almost every part of CIDER is configurable. The
CIDER developers have tried to implement some reasonable defaults that
should work for a large portion of the Clojure community, but we know
that there is nothing approaching a "one size fits all" development
environment and we've tried to create points of customization that can
account for many different peoples' preferences. In this way, you
should be able to make CIDER as comfortable as possible for *you*.

This section doesn't describe every possible customization that CIDER
offers, but here are some of the most popular.

TIP: You can see every single customizable configuration option with the command
kbd:[M-x customize-group RET cider].

== Disable Automatic cider-mode in clojure-mode Buffers

By default, CIDER enables `cider-mode` in all `clojure-mode` buffers
after it establishes the first CIDER connection. It will also add a
`clojure-mode` hook to enable `cider-mode` on newly-created `clojure-mode`
buffers. You can override this behavior, however:

[source,lisp]
----
(setq cider-auto-mode nil)
----

== Prompt for Symbol Confirmation

NOTE: The default here was changed in CIDER 1.0.

By default, CIDER won't prompt you for a symbol when it executes
interactive commands that require a symbol (e.g. `cider-doc`). Such
commands operate on the symbol at point and prompt you to provide
a symbol if they can't obtain one automatically.

If you set
`cider-prompt-for-symbol` to `t`, this behavior will be inverted and
CIDER will always prompt you to confirm the symbol on which a command
will operate. This behavior is useful, as it allows you to edit the
inferred symbol, before some operation is carried out with it (and you get to
see what was inferred by `cider-symbol-at-point`).

[source,lisp]
----
(setq cider-prompt-for-symbol t)
----

TIP: Many interactive commands that operate on the symbol at point,
accept a prefix argument that flips the behavior configured via
`cider-prompt-for-symbol` for the current command invocation.

== Control what window to use when jumping to a definition

By default kbd:[M-.] and other commands that jump to a definition have the following behavior:

* If the definition buffer is visible simply switch to it.
* Otherwise, use the current window to show the definition.

Other behavior is possible, and is controlled with
`cider-jump-to-pop-to-buffer-actions`; the value of this is passed as the
`action` argument to `pop-to-buffer`.

The default value is `\((display-buffer-reuse-window display-buffer-same-window))`.

Some people might prefer to always display the definition in the current
window. Here's how you can achieve this:

[source,lisp]
----
(setq cider-jump-to-pop-to-buffer-actions
      '((display-buffer-same-window)))
----

WARNING: Keep in mind this might cause problems with some special buffers (e.g. test report buffers),
as when you try to navigate to a definition this will clobber the special buffer.

For other possibilities, see the documentation for `display-buffer`.

=== Example 1

You jump to `map` in `core.clj` when `core.clj` *_is not_* being displayed in another
window in the current frame.

With both the default behavior and the alternative behavior defined above, the
definition of `map` will be shown in the current window.

=== Example 2

You jump to `map` in `core.clj` when `core.clj` *_is_* being displayed in another window
in the current frame.

With the default behavior, the definition of `map` will be shown in the current
window; you will now have two windows showing `core.clj`, and the existing
`core.clj` window will be unchanged.

With the alternative behavior defined above, the definition of `map` will be
shown in the existing `core.clj` window; all windows will show the same buffer as
before the jump, and the current window will now be the one showing `core.clj`.

== 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 kbd:[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 minibuffer completion:

[source,lisp]
----
(require 'icomplete)
----

You can learn more about `icomplete`
https://www.gnu.org/software/emacs/manual/html_node/emacs/Icomplete.html[here].

=== 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 https://github.com/DarwinAwardWinner/ido-completing-read-plus[`ido-completing-read+`].
You might also want to install https://github.com/lewang/flx[`ido-flex`].

=== ivy (recommended)

If you're fine with installing a third-party package for enhanced minibuffer
completion you can't go wrong with the modern and versatile
http://oremacs.com/2015/04/16/ivy-mode/[ivy].

== Message Displayed on Connect

By default CIDER will display an inspirational message when a new connection is
established. This behavior is configurable via `cider-connection-message-fn`:

[source,lisp]
----
;; make the message more educational
(setq cider-connection-message-fn #'cider-random-tip)
;; disable this extra message altogether
(setq cider-connection-message-fn nil)
----

The default messages are stored in the variable `cider-words-of-inspiration` that
you can tweak easily yourselves:

[source,lisp]
----
(add-to-list 'cider-words-of-inspiration "Moar inspiration!")
----

Of course, it goes without saying that you can do the same with `cider-tips`.

IMPORTANT: This is probably one of the most important CIDER features. Disable
those amazing messages at your own risk!

== Log nREPL Communications

If you want to see all communications between CIDER and the nREPL
server:

[source,lisp]
----
(setq nrepl-log-messages t)
----

CIDER will then create buffers named `+*nrepl-messages conn-name*+` for
each connection.

The communication log is tremendously valuable for
debugging CIDER-to-nREPL problems and we recommend you enable it when
you are facing such issues.

== Hide Special nREPL Buffers

If you're finding that `+*nrepl-connection*+` and `+*nrepl-server*+`
buffers are cluttering up your development environment, you can
suppress them from appearing in some buffer switching commands like
`switch-to-buffer`(kbd:[C-x b]):

[source,lisp]
----
(setq nrepl-hide-special-buffers t)
----

If you need to make the hidden buffers appear when using
`switch-to-buffer`, type kbd:[SPC] after issuing the command. The
hidden buffers will always be visible in `list-buffers` (kbd:[C-x C-b]).

== Prefer Local Resources Over Remote Resources

To prefer local resources to remote resources (tramp) when both are available:

[source,lisp]
----
(setq cider-prefer-local-resources t)
----

== Translate File Paths

If you are running Clojure within a Docker image, or doing something similar (i.e. you're `cider-connect`ing to a process,
and there's a directory mapping for your source paths), you typically need to set `cider-path-translations`
for jump-to-definition to properly work. For instance, suppose your app is
running in a docker container with your source directories mounted there as volumes. The
navigation paths you'd get from nREPL will be relative to the source in the
docker container rather than the correct path on your host machine. You can add
translation mappings easily by setting the following (typically in `.dir-locals.el`):

[source,lisp]
----
((nil
  (cider-path-translations . (("/root/.m2" . "/Users/foo/.m2")
                              ("/src/" . "/Users/foo/projects")))))
----

Each entry will be interpreted as a directory entry so trailing slash
is optional. Navigation to definition will attempt to translate these locations, and
if they exist, navigate there rather than report that the file does not
exist. In the example above, the `.m2` directory is mounted at `/root/.m2`
and the source at `/src`. These translations would map these locations
back to the user's computer so that navigation to definition would work.

Using the `eval` pseudo-variable you can make the translation dynamic, enabling
the possibility of sharing the `.dir-locals.el` across a team of developers with
different configurations.

[source,lisp]
----
((nil . ((eval . (customize-set-variable 'cider-path-translations
                                         (list
                                           (cons "/src" (clojure-project-dir))
                                           (cons "/root/.m2" (concat (getenv "HOME") "/.m2"))))))))
----

In this example, the path `/src` will be translated to the correct path of your
Clojure project on the host machine. And `/root/.m2` to the host's `~/.m2` folder.

You need to run `lein deps` (or `clojure -P`, etc) in the host machine in order for
navigation to fully work, at least once, and then, preferably, every time your Maven dependencies change.
This allows the `.m2` part of `cider-path-translations` to be actually useful.

If you can't or won't do that, you can use TRAMP capabilities (which CIDER supports) instead of
setting up `cider-path-translations`. For that, you'd typically need to set up a SSH daemon
within your Docker image. 

== Filter out namespaces in certain namespace-related commands

You can hide all nREPL middleware details from `cider-browse-ns*` and `cider-apropos*`
commands by customizing the variable `cider-filter-regexps`. The value of this
variable should be a list of regexps matching the pattern of namespaces you want
to filter out.

Its default value is `+'("^cider.nrepl" "^refactor-nrepl" "^nrepl")+`,
the most commonly used middleware collections/packages.

An important thing to note is that this list of regexps is passed on to the middleware
without any pre-processing. So, the regexps have to be in Clojure format (with twice the number of backslashes)
and not Emacs Lisp. For example, to achieve the above effect, you could also set `cider-filter-regexps` to `'(".*nrepl")`.

To customize `cider-filter-regexps`, you could use the Emacs customize UI,
with kbd:[M-x] `customize-variable` kbd:[RET] `cider-filter-regexps`.

An alternative is to set the variable along with the other CIDER configuration.

[source,lisp]
----
(setq cider-filter-regexps '(".*nrepl"))
----

== Truncate long lines in special buffers

By default contents of CIDER's special buffers such as `+*cider-test-report*+`
or `+*cider-doc*+` are line truncated. You can set
`cider-special-mode-truncate-lines` to `nil` to make those buffers use word
wrapping instead of line truncating.

[source,lisp]
----
(setq cider-special-mode-truncate-lines nil)
----

IMPORTANT: This variable should be set *before* loading CIDER (which means before
`require`-ing it or autoloading it).

== nREPL Connection Hooks

CIDER provides the hooks `cider-connected-hook` and `cider-disconnected-hook`
that get triggered when an nREPL connection is established or closed respectively.

Here's how CIDER uses the first hook internally to display its famous inspirational
messages on connect:

[source,lisp]
----
(defun cider--maybe-inspire-on-connect ()
  "Display an inspiration connection message."
  (when cider-connection-message-fn
    (message "Connected! %s" (funcall cider-connection-message-fn))))

(add-hook 'cider-connected-hook #'cider--maybe-inspire-on-connect)
----

NOTE: There are also lower-level `nrepl-connected-hook` and `nrepl-disconnected-hook` that CIDER uses internally. Most of the time end-users would be better off using
the CIDER-level hooks instead.
