1EMACS(1)                    General Commands Manual                   EMACS(1)
2
3
4

NAME

6       emacs - GNU project Emacs editor
7

SYNOPSIS

9       emacs [ command-line switches ] [ files ... ]
10

DESCRIPTION

12       GNU  Emacs is a version of Emacs, written by the author of the original
13       (PDP-10) Emacs, Richard Stallman.  The user functionality of GNU  Emacs
14       encompasses  everything  other  editors do, and it is easily extensible
15       since its editing commands are written in Lisp.
16
17       The primary documentation of GNU Emacs is  in  the  GNU  Emacs  Manual,
18       which  you  can  read  using Info, either from Emacs or as a standalone
19       program.  Please look there for complete and up-to-date  documentation.
20       This man page is updated only when someone volunteers to do so.
21
22       Emacs  has  an  extensive  interactive  help facility, but the facility
23       assumes that you know how to  manipulate  Emacs  windows  and  buffers.
24       CTRL-h or F1 enters the Help facility.  Help Tutorial (CTRL-h t) starts
25       an interactive tutorial to quickly teach beginners the fundamentals  of
26       Emacs.   Help  Apropos  (CTRL-h a) helps you find a command with a name
27       matching a given pattern, Help Key (CTRL-h k)  describes  a  given  key
28       sequence, and Help Function (CTRL-h f) describes a given Lisp function.
29
30       GNU Emacs's many special packages handle mail reading (RMail) and send‐
31       ing (Mail), outline editing  (Outline),  compiling  (Compile),  running
32       subshells  within Emacs windows (Shell), running a Lisp read-eval-print
33       loop (Lisp-Interaction-Mode),  automated  psychotherapy  (Doctor),  and
34       much more.
35
36   Emacs Options
37       The following options are of general interest:
38
39              file    Edit file.
40
41              --file=file, --find-file=file, --visit=file
42                      The same as specifying file directly as an argument.
43
44              +number Go  to  the  line  specified  by number (do not insert a
45                      space between  the  "+"  sign  and  the  number).   This
46                      applies only to the next file specified.
47
48              +line:column
49                      Go to the specified line and column.
50
51              --chdir=directory
52                      Change to directory.
53
54              -q, --no-init-file
55                      Do not load an init file.
56
57              -nl, --no-shared-memory
58                      Do not use shared memory.
59
60              --no-site-file
61                      Do not load the site-wide startup file.
62
63              -nsl, --no-site-lisp
64                      Do not add site-lisp directories to load-path.
65
66              --no-desktop
67                      Do not load a saved desktop.
68
69              -Q, --quick
70                      Similar to "-q --no-site-file --no-splash".  Also, avoid
71                      processing X resources.
72
73              --no-splash
74                      Do not display a splash screen during start-up.
75
76              --debug-init
77                      Enable Emacs Lisp debugger during the processing of  the
78                      user  init  file ~/.emacs.  This is useful for debugging
79                      problems in the init file.
80
81              -u user, --user=user
82                      Load user's init file.
83
84              -t file, --terminal=file
85                      Use specified file as  the  terminal  instead  of  using
86                      stdin/stdout.  This must be the first argument specified
87                      in the command line.
88
89              --daemon[=name], --bg-daemon[=name]
90                      Start Emacs as a daemon, enabling the Emacs  server  and
91                      disconnecting  from  the terminal.  You can then use the
92                      emacsclient (see emacsclient(1)) command to  connect  to
93                      the server (with optional name).
94
95              --fg-daemon[=name]
96                      Like "--bg-daemon", but don't disconnect from the termi‐
97                      nal.
98
99              --version
100                      Display Emacs version information and exit.
101
102              --help  Display this help and exit.
103
104       The following options are Lisp-oriented (these options are processed in
105       the order encountered):
106
107              -f function, --funcall=function
108                      Execute the lisp function function.
109
110              -l file, --load=file
111                      Load the lisp code in the file file.
112
113              --eval=expr, --execute=expr
114                      Evaluate the Lisp expression expr.
115
116       The following options are useful when running Emacs as a batch editor:
117
118              --batch Edit  in  batch  mode.  The editor will send messages to
119                      stderr.  You must use -l and -f options to specify files
120                      to execute and functions to call.
121
122              --script file
123                      Run file as an Emacs Lisp script.
124
125              --insert=file
126                      Insert contents of file into the current buffer.
127
128              --kill  Exit Emacs while in batch mode.
129
130              -L dir, --directory=dir
131                      Add  dir  to  the list of directories Emacs searches for
132                      Lisp files.
133
134   Using Emacs with X
135       Emacs has been tailored to work well with the X window system.  If  you
136       run Emacs from under X windows, it will create its own X window to dis‐
137       play in.  You will probably want to start the editor  as  a  background
138       process so that you can continue using your original window.
139
140       Emacs can be started with the following X switches:
141
142              --name=name
143                      Specify the name which should be assigned to the initial
144                      Emacs window.  This controls looking up X  resources  as
145                      well as the window title.
146
147              -T name, --title=name
148                      Specify the title for the initial X window.
149
150              -r, -rv, --reverse-video
151                      Display the Emacs window in reverse video.
152
153              -fn font, --font=font
154                      Set  the  Emacs window's font to that specified by font.
155                      You   will   find   the   various   X   fonts   in   the
156                      /usr/lib/X11/fonts directory.  Note that Emacs will only
157                      accept fixed width fonts.  Under the X11 Release 4 font-
158                      naming  conventions,  any font with the value "m" or "c"
159                      in the eleventh field of the font name is a fixed  width
160                      font.   Furthermore,  fonts  whose  name are of the form
161                      widthxheight are generally fixed width, as is  the  font
162                      fixed.  See xlsfonts(1) for more information.
163
164                      When  you specify a font, be sure to put a space between
165                      the switch and the font name.
166
167              --xrm=resources
168                      Set additional X resources.
169
170              --color, --color=mode
171                      Override  color  mode  for  character  terminals;   mode
172                      defaults  to  "auto",  and  can also be "never", "auto",
173                      "always", or a mode name like "ansi8".
174
175              -bw pixels, --border-width=pixels
176                      Set the Emacs window's border width  to  the  number  of
177                      pixels  specified  by  pixels.  Defaults to one pixel on
178                      each side of the window.
179
180              -ib pixels, --internal-border=pixels
181                      Set the window's internal border width to the number  of
182                      pixels  specified  by  pixels.  Defaults to one pixel of
183                      padding on each side of the window.
184
185              -g geometry, --geometry=geometry
186                      Set the Emacs window's width, height,  and  position  as
187                      specified.   The  geometry specification is in the stan‐
188                      dard X format; see X(7) for more information.  The width
189                      and  height are specified in characters; the default for
190                      GUI frames is a width of 80 and a height between 35  and
191                      40, depending on the OS and the window manager.  See the
192                      Emacs manual, section "Options for Window Size and Posi‐
193                      tion", for information on how window sizes interact with
194                      selecting or deselecting the tool bar, tab bar and  menu
195                      bar.
196
197              -lsp pixels, --line-spacing=pixels
198                      Additional space to put between lines.
199
200              -vb, --vertical-scroll-bars
201                      Enable vertical scrollbars.
202
203              -fh, --fullheight
204                      Make the first frame as high as the screen.
205
206              -fs, --fullscreen
207                      Make the first frame fullscreen.
208
209              -fw, --fullwidth
210                      Make the first frame as wide as the screen.
211
212              -mm, --maximized
213                      Maximize the first frame, like "-fw -fh".
214
215              -fg color, --foreground-color=color
216                      On color displays, set the color of the text.
217
218                      Use  the  command  M-x list-colors-display for a list of
219                      valid color names.
220
221              -bg color, --background-color=color
222                      On color displays, set the color of the  window's  back‐
223                      ground.
224
225              -bd color, --border-color=color
226                      On color displays, set the color of the window's border.
227
228              -cr color, --cursor-color=color
229                      On  color  displays,  set the color of the window's text
230                      cursor.
231
232              -ms color, --mouse-color=color
233                      On color displays, set the color of the  window's  mouse
234                      cursor.
235
236              -d displayname, --display=displayname
237                      Create the Emacs window on the display specified by dis‐
238                      playname.  Must be the first  option  specified  in  the
239                      command line.
240
241              -nbi, --no-bitmap-icon
242                      Do not use picture of gnu for Emacs icon.
243
244              --iconic
245                      Start Emacs in iconified state.
246
247              -nbc, --no-blinking-cursor
248                      Disable blinking cursor.
249
250              --parent-id=xid
251                      Set parent window.
252
253              -nw, --no-window-system
254                      Tell  Emacs not to create a graphical frame.  If you use
255                      this switch when invoking Emacs from an xterm(1) window,
256                      display is done in that window.
257
258              -D, --basic-display
259                      This  option  disables many display features; use it for
260                      debugging Emacs.
261
262       You can set X default values for your Emacs windows in your .Xresources
263       file (see xrdb(1)).  Use the following format:
264
265              emacs.keyword:value
266
267       where value specifies the default value of keyword.  Emacs lets you set
268       default values for the following keywords:
269
270              background (class Background)
271                      For color displays, sets the window's background color.
272
273              bitmapIcon (class BitmapIcon)
274                      If bitmapIcon's value is set  to  on,  the  window  will
275                      iconify into the "kitchen sink."
276
277              borderColor (class BorderColor)
278                      For  color displays, sets the color of the window's bor‐
279                      der.
280
281              borderWidth (class BorderWidth)
282                      Sets the window's border width in pixels.
283
284              cursorColor (class Foreground)
285                      For color displays, sets the color of the window's  text
286                      cursor.
287
288              cursorBlink (class CursorBlink)
289                      Specifies whether to make the cursor blink.  The default
290                      is on.  Use off or false to turn cursor blinking off.
291
292              font (class Font)
293                      Sets the window's text font.
294
295              foreground (class Foreground)
296                      For color displays, sets the window's text color.
297
298              fullscreen (class Fullscreen)
299                      The desired fullscreen size.  The value can  be  one  of
300                      fullboth,  maximized,  fullwidth,  or  fullheight, which
301                      correspond to the  command-line  options  "-fs",  "-mm",
302                      "-fw",  and "-fh", respectively.  Note that this applies
303                      to the initial frame only.
304
305              geometry (class Geometry)
306                      Sets the geometry of  the  Emacs  window  (as  described
307                      above).
308
309              iconName (class Title)
310                      Sets the icon name for the Emacs window icon.
311
312              internalBorder (class BorderWidth)
313                      Sets the window's internal border width in pixels.
314
315              lineSpacing (class LineSpacing)
316                      Additional space ("leading") between lines, in pixels.
317
318              menuBar (class MenuBar)
319                      Gives  frames  menu  bars if on; don't have menu bars if
320                      off.  See the Emacs manual, sections  "Lucid  Resources"
321                      and "Motif Resources", for how to control the appearance
322                      of the menu bar if you have one.
323
324              minibuffer (class Minibuffer)
325                      If none, don't make a minibuffer in this frame.  It will
326                      use a separate minibuffer frame instead.
327
328              paneFont (class Font)
329                      Font  name for menu pane titles, in non-toolkit versions
330                      of Emacs.
331
332              pointerColor (class Foreground)
333                      For color displays, sets the color of the window's mouse
334                      cursor.
335
336              privateColormap (class PrivateColormap)
337                      If  on,  use  a private color map, in the case where the
338                      "default visual" of class PseudoColor and Emacs is using
339                      it.
340
341              reverseVideo (class ReverseVideo)
342                      If reverseVideo's value is set to on, the window will be
343                      displayed in reverse video.
344
345              screenGamma (class ScreenGamma)
346                      Gamma correction for colors,  equivalent  to  the  frame
347                      parameter "screen-gamma".
348
349              scrollBarWidth (class ScrollBarWidth)
350                      The  scroll bar width in pixels, equivalent to the frame
351                      parameter "scroll-bar-width".
352
353              selectionFont (class SelectionFont)
354                      Font name for pop-up menu items, in non-toolkit versions
355                      of  Emacs.  (For toolkit versions, see the Emacs manual,
356                      sections "Lucid Resources" and "Motif Resources".)
357
358              selectionTimeout (class SelectionTimeout)
359                      Number of milliseconds to wait for a selection reply.  A
360                      value of 0 means wait as long as necessary.
361
362              synchronous (class Synchronous)
363                      Run  Emacs  in synchronous mode if on.  Synchronous mode
364                      is useful for debugging X problems.
365
366              title (class Title)
367                      Sets the title of the Emacs window.
368
369              toolBar (class ToolBar)
370                      Number of lines to reserve for the tool bar.
371
372              tabBar (class TabBar)
373                      Number of lines to reserve for the tab bar.
374
375              useXIM (class UseXIM)
376                      Turns off use of X input methods (XIM) if false or off.
377
378              verticalScrollBars (class ScrollBars)
379                      Gives frames scroll bars if on; suppresses  scroll  bars
380                      if off.
381
382              visualClass (class VisualClass)
383                      Specify  the  "visual"  that X should use.  This tells X
384                      how to handle colors.  The value should start  with  one
385                      of  TrueColor,  PseudoColor,  DirectColor,  StaticColor,
386                      GrayScale, and StaticGray,  followed  by  -depth,  where
387                      depth is the number of color planes.
388

