1. Installing Emacs on Windows
  2. Installing Emacs on Mac
  3. For anyone totally new to Emacs
  4. If you get into trouble
  5. How to close emacs
  6. Useful Emacs Related Links
  7. Start elisp REPL
  8. Help
  9. Help Documentation for Functions
    1. If you want to browse around elisp source code
  10. Some of the packages I recommend
  11. Marking and Highlighting
  12. Package Management
  13. Directory Editor: Dired
    1. WDired
  14. List open Buffers
  15. Windows
  16. Bookmarks
  17. Replace annoying ^M characters
  18. Some more useful commands
    1. Font Lock and colors
    2. Change Font Size
    3. Turn bell off
    4. Character count
  19. Rectangular, Block, Vertical Editing
  20. Paragraph Filling and Word wrap
  21. Changing how the lines are displayed
  22. Search and Replace
  23. Regular expressions
  24. Magit (Git)
    1. Staging files in Magit
    2. Making a Commit in Magit
    3. View Log Messages in Magit
  25. Subversion
  26. Ediff and Comparing files and directories/folders
  27. Ruby
  28. Macros
  29. Align
  30. Tramp Mode
  31. Undo
  32. Frames (things that are called windows outside of emacs)
  33. Tail
  34. Minor Modes
  35. Spelling
  36. UTF8 chars
  37. Byte compile
  38. Find Unbound Keys and possibly key binding mappings

Installing Emacs on Windows

Download Binary from Here

I like to run emacs from cygwin on windows to take advantage of all unix commands.

Installing Emacs on Mac

On mac, I find it's easiest to grab a binary:

http://emacsformacosx.com/builds

Then, I use a bash script to open it so that current terminal environment is available:

Create ./emacs.sh inside /Applications/Emacs.app/Contents/MacOS/bin

#!/bin/bash
/Applications/Emacs.app/Contents/MacOS/Emacs "$@" 

Then symlink to it

 sudo ln -s emacs.sh emacs

Then add /Applications/Emacs.app/Contents/MacOS/bin to PATH and good to go.

Note that OS-X sometimes has emacs pre-installed under /usr/bin/emacs (or maybe I installed it and forgot) Here's how I checked and fixed that

which emacs
sudo mv /usr/bin/emacs /usr/bin/emacs.orig
sudo ln -s /Applications/Emacs.app/Contents/MacOS/Emacs /usr/bin/emacs

For anyone totally new to Emacs

If you're considering learning emacs, I say go for it! Emacs is probably the most interesting, useful, amazing software I've ever used.

It takes a lot of effort to learn, but as someone who's already been down that path, I can say it's definitely worth it.

If you're completely new, I suggest you read and follow thru the tutorial that comes as part of emacs. To start the tutorial do the following.

  • Open Emacs.
  • Press "Esc" and then "x". You should see "M-x" in the minibuffer.
  • Then type "help-with-tutorial" and press Enter.

If that works, it should bring up an "Emacs Tutorial" buffer. If you read thru and follow along, it will teach you the basic key chords to use to navigate around.

Once you've made it thru the tutorial, the next step is to try to use emacs as much as possible. Try using it to write emails, blog posts, code, documentation, and anything else you need to write.

If you're like me, you'll feel like a complete nincompoop the first few weeks but stick with it!

After a few weeks, start exploring elisp packages like magit for interacting with git, org-mode for taking notes, and paredit for writing lisp.

After a month or so, try writing some elisp.

I've been using emacs for years and I still learn new things every day. So be patient, and keep at it.

If you get into trouble

If you ever get stuck or if emacs seems frozen, try C-g

How to close emacs

Use C-x C-c to close emacs. But why would you want to do that?!

Useful Emacs Related Links

Start elisp REPL

M-x ielm

Help

C-h v <variable name> for help on a variable

C-h f <method name> for help on a method

C-h k <key chord> for help on key sequence

C-h b describe-bindings for all possible key bindings available inside the current buffer

M-x apropos regex search for commands.

C-h i open info

M-x info-apropos to perform regex search for topics inside info

C-h m describe-mode, displays documentation of current major and minor modes

Help Documentation for Functions

Use find-function to look around for el functions. This is also handy when trying to find the el file in which a function is defined.

M-x find-function
C-h f

If you want to browse around elisp source code

By default, only elc files are installed for emacs. To jump from functions and browse source code, you need to install the emacs el source files.

For example, on ubuntu (11.10), install the emacs-snapshot-el package. Or build emacs from source

