Sample Configuration (ERC Manual)

5.3 Sample Configuration

Here is an example configuration for ERC. Don’t panic if you aren’t familiar with ‘use-package’ or have no interest in learning it. For our purposes, it’s just a means of presenting configuration details in a tidy, standardized format. If it helps, just pretend it’s some make-believe, pseudo configuration language. And while the syntax below is easy enough to intuit and adapt to your setup, you may wish to keep the following in mind:

Each use-package “declaration” focuses on a library “feature”, which is just a symbol you’d normally require in your config.
Emacs loads anything in a :config section after loading whatever library provides the declaration’s feature.
Everything in a :custom or :custom-face section is basically something you’d find in your custom-file.
For more info, see (elisp)Named Features, or see (use-package)Top.

The following would typically go in your init file. Experienced users may opt to keep any non-settings, like commands and functions, in a dedicated ~/.emacs.d/.ercrc.el. Whatever the case, please keep in mind that you can replace nearly all of the following with Custom settings (see Sample configuration via Customize).

;;; My ERC configuration -*- lexical-binding: t -*-

(use-package erc
  :config
  ;; Prefer SASL to NickServ, colorize nicknames, and show side panels
  ;; with joined channels and members
  (setopt erc-modules
          (seq-union '(sasl nicks bufbar nickbar scrolltobottom)
                     erc-modules))

  :custom
  ;; Protect me from accidentally sending excess lines.
  (erc-inhibit-multiline-input t)
  (erc-send-whitespace-lines t)
  (erc-ask-about-multiline-input t)
  ;; Scroll all windows to prompt when submitting input.
  (erc-scrolltobottom-all t)

  ;; Reconnect automatically using a fancy strategy.
  (erc-server-reconnect-function #'erc-server-delayed-check-reconnect)
  (erc-server-reconnect-timeout 30)

  ;; Show new buffers in the current window instead of a split.
  (erc-interactive-display 'buffer)

  ;; Insert a newline when I hit <RET> at the prompt, and prefer
  ;; something more deliberate for actually sending messages.
  :bind (:map erc-mode-map
              ("RET" . nil)
              ("C-c C-c" . #'erc-send-current-line))

  ;; Emphasize buttonized text in notices.
  :custom-face (erc-notice-face ((t (:slant italic :weight unspecified)))))

(use-package erc-sasl
  ;; Since my account name is the same as my nick, free me from having
  ;; to hit C-u before M-x erc to trigger a username prompt.
  :custom (erc-sasl-user :nick))

(use-package erc-join
  ;; Join #emacs and #erc whenever I connect to Libera.Chat.
  :custom (erc-autojoin-channels-alist '((Libera.Chat "#emacs" "#erc"))))

(use-package erc-fill
  :custom
  ;; Prefer one message per line without continuation indicators.
  (erc-fill-function #'erc-fill-wrap)
  (erc-fill-static-center 18)

  :bind (:map erc-fill-wrap-mode-map ("C-c =" . #'erc-fill-wrap-nudge)))

(use-package erc-track
  ;; Prevent JOINs and PARTs from lighting up the mode-line.
  :config (setopt erc-track-faces-priority-list
                  (remq 'erc-notice-face erc-track-faces-priority-list))

  :custom (erc-track-priority-faces-only 'all))

(use-package erc-goodies
  ;; Turn on read indicators when joining channels.
  :hook (erc-join . my-erc-enable-keep-place-indicator-on-join))

(defvar my-erc-read-indicator-channels '("#emacs")
  "Channels in which to show a `keep-place-indicator'.")

(defun my-erc-enable-keep-place-indicator-on-join ()
  "Enable read indicators for certain queries or channels."
  (when (member (erc-default-target) my-erc-read-indicator-channels)
    (erc-keep-place-indicator-mode +1)))

;; Handy commands from the Emacs Wiki.
(defun erc-cmd-TRACK (&optional target)
  "Start tracking TARGET or that of current buffer."
  (setq erc-track-exclude
        (delete (or target (erc-default-target) (current-buffer))
                erc-track-exclude)))

(defun erc-cmd-UNTRACK (&optional target)
  "Stop tracking TARGET or that of current buffer."
  (setq erc-track-exclude
        (cl-pushnew (or target (erc-default-target) (current-buffer))
                    erc-track-exclude
                    :test #'equal)))

Those familiar with use-package may have noticed the lack of :defer keyword args. This was done to conserve space, but you can just pretend that this user has enabled use-package-always-defer elsewhere.

Via Customize

As mentioned, Customize users can accomplish nearly all of the above via the Customize interface. Start by running M-x customize-group RET erc RET, and search for “Modules” with C-s modules RET. Toggle open the flyout menu to reveal the full widget panel, a web-form-like interface for “Erc Modules”. Tick the boxes for ‘bufbar’, ‘nickbar’, ‘nicks’, ‘sasl’, and ‘scrolltobottom’.

Next, search for the phrases “Erc Ask About Multiline Input”, “Erc Inhibit Multiline Input”, and “Erc Send Whitespace Lines”. These are the print names of three boolean options that control how ERC treats prompt input containing line breaks. When visiting each option’s section, twirl open its triangle icon to reveal its widget UI, and click its ‘[Toggle]’ button to set its value to t. While going about this, you may find it helpful to glance at the descriptions just in case you want to disable them later. When finished, hit C-x C-s or click ‘[Apply and Save]’ atop the buffer.

Now do the same for another couple options, this time having to do with automatic reconnection. But instead of searching for their print names, try running M-x customize-option RET ‘<option>’ RET, replacing ‘<option>’ with:

erc-server-reconnect-function, a function
erc-server-reconnect-timeout, a number

(If it helps, hit TAB for completion.) As you may have noticed, when customizing options individually, each buffer displays but a single option’s widget. When you get to the buffer for “Erc Server Reconnect Function”, you’ll see that ‘[Toggle]’ has been replaced with ‘[Value Menu]’ and that clicking it reveals three choices in a pop-up window. Enter 1 to select erc-server-delayed-check-reconnect before TAB’ing over to ‘[State]’ and hitting RET. Enter 1 again, this time to persists your changes.

For the final option, erc-server-reconnect-timeout, you’ll encounter a text field (instead of a button), which works like those in a typical web form. Enter ‘30’ and hit C-x C-s to save. Just for fun, click the group link for ‘Erc Server’ at the bottom of the buffer. You could just as well have set the last two options from this “custom group” buffer alone, which very much resembles the one for the ‘Erc’ group, which is actually the “parent” of this group (note the “breadcrumb” for group ‘Erc’ atop the buffer). Indeed, you can always get back here by running M-x customize-group RET erc-server RET from almost anywhere in Emacs.

To make sure you’ve got this, try quickly customizing the option erc-interactive-display, which lives in the ‘Erc Buffers’ group (M-x customize-group RET erc-buffers RET). As its doc string explains, the option controls where new buffers show up when you do M-x erc-tls RET or issue certain slash commands, like /JOIN #emacs-beginners RET, at ERC’s prompt. Change its value to the symbol buffer by choosing ‘Use current window’ (item 5) from the option’s ‘[Value Menu]’. Don’t forget to save.

If you need more practice, try enabling the boolean option erc-scrolltobottom-all, which lives in the ‘Erc Display’ group (M-x customize-group RET erc-display RET). When enabled, this option tells the ‘scrolltobottom’ module to adjust all ERC windows instead of just the one you’re currently typing in.

Now it’s time to set some key bindings for erc-mode-map, a major-mode keymap active in all ERC buffers. In general, it’s best to do this part either entirely or in conjunction with some lisp code in you init file. However, to keep things “simple”, we’ll do it all in customization buffers. To get started, hit M-x customize-group RET erc-hooks RET and search for “Erc Mode Hook”. In the widget form, click ‘[INS]’, and paste the following into the value field in place of the default text.

(lambda ()
  (keymap-set erc-mode-map "RET" nil)
  (keymap-set erc-mode-map "C-c C-c" 'erc-send-current-line))

Don’t worry about the line breaks. Emacs is smart enough to handle those. When you’re ready, click ‘[Apply and Save]’.

Next, try tweaking the face ERC uses to stylize server messages that say things like “SoAndSo has joined channel #chan”. Type M-x customize-face RET erc-notice-face RET. Click the “link”-looking button at the very bottom that says something like “Show All Attributes”. Untick ‘Weight’ and tick ‘Slant’. Then, in the latter’s ‘[Value Menu]’, enter ‘0’ for ‘italic’. Hit C-x C-s to save.

Time for some more involved configuring. From now on, if something isn’t applicable to your setup, just skip ahead. Also, note that if you’ve installed ERC from GNU ELPA, you may need to load libraries for groups and options you’d like to customize before Emacs can create a customization buffer. For example, to do this for the group erc-sasl, run M-: (require 'erc-sasl) RET.

Speaking of SASL, those already authenticating with it may have noticed that connecting interactively requires running C-u M-x erc-tls RET in order to receive a “User” prompt for your account name. However, if your nickname happens to be the same as your account name, you can avoid the leading C-u by customizing the option erc-sasl-user to the keyword symbol :nick. At the time of writing, you’d hit 2 when prompted by the option’s ‘[Value menu]’. Hit C-x C-s to save your changes.

One of ERC’s most configured options lives in erc-join, and it determines the channels you join upon connecting. To make it work for you, customize the option erc-autojoin-channels-alist. In the customization widget, hit ‘[INS]’ to create a new entry. In the ‘Network:’ field, type ‘Libera.Chat’. Under ‘Channels:’, hit ‘[INS]’ again, this time to create a field to enter a channel name, and enter ‘#emacs’. Now, find and click on the lowermost ‘[INS]’, and this time enter ‘#erc’ in the ‘Name:’ field. Save your changes.

If you’re new to ERC, you may not be familiar with the various ways it can “fill” message text by inserting line breaks. The most modern fill style is called fill-wrap, and it’s available by customizing erc-fill-function to erc-fill-wrap, which appears as ‘Dynamic word-wrap’ in the option’s ‘[Value Menu]’. After setting this, change the related option erc-fill-static-center to the integer ‘18’. Save your changes. As a bonus exercise, try binding the key C-c = to the function erc-fill-wrap-nudge in the minor-mode keymap erc-fill-wrap-mode-map (hint: the minor mode’s hook is called erc-fill-wrap-mode-hook, and it’s not a member of any customization group).

ERC users tend to be picky about the mode line. If you find that you’d rather not see changes when people join and leave channels, customize the option erc-track-faces-priority-list. When visiting its customization buffer, you’ll notice it’s quite busy. Ignore everything and type C-s erc-notice-face RET. Click the ‘[DEL]’ button at the beginning of the line you end up on, and save your changes. Next, customize the related option erc-track-priority-faces-only to the ‘[Value Menu]’ choice ‘all’. Once again, save your changes.

Let’s say you’d like to enable a local module (ERC’s version of a local minor mode) in a specific channel. One way to do that is by running some code to activate the module if the channel’s name matches. Try that now by customizing the option erc-join-hook. Add the following in the value field before saving your changes:

(lambda ()
  (require 'erc-goodies)
  (when (equal (erc-default-target) "#emacs")
    (erc-keep-place-indicator-mode +1)))

Lastly, if you really want the two slash commands defined at the end of the previous section, you can put them in any file listed in erc-startup-file-list, such as ~/.emacs.d/.ercrc.el. Make sure to put (require 'erc-track) near the top of the file. These will allow you to type /TRACK RET and /UNTRACK RET in channels and query buffers to tell ERC whether to show activity from these buffers in the mode line.