MANUALS

390       You  can  order  printed  copies  of the GNU Emacs Manual from the Free
391       Software Foundation, which develops GNU software.  See the online store
392       at <https://shop.fsf.org/>.
393       Your local administrator might also have copies available.  As with all
394       software and publications from FSF, everyone is permitted to  make  and
395       distribute  copies of the Emacs manual.  The Texinfo source to the man‐
396       ual is also included in the Emacs source distribution.
397

FILES

399       /usr/local/share/info — files for the Info documentation browser.   The
400       complete text of the Emacs reference manual is included in a convenient
401       tree structured form.  Also includes the Emacs Lisp  Reference  Manual,
402       useful  to anyone wishing to write programs in the Emacs Lisp extension
403       language, and the Introduction to Programming in Emacs Lisp.
404
405       /usr/local/share/emacs/$VERSION/lisp — Lisp source files  and  compiled
406       files  that  define  most editing commands.  Some are preloaded; others
407       are autoloaded from this directory when used.
408
409       /usr/local/libexec/emacs/$VERSION/$ARCH —  various  programs  that  are
410       used with GNU Emacs.
411
412       /usr/local/share/emacs/$VERSION/etc — various files of information.
413
414       /usr/local/share/emacs/$VERSION/etc/DOC.*  — contains the documentation
415       strings for the Lisp primitives and preloaded  Lisp  functions  of  GNU
416       Emacs.  They are stored here to reduce the size of Emacs proper.
417
418

