Packages & configurations for Ruby on Rails development for GNU Emacs 23+

Language: Emacs Lisp


Packages & configurations for Ruby on Rails development on Emacs.

Tested on GNU Emacs 23.3 & 24.3, Ruby 1.8.7/1.9.3/2.0.0/2.1.2, on Ubuntu Linux 11.10/12.04, RHEL 5.x.

Package integrated[]

Package Description Homepage melpa depends
ac-inf-ruby Enable auto-complete in inf-ruby sessions Y auto-complete
anything-rails Adds useful anything sources for use with Ruby on Rails development anything
bundler Interact with Bundler from Emacs Y
enh-ruby-mode Major mode for editing Ruby files Y
flymake-ruby A flymake handler for ruby-mode files Y
geben DBGp protocol frontend, a script debugger Y
haml-mode Major mode for editing Haml files Y
inf-ruby Run a Ruby process in a buffer Y
jquery-doc jQuery api documentation interface for emacs Y
js2-mode Improved JavaScript editing mode Y
know-your-http-well Look up the meaning of HTTP headers, methods, relations, status codes Y
know-your-css-well CSS properties description in your emacs [Inspired by know-your-http-well]
milkode Command line search and direct jump with Milkode Y
php-mode Major mode for editing PHP code Y
projectile-rails Minor mode for Rails projects based on projectile-mode Y projectile
pry Pry support within Emacs
rails-log-mode Major mode for viewing Rails log files Y
rhtml-mode major mode for editing RHTML files Y
rainbow-mode a minor mode displays color strings with the color they represent as background.
rdebug a full-blown debugger user interface to the Ruby rdebug debugger shell
rinari Rinari Is Not A Rails IDE Y
robe Code navigation, documentation lookup and completion for Ruby Y
rubocop An Emacs interface for RuboCop Y
ruby-block highlight matching block Y
ruby-compilation run a ruby process in a compilation buffer Y
ruby-tools Collection of handy functions for ruby-mode. Y
web-mode major mode for editing html templates Y
yaml-mode Major mode for editing YAML files Y
yari Yet Another RI interface for Emacs Y

some other packages might be useful (but not included here)


Package Description Homepage melpa
omniref Emacs interface for Ruby documentation search engine Y
realgud A modular front-end for interacting with external debuggers (supports rdebug) Y
projectile Manage and navigate projects in Emacs easily Y


M-x load-file RET /path/to/dotemacs-rails/_init.el RET


Add this into your dotemacs (~/.emacs or ~/.emacs.d/init.el)

(load-file "/path/to/dotemacs-rails/_init.el")

Note: If you don’t care about compabilities with emacs-23.x, you can install those 3rd-party packages directly from MELPA. (And remember to comment out line 18-25 in _init.el which would add subdirectory into load-path)


Major Modes

extension major mode alternative
.rb ruby-mode (emacs built-in) enh-ruby-mode
.erb web-mode rhtml-mode
.haml haml-mode
.yml yaml-mode
.php web-mode php-mode
.rake ruby-mode (emacs built-in) enh-ruby-mode
.js js-mode (emacs built-in) js2-mode
.css css-mode (emacs built-in)

To use alternative major-mode, you need to activate them manually (M-x major-mode-name after file opened, or customized =auto-mode-alist= by yourself).


Advantages over built-in ruby-mode:

  • Dynamic syntax checking
  • beginning-of-defun and end-of-defun would work (while emacs < 24 would not)
  • imenu would work (but emacs < 24 would not)


  • To use enh-ruby-mode, ruby intepreter must exist in your PATH, and it must be >=1.9.2

Jumping Across Files

For Rails project, rinari-minor-mode would be activated for ruby & erb buffers:

C-c ; f c	rinari-find-controller
C-c ; f e	rinari-find-environment
C-c ; f f	rinari-find-file-in-project
C-c ; f h	rinari-find-helper
C-c ; f i	rinari-find-migration
C-c ; f j	rinari-find-javascript
C-c ; f l	rinari-find-plugin
C-c ; f m	rinari-find-model
C-c ; f n	rinari-find-configuration
C-c ; f o	rinari-find-log
C-c ; f p	rinari-find-public
C-c ; f s	rinari-find-script
C-c ; f t	rinari-find-test
C-c ; f v	rinari-find-view
C-c ; f w	rinari-find-worker
C-c ; f x	rinari-find-fixture
C-c ; f y	rinari-find-stylesheet

