1EMACS(1)                              GNU                             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 as‐
23       sumes that you know how to manipulate Emacs windows and buffers.  CTRL-
24       h  or  F1 enters the Help facility.  Help Tutorial (CTRL-h t) starts an
25       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 se‐
28       quence, 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  ap‐
46                      plies 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              --no-x-resources
148                      Do not load X resources.
149
150              -T name, --title=name
151                      Specify the title for the initial X window.
152
153              -r, -rv, --reverse-video
154                      Display the Emacs window in reverse video.
155
156              -fn font, --font=font
157                      Set  the  Emacs window's font to that specified by font.
158                      You   will   find   the   various   X   fonts   in   the
159                      /usr/lib/X11/fonts directory.  Note that Emacs will only
160                      accept fixed width fonts.  Under the X11 Release 4 font-
161                      naming  conventions,  any font with the value "m" or "c"
162                      in the eleventh field of the font name is a fixed  width
163                      font.   Furthermore,  fonts  whose  name are of the form
164                      widthxheight are generally fixed width, as is  the  font
165                      fixed.  See xlsfonts(1) for more information.
166
167                      When  you specify a font, be sure to put a space between
168                      the switch and the font name.
169
170              --xrm=resources
171                      Set additional X resources.
172
173              --color, --color=mode
174                      Override color mode for character  terminals;  mode  de‐
175                      faults  to "auto", and can also be "never", "auto", "al‐
176                      ways", or a mode name like "ansi8".
177
178              -bw pixels, --border-width=pixels
179                      Set the Emacs window's border width  to  the  number  of
180                      pixels  specified  by  pixels.  Defaults to one pixel on
181                      each side of the window.
182
183              -ib pixels, --internal-border=pixels
184                      Set the window's internal border width to the number  of
185                      pixels  specified  by  pixels.  Defaults to one pixel of
186                      padding on each side of the window.
187
188              -g geometry, --geometry=geometry
189                      Set the Emacs window's width, height,  and  position  as
190                      specified.   The  geometry specification is in the stan‐
191                      dard X format; see X(7) for more information.  The width
192                      and  height are specified in characters; the default for
193                      GUI frames is a width of 80 and a height between 35  and
194                      40, depending on the OS and the window manager.  See the
195                      Emacs manual, section "Options for Window Size and Posi‐
196                      tion", for information on how window sizes interact with
197                      selecting or deselecting the tool bar, tab bar and  menu
198                      bar.
199
200              -lsp pixels, --line-spacing=pixels
201                      Additional space to put between lines.
202
203              -vb, --vertical-scroll-bars
204                      Enable vertical scrollbars.
205
206              -fh, --fullheight
207                      Make the first frame as high as the screen.
208
209              -fs, --fullscreen
210                      Make the first frame fullscreen.
211
212              -fw, --fullwidth
213                      Make the first frame as wide as the screen.
214
215              -mm, --maximized
216                      Maximize the first frame, like "-fw -fh".
217
218              -fg color, --foreground-color=color
219                      On color displays, set the color of the text.
220
221                      Use  the  command  M-x list-colors-display for a list of
222                      valid color names.
223
224              -bg color, --background-color=color
225                      On color displays, set the color of the  window's  back‐
226                      ground.
227
228              -bd color, --border-color=color
229                      On color displays, set the color of the window's border.
230
231              -cr color, --cursor-color=color
232                      On  color  displays,  set the color of the window's text
233                      cursor.
234
235              -ms color, --mouse-color=color
236                      On color displays, set the color of the  window's  mouse
237                      cursor.
238
239              -d displayname, --display=displayname
240                      Create the Emacs window on the display specified by dis‐
241                      playname.  Must be the first  option  specified  in  the
242                      command line.
243
244              -nbi, --no-bitmap-icon
245                      Do not use picture of gnu for Emacs icon.
246
247              --iconic
248                      Start Emacs in iconified state.
249
250              -nbc, --no-blinking-cursor
251                      Disable blinking cursor.
252
253              --parent-id=xid
254                      Set parent window.
255
256              -nw, --no-window-system
257                      Tell  Emacs not to create a graphical frame.  If you use
258                      this switch when invoking Emacs from an xterm(1) window,
259                      display is done in that window.
260
261              -D, --basic-display
262                      This  option  disables many display features; use it for
263                      debugging Emacs.
264
265       You can set X default values for your Emacs windows in your .Xresources
266       file (see xrdb(1)).  Use the following format:
267
268              emacs.keyword:value
269
270       where value specifies the default value of keyword.  Emacs lets you set
271       default values for the following keywords:
272
273              background (class Background)
274                      For color displays, sets the window's background color.
275
276              bitmapIcon (class BitmapIcon)
277                      If bitmapIcon's value is set  to  on,  the  window  will
278                      iconify into the "kitchen sink."
279
280              borderColor (class BorderColor)
281                      For  color displays, sets the color of the window's bor‐
282                      der.
283
284              borderWidth (class BorderWidth)
285                      Sets the window's border width in pixels.
286
287              cursorColor (class Foreground)
288                      For color displays, sets the color of the window's  text
289                      cursor.
290
291              cursorBlink (class CursorBlink)
292                      Specifies whether to make the cursor blink.  The default
293                      is on.  Use off or false to turn cursor blinking off.
294
295              font (class Font)
296                      Sets the window's text font.
297
298              foreground (class Foreground)
299                      For color displays, sets the window's text color.
300
301              fullscreen (class Fullscreen)
302                      The desired fullscreen size.  The value can  be  one  of
303                      fullboth,  maximized,  fullwidth,  or  fullheight, which
304                      correspond to the  command-line  options  "-fs",  "-mm",
305                      "-fw",  and "-fh", respectively.  Note that this applies
306                      to the initial frame only.
307
308              geometry (class Geometry)
309                      Sets the geometry of  the  Emacs  window  (as  described
310                      above).
311
312              iconName (class Title)
313                      Sets the icon name for the Emacs window icon.
314
315              internalBorder (class BorderWidth)
316                      Sets the window's internal border width in pixels.
317
318              lineSpacing (class LineSpacing)
319                      Additional space ("leading") between lines, in pixels.
320
321              menuBar (class MenuBar)
322                      Gives  frames  menu  bars if on; don't have menu bars if
323                      off.  See the Emacs manual, sections  "Lucid  Resources"
324                      and "Motif Resources", for how to control the appearance
325                      of the menu bar if you have one.
326
327              minibuffer (class Minibuffer)
328                      If none, don't make a minibuffer in this frame.  It will
329                      use a separate minibuffer frame instead.
330
331              paneFont (class Font)
332                      Font  name for menu pane titles, in non-toolkit versions
333                      of Emacs.
334
335              pointerColor (class Foreground)
336                      For color displays, sets the color of the window's mouse
337                      cursor.
338
339              privateColormap (class PrivateColormap)
340                      If  on,  use  a private color map, in the case where the
341                      "default visual" of class PseudoColor and Emacs is using
342                      it.
343
344              reverseVideo (class ReverseVideo)
345                      If reverseVideo's value is set to on, the window will be
346                      displayed in reverse video.
347
348              screenGamma (class ScreenGamma)
349                      Gamma correction for colors, equivalent to the frame pa‐
350                      rameter "screen-gamma".
351
352              scrollBarWidth (class ScrollBarWidth)
353                      The  scroll bar width in pixels, equivalent to the frame
354                      parameter "scroll-bar-width".
355
356              selectionFont (class SelectionFont)
357                      Font name for pop-up menu items, in non-toolkit versions
358                      of  Emacs.  (For toolkit versions, see the Emacs manual,
359                      sections "Lucid Resources" and "Motif Resources".)
360
361              selectionTimeout (class SelectionTimeout)
362                      Number of milliseconds to wait for a selection reply.  A
363                      value of 0 means wait as long as necessary.
364
365              synchronous (class Synchronous)
366                      Run  Emacs  in synchronous mode if on.  Synchronous mode
367                      is useful for debugging X problems.
368
369              title (class Title)
370                      Sets the title of the Emacs window.
371
372              toolBar (class ToolBar)
373                      Number of lines to reserve for the tool bar.
374
375              tabBar (class TabBar)
376                      Number of lines to reserve for the tab bar.
377
378              useXIM (class UseXIM)
379                      Turns off use of X input methods (XIM) if false or off.
380
381              verticalScrollBars (class ScrollBars)
382                      Gives frames scroll bars if on; suppresses  scroll  bars
383                      if off.
384
385              visualClass (class VisualClass)
386                      Specify  the  "visual"  that X should use.  This tells X
387                      how to handle colors.  The value should start  with  one
388                      of  TrueColor,  PseudoColor,  DirectColor,  StaticColor,
389                      GrayScale, and StaticGray,  followed  by  -depth,  where
390                      depth is the number of color planes.
391

MANUALS

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

FILES

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

BUGS

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

UNRESTRICTIONS

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

SEE ALSO

461       emacsclient(1), etags(1), X(7), xlsfonts(1), xterm(1), xrdb(1)
462

AUTHORS

464       Emacs was written by Richard Stallman and the Free Software Foundation.
465       For detailed credits and acknowledgments, see the GNU Emacs manual.
466

COPYING

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