BUGS

420       There  is  a  mailing  list, bug-gnu-emacs@gnu.org, for reporting Emacs
421       bugs and fixes.  But before reporting something as a bug, please try to
422       be sure that it really is a bug, not a misunderstanding or a deliberate
423       feature.  We ask you to read the section "Reporting Bugs" in the  Emacs
424       manual  for  hints  on  how and when to report bugs.  Also, include the
425       version number of the Emacs you are running in every  bug  report  that
426       you  send  in.  Bugs tend actually to be fixed if they can be isolated,
427       so it is in your interest to report them in such a way that they can be
428       easily reproduced.
429
430       Do  not  expect  a  personal  answer  to  a bug report.  The purpose of
431       reporting bugs is to get them fixed for everyone in the  next  release,
432       if possible.  For personal assistance, consult the service directory at
433       <https://www.fsf.org/resources/service/> for a list of people who offer
434       it.
435
436       Please  do not send anything but bug reports to this mailing list.  For
437       other Emacs lists, see <https://savannah.gnu.org/mail/?group=emacs>.
438

UNRESTRICTIONS

440       Emacs is free; anyone may redistribute copies of Emacs to anyone  under
441       the  terms  stated  in  the GNU General Public License, a copy of which
442       accompanies each copy of Emacs and which also appears in the  reference
443       manual.
444
445       Copies  of  Emacs may sometimes be received packaged with distributions
446       of Unix systems, but it is never included in the scope of  any  license
447       covering  those  systems.   Such  inclusion violates the terms on which
448       distribution is permitted.  In fact, the primary  purpose  of  the  GNU
449       General  Public  License is to prohibit anyone from attaching any other
450       restrictions to redistribution of Emacs.
451
452       Richard Stallman encourages you to improve and extend Emacs, and  urges
453       that you contribute your extensions to the GNU library.  Eventually GNU
454       (Gnu's Not Unix) will be a complete  replacement  for  Unix.   Everyone
455       will be free to use, copy, study and change the GNU system.
456

SEE ALSO

458       emacsclient(1), etags(1), X(7), xlsfonts(1), xterm(1), xrdb(1)
459

AUTHORS

461       Emacs was written by Richard Stallman and the Free Software Foundation.
462       For detailed credits and acknowledgments, see the GNU Emacs manual.
463

COPYING

465       Copyright 1995, 1999-2021 Free Software Foundation, Inc.
466
467       Permission is granted to make and distribute verbatim  copies  of  this
468       document  provided  the copyright notice and this permission notice are
469       preserved on all copies.
470
471       Permission is granted to copy and distribute modified versions of  this
472       document  under  the conditions for verbatim copying, provided that the
473       entire resulting derived work is distributed under the terms of a  per‐
474       mission notice identical to this one.
475
476       Permission is granted to copy and distribute translations of this docu‐
477       ment into another language, under the  above  conditions  for  modified
478       versions,  except that this permission notice may be stated in a trans‐
479       lation approved by the Free Software Foundation.
480
481
482
483
484GNU Emacs 27.2                   2007 April 13                        EMACS(1)
Impressum