Note: use C-u M-x info RET dotemacs-rails/info/ to view info pages of rinari

open gems source

bundle-open wraps bundle open, which opens gem according to Gemfile.

Jumping to Class/Symbol Definition

method 1: use ctags (emacs built-in)

  1. make sure you’ve installed exuberant ctags ( use ctags --version to check
  2. run ctags -R -e . in your Rails project
  3. call find-tag to jump to class/function at point

Note: rinari-minor-mode would automatically updating your tags-file-name variable whenever you enter a rails project,

method 2: use robe

  1. Use M-x rinari-console or M-x inf-ruby-console-auto to launch Rails console (for non-Rails project, use M-x inf-ruby-console-default)
  2. Call M-x robe-jump

Code Completion

in ruby source buffer:

  • M-x hippie-expand is always your friend (zero configuration, zero pain)
  • ac-source-robe (from package robe) enables auto-complete for ruby buffers (you need to install auto-complete by yourself)

But it seems to make editing too slow, thus disabled by default. Use M-x ruby-mode-enable-ac to activate it for current buffer. (If you want to activate it each time a ruby buffer opens, add (add-hook 'ruby-mode-hook 'ruby-mode-enable-ac) to your ~/.emacs .)

And make sure you’ve started an inf-ruby process (see section console below).

in irb shell buffer:

  • [ ] ac-inf-ruby (but not enabled in this suite as it won’t work in my machine)
    • [ ] what if you’re using pry as console (if ac-inf-ruby works for irb)?

Document Lookup

yari from package yari

  1. use gem rdoc <gemname> [-v <version>] to generate RDoc/RI documentation (generated files live in ruby/lib/ruby/gems/1.9.x/doc/gemname-1.x.x/)
  2. call M-x yari to lookup documentaion


If you’ve started a console, the following features from robe would be available:

  • M-x robe-doc: Show docstring for the method at point.
  • eldoc would make use of robe if minor mode robe-mode activated

Looking up documentation in pry console running inside emacs (see below pry-console-in-emacs)

  • ri command in pry console
  • show-doc command in pry console


Syntax Checking

For ruby source code:

  • If you’re using enh-ruby-mode as major mode for ruby source file, it would check syntax dynamically and highlight the errors
  • Use M-x compile RET ruby -w -c <filename.rb>
  • Use M-x flymake-ruby
  • Use M-x rubocop-check-current-file (you need to install gem rubocop)


use rdebug emacs package from ‘ruby-debug’ gem + GUD multi-window UI


  • install ruby debugger[]
    • for ruby 1.8.x: gem install ruby-debug
    • for ruby 1.9.x: gem install debugger
    • for ruby 2.x: gem install byebug
  • install emacs package from:


  1. optional: add debugger statement into your source code[]
    • for rubyg 1.8 + ruby-debug gem: add require 'ruby-debug' ; Debugger.start on the file header and debugger to the line you want the debugger to stop
    • for ruby 1.9 + debugger gem: add require "debugger"; debugger
    • for ruby 2.x + byebug gem: you just need to insert byebug
  2. in emacs’s shell buffer or eshell buffer, cd to your Rails project’s root folder (this means to make your current working directory is correct . For Rails project, you should start the server/console/rake from the project root folder).
  3. type M-x rdebug RET rdebug --emacs=3 script/rails -- server RET. GUD multi-windows UI would show up.
  4. now you can type commands such as break <file>:<line>, next, step, continue into debug the program (type help for help on commands)


  • GUD multi-windows //(info “(emacs) GDB-UI Layout”)
  • easy to customization (compared to [realgud])


  • not updated for 5 years, thus not fully compatible with Emacs 23/24 (e.g. rdebug-track-mode not work in shell buffer)


  • Use C-u M-x info RET <dotemacs-rails-dir>/info/ RET to view the documentaion
  • (not work yet?) Use M-x turn-on-rdebug-track-mode in shell/eshell buffer to …

method 2: use package realgud (


  1. realgud supports multiple debuggers, including gdb, ruby-debug, pdb (python), perldb, bashdb etc. (refer Debuggers Supported · rocky/emacs-dbgr Wiki)
  2. realgud-track-mode allows your attach to an existing debugger session in a comint-shell
  3. it is actively maintained

Installation: refer How to Install · rocky/emacs-dbgr Wiki · GitHub

or install it manually:

mkdir ~/.emacs.d/packages
cd ~/temp
wget -c -O
cp -a emacs-dbgr-master/realgud ~/.emacs.d/packages/
cp emacs-dbgr-master/realgud.el ~/.emacs.d/packages/realgud/
cd ~/.emacs.d/packages/realgud
wget -c
wget -c
wget -c
echo "(add-to-list 'load-path \"~/.emacs.d/packages/realgud\")" >> ~/.emacs.d/init.el
echo '(load-library "realgud")' >> ~/.emacs.d/init.el

Console (repl/shell/comint)

For Rails projects, you can use:

  • M-x rinari-console from package rinari
  • M-x projectile-rails-console from package projectile-rails (but you need to install projectile by yourself, as it is not include in this suite)

For projects of other type, you can always use inf-ruby-console-auto from package inf-ruby

  • M-x inf-ruby-console-rails runs rails console for rails project
  • M-x inf-ruby-console-default runs bundle console for bundler-enabled project
  • M-x inf-ruby-console-gem runs bundle exec irb (if Gemfile exists) or irb -I lib
  • M-x inf-ruby-console-auto automatically choose above 3 methods

Using pry as console in emacs

run-pry from package pry
M-x run-pry
  • if you’ve add pry-rails into your Gemfile, then (after bundle install finished ) rinari-console or inf-ruby-console-rails would be powered by pry

Some notes for emacs:

if ENV['TERM']=='dump'
   Pry.config.pager = false
   # uncomment the following two lines if your emacs doesn't support ANSI color
   #Pry.config.color = false
   #Pry.config.auto_indent = false 

if you want to disable Pry for rinari-console or inf-ruby-console-rails, type



M-: (setenv "DISABLE_PRY_RAILS" "1") RET

Database Console

Command rinari-sql from package rinari wraps Emacs’s built-in sql-mysql/sql-sqlite/sql-postgresql. The difference is that it would try to read config/database.yml from your Rails project and guess the parameters sql-database, sql-user etc. But sometimes it doesn’t work well.

View Logs

As log files could be very big, it is not a good idea to open it directly into Emacs. You can use the following ways:

  • Call tail -f log/development.log in shell/eshell buffer
  • Use M-x rails-log-view-development from package rails-log-mode, which wraps tail -f. The advantage is that all the file paths in the log are navigatable, thus you can press Enter to open a file in the stack trace
  • If you’ve installed package projectile, you can use M-x projectile-rails-find-log . It allow you find a log file and enable auto-revert-tail-mode in its buffer.

Other tips for web development

debugging php with geben

GEBEN is a software package that interfaces Emacs to DBGp protocol with which you can debug running scripts interactively. At this present DBGp protocol are supported in several script languages with help of custom extensions.


  1. install xdebug extension on your php server:
  2. type M-x geben RET on Emacs to start the debugger on port 9000
  3. when requesting from web browser, remember to activate xdebug with adding XDEBUG_SESSION_START=session_name parameter to the URL (or with some web browser extensions (refer to for detailed info)
  4. geben would display the script being debugged on Emacs

http status / http header

package know-your-http-well provides the following commands to consult http related info:

  • M-x http-header
  • M-x http-method
  • M-x http-relation
  • M-x http-status-code
  • M-x http-status-code

css property

package know-your-css-well provides the following commands:

  • M-x css-property

rainbow-mode highlight color names in css files

Package rainbow-mode provides a minor mode rainbow-mode, which sets background color to strings that match color names, e.g. #0000ff is displayed in white with a blue background.


Package jquery-doc provides:

  • completion source for auto-complete and company-mode
  • a command jquery-doc to lookup the documentation for a method in jquery

other tips

use milkode to build a big code database for searching

  • add sass-mode
  • add rdoc-mode, textile-mode
  • remove ruby-debug.el (as it is useless)

Project Statistics

Sourcerank 2
Repository Size 1.89 MB
Forks 1
Watchers 2
Dependencies 0
Tags 1
Last updated

Recent Tags See all

tip November 01, 2016

Something wrong with this page? Make a suggestion

Last synced: 2017-03-04 12:05:30 UTC

Login to resync this repository