3 @setfilename ../../info/erc.info
11 This manual is for ERC as distributed with Emacs @value{EMACSVER}.
13 Copyright @copyright{} 2005--2018 Free Software Foundation, Inc.
16 Permission is granted to copy, distribute and/or modify this document
17 under the terms of the GNU Free Documentation License, Version 1.3 or
18 any later version published by the Free Software Foundation; with no
19 Invariant Sections, with the Front-Cover Texts being ``A GNU Manual,''
20 and with the Back-Cover Texts as in (a) below. A copy of the license
21 is included in the section entitled ``GNU Free Documentation License''.
23 (a) The FSF's Back-Cover Text is: ``You have the freedom to copy and
24 modify this GNU manual.''
26 All Emacs Lisp code contained in this document may be used, distributed,
27 and modified without restriction.
31 @dircategory Emacs network features
33 * ERC: (erc). Powerful and extensible IRC client for Emacs.
38 @subtitle a full-featured IRC client
39 @subtitle for Emacs and XEmacs
41 @c The following two commands
42 @c start the copyright page.
44 @vskip 0pt plus 1filll
58 * Introduction:: What is ERC?
59 * Getting Started:: Quick Start guide to using ERC.
60 * Keystroke Summary:: Keystrokes used in ERC buffers.
61 * Modules:: Available modules for ERC.
62 * Advanced Usage:: Cool ways of using ERC.
63 * Getting Help and Reporting Bugs::
64 * History:: The history of ERC.
65 * GNU Free Documentation License:: The license for this documentation.
66 * Concept Index:: Search for terms.
69 --- The Detailed Node Listing ---
73 * Sample Session:: Example of connecting to the #emacs channel
74 * Special Features:: Differences from standalone IRC clients
78 * Connecting:: Ways of connecting to an IRC server.
79 * Sample Configuration:: An example configuration file.
80 * Options:: Options that are available for ERC.
88 ERC is a powerful, modular, and extensible IRC client for Emacs.
89 It is distributed with Emacs since version 22.1.
91 It comes with the following capabilities enabled by default.
96 @item Join channels automatically
97 @item Buttonize URLs, nicknames, and other text
99 @item Highlight or remove IRC control characters
100 @item Highlight pals, fools, and other keywords
101 @item Detect netsplits
102 @item Complete nicknames and commands in a programmable fashion
103 @item Make displayed lines read-only
105 @item Track channel activity in the mode-line
110 @node Getting Started
111 @chapter Getting Started
114 The command @kbd{M-x erc} will start ERC and prompt for the server to
117 If you want to place ERC settings in their own file, you can place them
118 in @file{~/.emacs.d/.ercrc.el}, creating it if necessary.
120 If you would rather use the Customize interface to change how ERC
121 works, do @kbd{M-x customize-group @key{RET} erc @key{RET}}. In
122 particular, ERC comes with lots of modules that may be enabled or
123 disabled; to select which ones you want, do @kbd{M-x
124 customize-variable @key{RET} erc-modules @key{RET}}.
127 * Sample Session:: Example of connecting to the #emacs channel
128 * Special Features:: Differences from standalone IRC clients
132 @section Sample Session
134 This is an example ERC session which shows how to connect to the #emacs
135 channel on Freenode. Another IRC channel on Freenode that may be of
136 interest is #erc, which is a channel where ERC users and developers hang
141 @item Connect to Freenode
143 Run @kbd{M-x erc}. Use ``irc.freenode.net'' as the IRC server, ``6667''
144 as the port, and choose a nickname.
146 @item Get used to the interface
148 Switch to the ``irc.freenode.net:6667'' buffer, if you're not already
149 there. You will see first some messages about checking for ident, and
150 then a bunch of other messages that describe the current IRC server.
152 @item Join the #emacs channel
154 In that buffer, type ``/join @key{SPC} #emacs'' and hit @kbd{RET}. Depending
155 on how you've set up ERC, either a new buffer for ``#emacs'' will be
156 displayed, or a new buffer called ``#emacs'' will be created in the
157 background. If the latter, switch to the ``#emacs'' buffer. You will
158 see the channel topic and a list of the people who are currently on the
161 @item Register your nickname with Freenode
163 If you would like to be able to talk with people privately on the
164 Freenode network, you will have to ``register'' your nickname. To do
165 so, switch to the ``irc.freenode.net:6667'' buffer and type ``/msg
166 NickServ register <password>'', replacing ``<password>'' with your
167 desired password. It should tell you that the operation was successful.
169 @item Talk to people in the channel
171 If you switch back to the ``#emacs'' buffer, you can type a message, and
172 everyone on the channel will see it.
174 @item Open a query buffer to talk to someone
176 If you want to talk with someone in private (this should usually not be
177 done for technical help, only for personal questions), type ``/query
178 <nick>'', replacing ``<nick>'' with the nickname of the person you would
179 like to talk to. Depending on how ERC is set up, you will either see a
180 new buffer with the name of the person, or such a buffer will be created
181 in the background and you will have to switch to it. Begin typing
182 messages, and you will be able to have a conversation.
184 Note that if the other person is not registered, you will not be able to
189 @node Special Features
190 @section Special Features
192 ERC has some features that distinguish it from some IRC clients.
196 @item multiple channels and multiple servers
198 Every channel is put in a separate buffer. Several IRC servers may be
199 connected to at the same time.
201 @cindex query buffers
202 @item private message separation
204 Private conversations are treated as channels, and are put into separate
205 buffers in Emacs. We call these ``query buffers''.
209 Some occurrences of words can be highlighted, which makes it easier to
210 track different kinds of conversations.
214 ERC can notify you that certain users are online.
216 @item channel tracking
218 Channels can be hidden and conversation continue in the background. You
219 are notified when something is said in such a channel that is not
220 currently visible. This makes it easy to get Real Work done while still
221 maintaining an IRC presence.
223 @item nick completion
225 ERC can complete words upon hitting @kbd{TAB}, which eases the writing
226 of nicknames in messages.
231 Past actions are kept in history rings for future use. To navigate a
232 history ring, hit @kbd{M-p} to go backwards and @kbd{M-n} to go
235 @item multiple languages
237 Different channels and servers may have different language encodings.
239 multiple languages. Please contact the Emacs developers
240 if you are interested in helping with the
245 Users can load scripts (e.g., auto greeting scripts) when ERC starts up.
247 It is also possible to make custom IRC commands, if you know a little
248 Emacs Lisp. Just make an Emacs Lisp function and call it
249 @code{erc-cmd-NEWCOMMAND}, where @code{NEWCOMMAND} is the name of the
250 new command in capital letters.
254 If the connection goes away at some point, ERC will try to reconnect
255 automatically. If it fails to reconnect, and you want to try to
256 manually reestablish the connection at some later point, switch to an
257 ERC buffer and run the @code{/RECONNECT} command.
262 @node Keystroke Summary
263 @chapter Keys Used in ERC
266 This is a summary of keystrokes available in every ERC buffer.
270 @item C-a or <home> (@code{erc-bol})
271 Go to beginning of line or end of prompt.
273 @item @key{RET} (@code{erc-send-current-line})
274 Send the current line
276 @item @key{TAB} (@code{erc-complete-word})
277 If at prompt, complete the current word.
278 Otherwise, move to the next link or button.
280 @item M-@key{TAB} (@code{ispell-complete-word})
281 Complete the given word, using ispell.
283 @item C-c C-a (@code{erc-bol})
284 Go to beginning of line or end of prompt.
286 @item C-c C-b (@code{erc-iswitchb})
287 Use @code{iswitchb-read-buffer} to prompt for a ERC buffer to switch to.
289 @item C-c C-c (@code{erc-toggle-interpret-controls})
290 Toggle interpretation of control sequences in messages.
292 @item C-c C-d (@code{erc-input-action})
293 Interactively input a user action and send it to IRC.
295 @item C-c C-e (@code{erc-toggle-ctcp-autoresponse})
296 Toggle automatic CTCP replies (like VERSION and PING).
298 @item C-c C-f (@code{erc-toggle-flood-control})
299 Toggle use of flood control on sent messages.
301 @item C-c @key{TAB} (@code{erc-invite-only-mode})
302 Turn on the invite only mode (+i) for the current channel.
304 @item C-c C-j (@code{erc-join-channel})
305 Join channel. If point is at the beginning of a channel name, use that
308 @item C-c C-k (@code{erc-go-to-log-matches-buffer})
309 Interactively open an erc-log-matches buffer
311 @item C-c C-l (@code{erc-save-buffer-in-logs})
312 Append buffer contents to the log file, if logging is enabled.
314 @item C-c C-n (@code{erc-channel-names})
315 Run "/names #channel" in the current channel.
317 @item C-c C-o (@code{erc-get-channel-mode-from-keypress})
318 Read a key sequence and call the corresponding channel mode function.
319 After doing @kbd{C-c C-o}, type in a channel mode letter.
321 @kbd{C-g} means quit.
322 @kbd{RET} lets you type more than one mode at a time.
323 If @kbd{l} is pressed, @code{erc-set-channel-limit} gets called.
324 If @kbd{k} is pressed, @code{erc-set-channel-key} gets called.
325 Anything else will be sent to @code{erc-toggle-channel-mode}.
327 @item C-c C-p (@code{erc-part-from-channel})
328 Part from the current channel and prompt for a reason.
330 @item C-c C-q (@code{erc-quit-server})
331 Disconnect from current server after prompting for reason.
333 @item C-c C-r (@code{erc-remove-text-properties-region})
334 Clears the region (start,end) in object from all colors, etc.
336 @item C-c C-t (@code{erc-set-topic})
337 Prompt for a topic for the current channel.
339 @item C-c C-u (@code{erc-kill-input})
340 Kill current input line using @code{erc-bol} followed by @code{kill-line}.
349 One way to add functionality to ERC is to customize which of its many
352 There is a spiffy customize interface, which may be reached by typing
353 @kbd{M-x customize-option @key{RET} erc-modules @key{RET}}.
354 Alternatively, set @code{erc-modules} manually and then call
355 @code{erc-update-modules}.
357 The following is a list of available modules.
361 @cindex modules, autoaway
363 Set away status automatically
365 @cindex modules, autojoin
367 Join channels automatically
369 @cindex modules, bbdb
371 Integrate with the Big Brother Database
373 @cindex modules, button
375 Buttonize URLs, nicknames, and other text
377 @cindex modules, capab-identify
379 Mark unidentified users on freenode and other servers supporting CAPAB.
381 @cindex modules, completion
382 @cindex modules, pcomplete
383 @item completion (aka pcomplete)
384 Complete nicknames and commands (programmable)
386 @cindex modules, fill
390 @cindex modules, identd
392 Launch an identd server on port 8113
394 @cindex modules, irccontrols
396 Highlight or remove IRC control characters
402 @cindex modules, match
404 Highlight pals, fools, and other keywords
406 @cindex modules, menu
408 Display a menu in ERC buffers
410 @cindex modules, netsplit
414 @cindex modules, noncommands
416 Don't display non-IRC commands after evaluation
418 @cindex modules, notify
420 Notify when the online status of certain users changes
422 @cindex modules, notifications
424 Send you a notification when you get a private message,
425 or your nickname is mentioned
427 @cindex modules, page
429 Process CTCP PAGE requests from IRC
431 @cindex modules, readonly
433 Make displayed lines read-only
435 @cindex modules, replace
437 Replace text in messages
439 @cindex modules, ring
441 Enable an input history
443 @cindex modules, scrolltobottom
445 Scroll to the bottom of the buffer
447 @cindex modules, services
449 Identify to Nickserv (IRC Services) automatically
451 @cindex modules, smiley
453 Convert smileys to pretty icons
455 @cindex modules, sound
457 Play sounds when you receive CTCP SOUND requests
459 @cindex modules, spelling
461 Check spelling of messages
463 @cindex modules, stamp
465 Add timestamps to messages
467 @cindex modules, track
469 Track channel activity in the mode-line
471 @cindex modules, truncate
473 Truncate buffers to a certain size
475 @cindex modules, unmorse
477 Translate morse code in messages
481 @c PRE5_4: Document every option of every module in its own subnode
485 @chapter Advanced Usage
486 @cindex advanced topics
489 * Connecting:: Ways of connecting to an IRC server.
490 * Sample Configuration:: An example configuration file.
491 * Options:: Options that are available for ERC.
495 @section Connecting to an IRC Server
498 The easiest way to connect to an IRC server is to call @kbd{M-x erc}.
499 If you want to assign this function to a keystroke, the following will
500 help you figure out its parameters.
503 Select connection parameters and run ERC@.
504 Non-interactively, it takes the following keyword arguments.
511 @item @var{full-name}
514 That is, if called with the following arguments, @var{server} and
515 @var{full-name} will be set to those values, whereas
516 @code{erc-compute-port}, @code{erc-compute-nick} and
517 @code{erc-compute-full-name} will be invoked for the values of the other
521 (erc :server "irc.freenode.net" :full-name "Harry S Truman")
527 @defun erc-compute-server &optional server
528 Return an IRC server name.
530 This tries a number of increasingly more default methods until a non-@code{nil}
534 @item @var{server} (the argument passed to this function)
535 @item The @code{erc-server} option
536 @item The value of the IRCSERVER environment variable
537 @item The @code{erc-default-server} variable
543 IRC server to use if one is not provided.
548 @defun erc-compute-port &optional port
549 Return a port for an IRC server.
551 This tries a number of increasingly more default methods until a non-@code{nil}
555 @item @var{port} (the argument passed to this function)
556 @item The @code{erc-port} option
557 @item The @code{erc-default-port} variable
563 IRC port to use if not specified.
565 This can be either a string or a number.
570 @defun erc-compute-nick &optional nick
571 Return user's IRC nick.
573 This tries a number of increasingly more default methods until a
574 non-@code{nil} value is found.
577 @item @var{nick} (the argument passed to this function)
578 @item The @code{erc-nick} option
579 @item The value of the IRCNICK environment variable
580 @item The result from the @code{user-login-name} function
586 Nickname to use if one is not provided.
588 This can be either a string, or a list of strings.
589 In the latter case, if the first nick in the list is already in use,
590 other nicks are tried in the list order.
593 @defopt erc-format-nick-function
594 A function to format a nickname for message display
596 You can set this to @code{erc-format-@@nick} to display user mode prefix
600 (setq erc-format-nick-function 'erc-format-@@nick)
603 @defopt erc-nick-uniquifier
604 The string to append to the nick if it is already in use.
607 @defopt erc-try-new-nick-p
608 If the nickname you chose isn't available, and this option is non-@code{nil},
609 ERC should automatically attempt to connect with another nickname.
611 You can manually set another nickname with the /NICK command.
617 @defopt erc-prompt-for-password
618 If non-@code{nil} (the default), @kbd{M-x erc} prompts for a password.
621 If you prefer, you can set this option to @code{nil} and use the
622 @code{auth-source} mechanism to store your password. For instance, if
623 you use @file{~/.authinfo} as your auth-source backend, then put
624 something like the following in that file:
627 machine irc.example.net login "#fsf" password sEcReT
631 ERC also consults @code{auth-source} to find any channel keys required
632 for the channels that you wish to autojoin, as specified by the
633 variable @code{erc-autojoin-channels-alist}.
635 For more details, @pxref{Top,,auth-source, auth, Emacs auth-source Library}.
638 @subheading Full name
640 @defun erc-compute-full-name &optional full-name
641 Return user's full name.
643 This tries a number of increasingly more default methods until a
644 non-@code{nil} value is found.
647 @item @var{full-name} (the argument passed to this function)
648 @item The @code{erc-user-full-name} option
649 @item The value of the IRCNAME environment variable
650 @item The result from the @code{user-full-name} function
655 @defopt erc-user-full-name
658 This can be either a string or a function to call.
661 @node Sample Configuration
662 @section Sample Configuration
663 @cindex configuration, sample
665 Here is an example of configuration settings for ERC@. This can go into
666 your Emacs configuration file. Everything after the @code{(require
667 'erc)} command can optionally go into @file{~/.emacs.d/.ercrc.el}.
670 ;;; Sample ERC configuration
672 ;; Load authentication info from an external source. Put sensitive
673 ;; passwords and the like in here.
674 (load "~/.emacs.d/.erc-auth")
676 ;; This is an example of how to make a new command. Type "/uptime" to
678 (defun erc-cmd-UPTIME (&rest ignore)
679 "Display the uptime of the system, as well as some load-related
680 stuff, to the current ERC buffer."
682 (replace-regexp-in-string
683 ", load average: " "] @{Load average@} ["
684 ;; Collapse spaces, remove
685 (replace-regexp-in-string
687 ;; Remove beginning and trailing whitespace
688 (replace-regexp-in-string
690 (shell-command-to-string "uptime"))))))
692 (concat "@{Uptime@} [" uname-output "]"))))
694 ;; This causes ERC to connect to the Freenode network upon hitting
695 ;; C-c e f. Replace MYNICK with your IRC nick.
696 (global-set-key "\C-cef" (lambda () (interactive)
697 (erc :server "irc.freenode.net" :port "6667"
700 ;; This causes ERC to connect to the IRC server on your own machine (if
701 ;; you have one) upon hitting C-c e b. Replace MYNICK with your IRC
702 ;; nick. Often, people like to run bitlbee (http://bitlbee.org/) as an
703 ;; AIM/Jabber/MSN to IRC gateway, so that they can use ERC to chat with
704 ;; people on those networks.
705 (global-set-key "\C-ceb" (lambda () (interactive)
706 (erc :server "localhost" :port "6667"
709 ;; Make C-c RET (or C-c C-RET) send messages instead of RET. This has
710 ;; been commented out to avoid confusing new users.
711 ;; (define-key erc-mode-map (kbd "RET") nil)
712 ;; (define-key erc-mode-map (kbd "C-c RET") 'erc-send-current-line)
713 ;; (define-key erc-mode-map (kbd "C-c C-RET") 'erc-send-current-line)
717 ;; Join the #emacs and #erc channels whenever connecting to Freenode.
718 (setq erc-autojoin-channels-alist '(("freenode.net" "#emacs" "#erc")))
720 ;; Rename server buffers to reflect the current network name instead
721 ;; of SERVER:PORT (e.g., "freenode" instead of "irc.freenode.net:6667").
722 ;; This is useful when using a bouncer like ZNC where you have multiple
723 ;; connections to the same server.
724 (setq erc-rename-buffers t)
726 ;; Interpret mIRC-style color commands in IRC chats
727 (setq erc-interpret-mirc-color t)
729 ;; The following are commented out by default, but users of other
730 ;; non-Emacs IRC clients might find them useful.
731 ;; Kill buffers for channels after /part
732 ;; (setq erc-kill-buffer-on-part t)
733 ;; Kill buffers for private queries after quitting the server
734 ;; (setq erc-kill-queries-on-quit t)
735 ;; Kill buffers for server messages after quitting the server
736 ;; (setq erc-kill-server-buffer-on-quit t)
743 @c PRE5_4: (Node) Document every ERC option (module options go in
746 This section is extremely incomplete. For now, the easiest way to
747 check out all the available options for ERC is to do
748 @kbd{M-x customize-group @key{RET} erc @key{RET}}.
750 @defopt erc-hide-list
751 If non, @code{nil}, this is a list of IRC message types to hide, e.g.:
754 (setq erc-hide-list '("JOIN" "PART" "QUIT"))
758 @defopt erc-network-hide-list
759 If non, @code{nil}, this is a list of IRC networks and message types
763 (setq erc-network-hide-list (("freenode" "JOIN" "PART" "QUIT")
764 ("OFTC" "JOIN" "PART""))
768 @defopt erc-channel-hide-list
769 If non, @code{nil}, this is a list of IRC channels and message types
773 (setq erc-channel-hide-list (("#erc" "JOIN" "PART" "QUIT")
778 @defopt erc-lurker-hide-list
779 Like @code{erc-hide-list}, but only applies to messages sent by
780 lurkers. The function @code{erc-lurker-p} determines whether a given
781 nickname is considered a lurker.
784 @defopt erc-rename-buffers
785 If non, @code{nil}, this will rename server buffers to reflect the
786 current network name instead of IP:PORT
789 (setq erc-rename-buffers t)
793 @node Getting Help and Reporting Bugs
794 @chapter Getting Help and Reporting Bugs
795 @cindex help, getting
796 @cindex bugs, reporting
798 After you have read this guide, if you still have questions about ERC,
799 or if you have bugs to report, there are several places you can go.
804 @uref{http://www.emacswiki.org/cgi-bin/wiki/ERC} is the
805 emacswiki.org page for ERC@. Anyone may add tips, hints, etc.@: to it.
808 You can ask questions about using ERC on the Emacs mailing list,
809 @uref{https://lists.gnu.org/mailman/listinfo/help-gnu-emacs}.
812 You can visit the IRC Freenode channel @samp{#emacs}. Many of the
813 contributors are frequently around and willing to answer your
817 To report a bug in ERC, use @kbd{M-x report-emacs-bug}.
824 @cindex history, of ERC
826 @c abel@@bfr.co.il, sergey.berezin@@cs.cmu.edu
827 ERC was originally written by Alexander L. Belikoff and Sergey Berezin.
828 They stopped development around
829 December 1999. Their last released version was ERC 2.0.
831 P.S.: If one of the original developers of ERC reads this, we'd like to
832 receive additional information for this file and hear comments in
838 @c mlang@@delysid.org, alex@@gnu.org
839 In June 2001, Mario Lang and Alex Schroeder
840 took over development and created a ERC Project at
841 @uref{http://sourceforge.net/projects/erc}.
843 In reaction to a mail about the new ERC development effort, Sergey
844 Berezin said, ``First of all, I'm glad that my version of ERC is being
845 used out there. The thing is, I do not have free time and enough
846 incentive anymore to work on ERC, so I would be happy if you guys take
847 over the project entirely.''
849 So we happily hacked away on ERC, and soon after (September 2001)
850 released the next "stable" version, 2.1.
852 Most of the development of the new ERC happened on #emacs on
853 irc.openprojects.net. Over time, many people contributed code, ideas,
854 bugfixes, and a lot of alpha/beta/gamma testing.
856 See the @file{CREDITS} file for a list of contributors.
860 ERC 3.0 was released.
864 ERC 4.0 was released.
869 ERC 5.0 was released. Michael Olson became
870 the release manager and eventually the maintainer.
872 After some discussion between him and the Emacs developers, it was
873 decided to include ERC in Emacs.
877 ERC 5.1 was released. It was subsequently included in Emacs 22.
879 ERC became an official GNU project, and development moved to
880 @uref{https://sv.gnu.org/projects/erc}. We switched to using GNU Arch as
881 our revision control system. Our mailing list address changed as well.
885 We switched to using git for our version control system.
889 Since about 2009, ERC is no longer developed as a separate project, but
890 is maintained as part of Emacs.
894 @node GNU Free Documentation License
895 @appendix GNU Free Documentation License
896 @include doclicense.texi