Some of the packages I recommend

  • starter-kit a great way to organize your .emacs files
  • paredit rainbow-delimiters for editing lisp. Now that I'm comfortable with paredit, it's hard to useany other editor for lisp
  • color-theme and color-theme-solarized I like dark background and these make it easy to customize look and feel.
  • auto-complete auto completion magic everywhere!
  • js-comint javascript repl in emacs
  • gist quickly post gists
  • ace-jump-mode moving around more easily
  • markdown-mode I used markdown mode to write this document
  • twittering-mode pretty slick twitter client
  • clojure-mode and cider, off course!

Marking and Highlighting

By default, there's no visual indication that you've marked some text. M-x transient-markup mode will enable Transient Markup Mode and make it so that marked text is highlighted.

Instead of enabling transient marke mode, you can also use C-spc C-spc to enable it temporarily.

C-spc set mark

C-x C-x jump back to mark

C-u C-<spc> to jump cursor (cycle thru previously set marks)

Package Management

The elpa is the elisp package archive. It's like apt-get or maven central for elisp

Add this to your .emacs.d/init.el

(require 'package)
(add-to-list 'package-archives
  '("marmalade" . "https://marmalade-repo.org/packages/"))

There are several repositories that contain elisp packages. Here's another one I like to add

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

Restart emacs and then do this to explore the packages available

M-x package-refresh-contents
M-x package-list-packages

Directory Editor: Dired

It's awesome. After using Dired for a while, you'll never want to use Windows Explorer or OS X Finder ever again! It's a pretty handy way to navigate thru folders and files.

WDired

Just when you thought Dired was totally awesome! There's Wdired! Edit directories of files as if it's a "normal" emacs text buffer. Enter Dired and then type C-x C-q or do M-x dired-toggle-read-only.

Once in wdired mode, you can rename files, query-replace, use macros, or whatever.

Then do C-c C-c or M-x wdired-finish-edit to commit the changes to the filesystem.

List open Buffers

C-x C-b or M-x list-buffers

Windows

C-x o other-window

C-x 0 delete current window

C-x 1 delete all other windows

Bookmarks

C-x r m bookmark-set

C-x r b bookmark-jump

M-x rename-bookmark change name of existing bookmark

C-x r l listl all bokmarks

Inside the Bookmark list, type e next to a bookmark to edit annotations. Type C-c C-c to exit the list

Replace annoying ^M characters

Replace ^M character with spaces

M-% RET C-q C-m RET RET !

Some more useful commands

C-q quoted characters, which is useful for inserting control characters

M-x comment-region (I bind this to C-/) Mark a bunch of text, then use comment-region to comment it out. It uses the appropriate comment syntax in almost any mode you can think of.

comment-indent-new-line M-q autofill paragraph. This takes a chunk of text and formats it nicely.

Font Lock and colors

`M-x list-colors-display'

Change Font Size

Increase Font Size: C-x C-+

Decrease Font Size: C-x C--

Turn bell off


xset b off

Character count

count-line-region

Rectangular, Block, Vertical Editing

This is so powerful, I use this all. the. time.

Select a rectangle using C-spc and moving cursor to bottom right of rectangle (no need to type C-spc again)

C-x r k kill-rectangle (deletes it and adds to rect kill ring)

C-x r d delete-retangle (without putting into kill ring)

C-x r y yank-rectangle Insert last killed rectangle

C-x r c clear-rectangle Blank out the area using spaces and don't save it

C-x r o open-rectangle Insert blank rectangle in area

C-x r r <any char> copy rectange to register

C-x i r <any char key>

C-x r t string Enter change contents of marked retange to string

Paragraph Filling and Word wrap

auto-fill-mode automatcially inserts line break (rather than having to manually do M-q)

Sometimes auto-fill-mode is annoying though, so just type `M-x auto-fill-mode` to toggle it off.

M-x fill-column or M-q to fill paragraph

Changing how the lines are displayed

(wrapped with backspace or continue on beyond right edge of window)

M-x toggle-truncate-lines M-x long-lines

When you do C-x 3 to create new window, it will not wrap lines by default. You can change this behavior using:

`M-x truncate-partial-width-windows`

Search and Replace

C-x s search (this is handy for quickly moving point to a position in a buffer too!)

C-x r search backword

C-M s regex search forward

C-M r regex search backword

C-n n narrow-to-region

C-n w widen

So to restrict a search to a region. First, set the region Next, do C-x n n Do the search Then, do C-x n w to do away with the restriction.

How do I insert a new line into a regex? Use C-q C-j.

Regular expressions

. matches everything except for newlines. If you want your regex to span multiple lines, you can't use .

To get around this problem, use the character classes: [[:ascii:]] and [[:nonascii:]]

For example, this regex:

"v:name\">\\([[:ascii:]]*\\)</h1>"

Matches the following html

<h1 property="v:name">Creamy Tomato-Basil Pasta with Chicken</h1>

Magit (Git)

It was definitely worth the effort to learn how to use magit. It is hands down the most powerful interface to git I've ever used.

Staging files in Magit

s stages individual files C-u s or S stages all untracked files u to unstage individual files U to unstage all

i add individual filenames to .gitignore C-u i will prompt for name of file to add to .gitignore

Type Tab to toggle details. For example, typing Tab when point is on modified files shows diff between working copy and last commit.

Making a Commit in Magit

c to pop open a commit buffer to write a comment C-c C-c to perform the commit

View Log Messages in Magit

l while in *magit-status* gives log of commits

Subversion

(I don't use this very often)

M-x svn-examine, then choose dir. This puts you into svn-status mode.

Once in svn-status:

g to update

c to commit

a to add

U to update

m to mark

if file is in conflict use, vc-resolve-conflicts to open ediff once conflicts are resolved, use svn-status-resolved to resolve file (if you're in svn-status dired view, make sure to mark the file(s) first

Ediff and Comparing files and directories/folders

vc-resove-conflicts will automatically start ediff. Use E to browse ediff manual.

To compare directories. Open one directory in diff and then use: M-x dired-compare-directories. By default, this does a simple comparison of whether all filenames in dir A match all filenames in dir B.

Ruby

(There's probably better ways to do this; I haven't written any ruby in a while)

M-x run-ruby to run irb (install inf-ruby.el if run-ruby isn't available)

From inside irb:

C-c C-l to load ruby file

Macros

Macros Rock!

C-x ( start macro definition

C-x ) end macro definition

C-x e execute last definied macro

M-n C-x e execute last defined macro n times

C-x C-k e edit last macro

C-x C-k n name last macro

C-x C-k r apply macro to region lines

C-x C-k d kmacro-delete-ring-head

C-x C-k p kmacro-cycle-ring-previous

C-x C-k n kmacro-cycle-ring-next

M-x insert-kbd-macro RET macroname to insert Lisp code that represents macro

Align

M-x align line columns up based on spaces

M-x align-regex specify custom regex that columns are aligned around. For example, we'd like to align the following around ::

# Author:: Dave Paroulek
# Copyright:: Copyright (c) 2002 The Pragmatic Programmers, LLC
# License::       Distributes under the same terms as Ruby

To do this, use M-u M-x align-regex RET ::&#40;\s-*&#41; RET RET RET y (I'm not sure what the - stands for in the regex and if I take it out, it still works correctly)

# Author::    Dave Paroulek
# Copyright:: Copyright (c) 2002 The Pragmatic Programmers, LLC
# License::   Distributes under the same terms as Ruby

Tramp Mode

Tramp mode allows you to ssh into remote hosts and view in emacs just as if they were local files! (Very slick).

On windows, use /plink:user@host:/filepath

Cool: if you open eshell while browsing a remote directory, it'll open a remote eshell!

Undo

C-_ can be used to cycle thru the previous undo's. Every time you do a C-_ it makes a change that is added to the stack of undos. But as long as you continue consecutive C-_ commands, you are moving down the stack. To stop moving down the stack, simply do any other command other than a C-_ (like C-f). After that, type C-_ will "redo".

Frames (things that are called windows outside of emacs)

C-x o switch between frames

Tail

Need itail package (I think that's the name of it) Open a file, and use auto-revert-tail-mode

Minor Modes

Check out Emacs Rocks! for a great demonstration of how to create minor modes

Spelling

I think you need aspell for ispell-mode to work on os x. But tried compiling aspell and it failed with error message, haven't had a chance to get back to troubeshooting

UTF8 chars

C-x 8 <unicode number> See ucs-commands.el

Or use input methods. Change input method using `C-‘ and choose rfc1345. Then use combo of ampersand + other keys to write utf8 chars.

Byte compile

To compile all el files inside a directory, use:

M-u 0 M-x byte-recompile-directory ;; see function docs

Find Unbound Keys and possibly key binding mappings

Install unbound package, then: M-x describe-unbound-keys

Using max complexity of 5 usually gives good options