installation

Installation

The easiest way to get going is to use emacs' own package manager to install clj-refactor.

It's available on melpa and melpa-stable:

M-x package-install clj-refactor

Melpa will get you a snapshot of the cutting edge, which you should probably combine with a snapshot release of the middleware, and melpa-stable a stable release.

If you haven't configured these package archives yet, you can do:

(add-to-list 'package-archives '("melpa" . "http://melpa.org/packages/"))
;; or
(add-to-list 'package-archives '("melpa-stable" . "http://stable.melpa.org/packages/"))

To let emacs' know about them.

Setup

(require 'clj-refactor)
(add-hook 'clojure-mode-hook (lambda ()
                               (clj-refactor-mode 1)
                               ;; insert keybinding setup here
                               ))

You'll also have to set up the keybindings in the lambda. Read on.

Setup keybindings

All functions in clj-refactor have a two-letter mnemonic shortcut. For instance, rename-file-or-dir is rf. You get to choose how those are bound. Here's how:

(cljr-add-keybindings-with-prefix "C-c C-m")
;; e.g. rename files with `C-c C-m rf`.

The prefix C-c C-m is fast and easy on the hands, but it clobbers the binding for cider-macroexpand-1, so you might want to pick something else.

If you would rather have a modifier key, instead of a prefix, do:

(cljr-add-keybindings-with-modifier "C-s-")
;; eg. rename files with `C-s-r C-s-f`.

If neither of these appeal to your sense of keyboard layout aesthetics, feel free to pick and choose your own keybindings with a smattering of:

(define-key clj-refactor-map (kbd "C-x C-r") 'cljr-rename-file-or-dir)

The keybindings suggested here might be conflicting with keybindings in either clojure-mode or cider. Ideally, you should pick keybindings that don't interfere with either.

Optional setup

Refactor nREPL middleware

For some of the more advanced refactorings we've written an nrepl middleware called refactor-nrepl.

From version 2.2.0 onwards if cider-jack-in is used it is injected automatically.

profiles.clj or profile.boot don't need to be modified anymore for the above usecase!

On the other hand if a standalone REPL or an embedded nREPL server is used you will need to manually add this dependency (see below).

You also still need to do this if you are using the current latest stable release 2.0.0!

Add the following, either in your project's project.clj or in the :user profile found at ~/.lein/profiles.clj:

:plugins [[refactor-nrepl "2.0.0"]
          [cider-nrepl "0.10.2"]]

If you want to run on the bleeding edge you can do:

:plugins [[refactor-nrepl "2.2.0-SNAPSHOT"] 
          [cider-nrepl "0.11.0-SNAPSHOT"]]

WARNING The analyzer needs to eval the code too in order to be able to build the AST we can work with. If that causes side effects like writing files, opening connections to servers, modifying databases, etc. performing certain refactoring functions on your code will do that, too.

Yasnippet

If you're not using yasnippet, then the "jumping back"-part of adding to namespace won't work. To remedy that, enable the mode with either:

(yas-global-mode 1)

or

(add-hook 'clojure-mode-hook (lambda () (yas/minor-mode 1)))