misc.texi 102 KB
Newer Older
Dave Love's avatar
#  
Dave Love committed
1
@c This is part of the Emacs manual.
2
@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2012
Glenn Morris's avatar
Glenn Morris committed
3
@c   Free Software Foundation, Inc.
Dave Love's avatar
#  
Dave Love committed
4 5 6 7 8
@c See file emacs.texi for copying conditions.
@iftex
@chapter Miscellaneous Commands

  This chapter contains several brief topics that do not fit anywhere
9
else: viewing ``document files'', reading Usenet news, running shell
10 11 12
commands and shell subprocesses, using a single shared Emacs for
utilities that expect to run an editor as a subprocess, printing
hardcopy, sorting text, narrowing display to part of the buffer,
13 14 15
editing binary files, saving an Emacs session for later resumption,
following hyperlinks, browsing images, emulating other editors, and
various diversions and amusements.
Dave Love's avatar
#  
Dave Love committed
16 17

@end iftex
18 19 20 21 22

@ifnottex
@raisesections
@end ifnottex

23
@node Gnus
Dave Love's avatar
#  
Dave Love committed
24 25
@section Gnus
@cindex Gnus
26 27
@cindex Usenet news
@cindex newsreader
Dave Love's avatar
#  
Dave Love committed
28

29 30 31 32
  Gnus is an Emacs package primarily designed for reading and posting
Usenet news.  It can also be used to read and respond to messages from
a number of other sources---email, remote directories, digests, and so
on.  Here we introduce Gnus and describe several basic features.
33
@ifnottex
Dave Love's avatar
#  
Dave Love committed
34
For full details, see @ref{Top, Gnus,, gnus, The Gnus Manual}.
35
@end ifnottex
Dave Love's avatar
#  
Dave Love committed
36
@iftex
37
For full details on Gnus, type @kbd{C-h i} and then select the Gnus
Dave Love's avatar
#  
Dave Love committed
38 39 40 41
manual.
@end iftex

@menu
42 43
* Buffers of Gnus::     The group, summary, and article buffers.
* Gnus Startup::        What you should know about starting Gnus.
44 45
* Gnus Group Buffer::   A short description of Gnus group commands.
* Gnus Summary Buffer:: A short description of Gnus summary commands.
Dave Love's avatar
#  
Dave Love committed
46 47 48 49 50
@end menu

@node Buffers of Gnus
@subsection Gnus Buffers

51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80
  Gnus uses several buffers to display information and to receive
commands.  The three most commonly-used Gnus buffers are the
@dfn{group buffer}, the @dfn{summary buffer} and the @dfn{article
buffer}.

  The @dfn{group buffer} contains a list of article sources (e.g.@:
newsgroups and email inboxes), which are collectively referred to as
@dfn{groups}.  This is the first buffer Gnus displays when it starts
up.  It normally displays only the groups to which you subscribe and
that contain unread articles.  From this buffer, you can select a
group to read.

  The @dfn{summary buffer} lists the articles in a single group,
showing one article per line.  By default, it displays each article's
author, subject, and line
@iftex
number.
@end iftex
@ifnottex
number, but this is customizable; @xref{Summary Buffer Format,,, gnus,
The Gnus Manual}.
@end ifnottex
The summary buffer is created when you select a group in the group
buffer, and is killed when you exit the group.

  From the summary buffer, you can choose an article to view.  The
article is displayed in the @dfn{article buffer}.  In normal Gnus
usage, you view this buffer but do not select it---all useful Gnus
commands can be invoked from the summary buffer.  But you can select
the article buffer, and execute Gnus commands from it, if you wish.
Dave Love's avatar
#  
Dave Love committed
81 82 83 84

@node Gnus Startup
@subsection When Gnus Starts Up

85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107
@findex gnus
@cindex @file{.newsrc} file
  If your system has been set up for reading Usenet news, getting
started with Gnus is easy---just type @kbd{M-x gnus}.

  On starting up, Gnus reads your @dfn{news initialization file}: a
file named @file{.newsrc} in your home directory which lists your
Usenet newsgroups and subscriptions (this file is not unique to Gnus;
it is used by many other newsreader programs).  It then tries to
contact the system's default news server, which is typically specified
by the @samp{NNTPSERVER} environment variable.

  If your system does not have a default news server, or if you wish
to use Gnus for reading email, then before invoking @kbd{M-x gnus} you
need to tell Gnus where to get news and/or mail.  To do this,
customize the variables @code{gnus-select-method} and/or
@code{gnus-secondary-select-methods}.
@iftex
See the Gnus manual for details.
@end iftex
@ifnottex
@xref{Finding the News,,, gnus, The Gnus Manual}.
@end ifnottex
Dave Love's avatar
#  
Dave Love committed
108

109 110 111 112 113 114
  Once Gnus has started up, it displays the group buffer.  By default,
the group buffer shows only a small number of @dfn{subscribed groups}.
Groups with other statuses---@dfn{unsubscribed}, @dfn{killed}, or
@dfn{zombie}---are hidden.  The first time you start Gnus, any group
to which you are not subscribed is made into a killed group; any group
that subsequently appears on the news server becomes a zombie group.
Dave Love's avatar
#  
Dave Love committed
115

116 117 118 119
  To proceed, you must select a group in the group buffer to open the
summary buffer for that group; then, select an article in the summary
buffer to view its article buffer in a separate window.  The following
sections explain how to use the group and summary buffers to do this.
Dave Love's avatar
#  
Dave Love committed
120

121 122 123 124
  To quit Gnus, type @kbd{q} in the group buffer.  This automatically
records your group statuses in the files @file{.newsrc} and
@file{.newsrc.eld}, so that they take effect in subsequent Gnus
sessions.
Dave Love's avatar
#  
Dave Love committed
125

126 127
@node Gnus Group Buffer
@subsection Using the Gnus Group Buffer
Dave Love's avatar
#  
Dave Love committed
128

129
  The following commands are available in the Gnus group buffer:
Dave Love's avatar
#  
Dave Love committed
130 131

@table @kbd
132 133 134 135
@kindex SPC @r{(Gnus Group mode)}
@findex gnus-group-read-group
@item @key{SPC}
Switch to the summary buffer for the group on the current line.
Dave Love's avatar
#  
Dave Love committed
136

137 138 139 140 141 142 143
@kindex l @r{(Gnus Group mode)}
@kindex A s @r{(Gnus Group mode)}
@findex gnus-group-list-groups
@item l
@itemx A s
In the group buffer, list only the groups to which you subscribe and
which contain unread articles (this is the default listing).
Dave Love's avatar
#  
Dave Love committed
144 145

@kindex L @r{(Gnus Group mode)}
146
@kindex A u @r{(Gnus Group mode)}
Dave Love's avatar
#  
Dave Love committed
147 148
@findex gnus-group-list-all-groups
@item L
149 150 151
@itemx A u
List all subscribed and unsubscribed groups, but not killed or zombie
groups.
Dave Love's avatar
#  
Dave Love committed
152

153 154 155 156 157 158 159 160 161
@kindex A k @r{(Gnus Group mode)}
@findex gnus-group-list-all-groups
@item A k
List killed groups.

@kindex A z @r{(Gnus Group mode)}
@findex gnus-group-list-all-groups
@item A z
List zombie groups.
Dave Love's avatar
#  
Dave Love committed
162 163 164 165 166 167

@kindex u @r{(Gnus Group mode)}
@findex gnus-group-unsubscribe-current-group
@cindex subscribe groups
@cindex unsubscribe groups
@item u
168 169 170 171
Toggle the subscription status of the group on the current line
(i.e.@: turn a subscribed group into an unsubscribed group, or vice
versa).  Invoking this on a killed or zombie group turns it into an
unsubscribed group.
Dave Love's avatar
#  
Dave Love committed
172

173
@kindex C-k @r{(Gnus Group mode)}
Dave Love's avatar
#  
Dave Love committed
174 175
@findex gnus-group-kill-group
@item C-k
176 177 178
Kill the group on the current line.  Killed groups are not recorded in
the @file{.newsrc} file, and they are not shown in the @kbd{l} or
@kbd{L} listings.
Dave Love's avatar
#  
Dave Love committed
179

180 181 182
@kindex DEL @r{(Gnus Group mode)}
@item @key{DEL}
Move point to the previous group containing unread articles.
Dave Love's avatar
#  
Dave Love committed
183

184 185 186 187 188
@kindex n @r{(Gnus Group mode)}
@findex gnus-group-next-unread-group
@findex gnus-summary-next-unread-article
@item n
Move point to the next unread group.
Dave Love's avatar
#  
Dave Love committed
189

190 191 192 193 194
@kindex p @r{(Gnus Group mode)}
@findex gnus-group-prev-unread-group
@findex gnus-summary-prev-unread-article
@item p
Move point to the previous unread group.
Dave Love's avatar
#  
Dave Love committed
195

196 197 198 199 200
@kindex q @r{(Gnus Group mode)}
@findex gnus-group-exit
@item q
Update your Gnus settings, and quit Gnus.
@end table
Dave Love's avatar
#  
Dave Love committed
201

202 203
@node Gnus Summary Buffer
@subsection Using the Gnus Summary Buffer
Dave Love's avatar
#  
Dave Love committed
204

205
  The following commands are available in the Gnus summary buffer:
Dave Love's avatar
#  
Dave Love committed
206

207 208 209 210 211 212 213 214
@table @kbd
@kindex SPC @r{(Gnus Summary mode)}
@findex gnus-group-read-group
@item @key{SPC}
If there is no article selected, select the article on the current
line and display its article buffer.  Otherwise, try scrolling the
selected article buffer in its window; on reaching the end of the
buffer, select the next unread article.
Dave Love's avatar
#  
Dave Love committed
215

216 217
Thus, you can read through all articles by repeatedly typing
@key{SPC}.
Dave Love's avatar
#  
Dave Love committed
218

219
@kindex DEL @r{(Gnus Summary mode)}
Dave Love's avatar
#  
Dave Love committed
220
@findex gnus-summary-prev-page
221 222
@item @key{DEL}
Scroll the text of the article backwards.
Dave Love's avatar
#  
Dave Love committed
223

224
@kindex n @r{(Gnus Summary mode)}
Dave Love's avatar
#  
Dave Love committed
225 226 227
@findex gnus-group-next-unread-group
@findex gnus-summary-next-unread-article
@item n
228
Select the next unread article.
Dave Love's avatar
#  
Dave Love committed
229

230
@kindex p @r{(Gnus Summary mode)}
Dave Love's avatar
#  
Dave Love committed
231 232 233
@findex gnus-group-prev-unread-group
@findex gnus-summary-prev-unread-article
@item p
234
Select the previous unread article.
Dave Love's avatar
#  
Dave Love committed
235 236 237 238

@kindex s @r{(Gnus Summary mode)}
@findex gnus-summary-isearch-article
@item s
239 240 241
Do an incremental search on the selected article buffer, as if you
switched to the buffer and typed @kbd{C-s} (@pxref{Incremental
Search}).
Dave Love's avatar
#  
Dave Love committed
242 243 244 245

@kindex M-s @r{(Gnus Summary mode)}
@findex gnus-summary-search-article-forward
@item M-s @var{regexp} @key{RET}
246
Search forward for articles containing a match for @var{regexp}.
Dave Love's avatar
#  
Dave Love committed
247

248 249 250
@kindex q @r{(Gnus Summary mode)}
@item q
Exit the summary buffer and return to the group buffer.
Dave Love's avatar
#  
Dave Love committed
251 252
@end table

253 254 255 256 257
@node Document View
@section Document Viewing
@cindex DVI file
@cindex PDF file
@cindex PS file
Juanma Barranquero's avatar
Juanma Barranquero committed
258
@cindex PostScript file
259 260 261 262 263 264
@cindex OpenDocument file
@cindex Microsoft Office file
@cindex DocView mode
@cindex mode, DocView
@cindex document viewer (DocView)
@findex doc-view-mode
Dave Love's avatar
#  
Dave Love committed
265

266 267 268 269 270 271 272 273
  DocView mode is a major mode for viewing DVI, PostScript (PS), PDF,
OpenDocument, and Microsoft Office documents.  It provides features
such as slicing, zooming, and searching inside documents.  It works by
converting the document to a set of images using the @command{gs}
(GhostScript) command and other external tools @footnote{@code{gs} is
a hard requirement.  For DVI files, @code{dvipdf} or @code{dvipdfm} is
needed.  For OpenDocument and Microsoft Office documents, the
@code{unoconv} tool is needed.}, and displaying those images.
Dave Love's avatar
#  
Dave Love committed
274

275 276 277
@findex doc-view-toggle-display
@findex doc-view-toggle-display
@cindex doc-view-minor-mode
278 279 280 281 282 283 284 285 286 287 288 289 290 291 292
  When you visit a document file that can be displayed with DocView
mode, Emacs automatically uses DocView mode @footnote{The needed
external tools for the document type must be available, and Emacs must
be running in a graphical frame and have PNG image support.  If any of
these requirements is not fulfilled, Emacs falls back to another major
mode.}.  As an exception, when you visit a PostScript file, Emacs
switches to PS mode, a major mode for editing PostScript files as
text; however, it also enables DocView minor mode, so you can type
@kbd{C-c C-c} to view the document with DocView.  In either DocView
mode or DocView minor mode, repeating @kbd{C-c C-c}
(@code{doc-view-toggle-display}) toggles between DocView and the
underlying file contents.

  You can explicitly enable DocView mode with the command @code{M-x
doc-view-mode}.  You can toggle DocView minor mode with @code{M-x
293
doc-view-minor-mode}.
Dave Love's avatar
#  
Dave Love committed
294

295 296 297
  When DocView mode starts, it displays a welcome screen and begins
formatting the file, page by page.  It displays the first page once
that has been formatted.
Dave Love's avatar
#  
Dave Love committed
298

299 300 301
  To kill the DocView buffer, type @kbd{k}
(@code{doc-view-kill-proc-and-buffer}).  To bury it, type @kbd{q}
(@code{quit-window}).
Dave Love's avatar
#  
Dave Love committed
302

303
@menu
304 305 306 307
* Navigation: DocView Navigation.  Navigating DocView buffers.
* Searching: DocView Searching.    Searching inside documents.
* Slicing: DocView Slicing.        Specifying which part of a page is displayed.
* Conversion: DocView Conversion.  Influencing and triggering conversion.
308
@end menu
Dave Love's avatar
#  
Dave Love committed
309

310 311
@node DocView Navigation
@subsection DocView Navigation
Dave Love's avatar
#  
Dave Love committed
312

313
  In DocView mode, you can scroll the current page using the usual
314 315
Emacs movement keys: @kbd{C-p}, @kbd{C-n}, @kbd{C-b}, @kbd{C-f}, and
the arrow keys.
Dave Love's avatar
#  
Dave Love committed
316

317 318 319 320 321 322 323
@vindex doc-view-continuous
  By default, the line-motion keys @kbd{C-p} and @kbd{C-n} stop
scrolling at the beginning and end of the current page, respectively.
However, if you change the variable @code{doc-view-continuous} to a
non-@code{nil} value, then @kbd{C-p} displays the previous page if you
are already at the beginning of the current page, and @kbd{C-n}
displays the next page if you are at the end of the current page.
Dave Love's avatar
#  
Dave Love committed
324

325 326
@findex doc-view-next-page
@findex doc-view-previous-page
327 328 329 330
@kindex n @r{(DocView mode)}
@kindex p @r{(DocView mode)}
@kindex C-x ] @r{(DocView mode)}
@kindex C-x [ @r{(DocView mode)}
331 332 333 334
  You can also display the next page by typing @kbd{n}, @key{next} or
@kbd{C-x ]} (@code{doc-view-next-page}).  To display the previous
page, type @kbd{p}, @key{prior} or @kbd{C-x [}
(@code{doc-view-previous-page}).
Dave Love's avatar
#  
Dave Love committed
335

336 337
@findex doc-view-scroll-up-or-next-page
@findex doc-view-scroll-down-or-previous-page
338 339 340 341 342 343
@kindex SPC @r{(DocView mode)}
@kindex DEL @r{(DocView mode)}
  @key{SPC} (@code{doc-view-scroll-up-or-next-page}) is a convenient
way to advance through the document.  It scrolls within the current
page or advances to the next.  @key{DEL} moves backwards in a similar
way (@code{doc-view-scroll-down-or-previous-page}).
Dave Love's avatar
#  
Dave Love committed
344

345 346 347
@findex doc-view-first-page
@findex doc-view-last-page
@findex doc-view-goto-page
348 349
@kindex M-< @r{(DocView mode)}
@kindex M-> @r{(DocView mode)}
350 351 352 353
  To go to the first page, type @kbd{M-<}
(@code{doc-view-first-page}); to go to the last one, type @kbd{M->}
(@code{doc-view-last-page}).  To jump to a page by its number, type
@kbd{M-g M-g} or @kbd{M-g g} (@code{doc-view-goto-page}).
Dave Love's avatar
#  
Dave Love committed
354

355 356 357 358 359 360 361 362 363 364 365 366 367 368 369
@findex doc-view-enlarge
@findex doc-view-shrink
@vindex doc-view-resolution
@kindex + @r{(DocView mode)}
@kindex - @r{(DocView mode)}
  You can enlarge or shrink the document with @kbd{+}
(@code{doc-view-enlarge}) and @kbd{-} (@code{doc-view-shrink}).  These
commands work by reconverting the document at the new size.  To
specify the default size for DocView, customize the variable
@code{doc-view-resolution}.

@node DocView Searching
@subsection DocView Searching

  In DocView mode, you can search the file's text for a regular
370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389
expression (@pxref{Regexps}).  The interface for searching is inspired
by @code{isearch} (@pxref{Incremental Search}).

@findex doc-view-search
@findex doc-view-search-backward
@findex doc-view-show-tooltip
  To begin a search, type @kbd{C-s} (@code{doc-view-search}) or
@kbd{C-r} (@code{doc-view-search-backward}).  This reads a regular
expression using a minibuffer, then echoes the number of matches found
within the document.  You can move forward and back among the matches
by typing @kbd{C-s} and @kbd{C-r}.  DocView mode has no way to show
the match inside the page image; instead, it displays a tooltip (at
the mouse position) listing all matching lines in the current page.
To force display of this tooltip, type @kbd{C-t}
(@code{doc-view-show-tooltip}).

  To start a new search, use the search command with a prefix
argument; i.e., @kbd{C-u C-s} for a forward search or @kbd{C-u C-r}
for a backward search.

390 391
@node DocView Slicing
@subsection DocView Slicing
392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418

Documents often have wide margins for printing.  They are annoying
when reading the document on the screen, because they use up screen
space and can cause inconvenient scrolling.

@findex doc-view-set-slice
@findex doc-view-set-slice-using-mouse
  With DocView you can hide these margins by selecting a @dfn{slice}
of pages to display.  A slice is a rectangle within the page area;
once you specify a slice in DocView, it applies to whichever page you
look at.

  To specify the slice numerically, type @kbd{s s}
(@code{doc-view-set-slice}); then enter the top left pixel position
and the slice's width and height.
@c ??? how does this work?

  A more convenient graphical way to specify the slice is with @kbd{s
m} (@code{doc-view-set-slice-using-mouse}), where you use the mouse to
select the slice.
@c ??? How does this work?

@findex doc-view-reset-slice
  To cancel the selected slice, type @kbd{s r}
(@code{doc-view-reset-slice}).  Then DocView shows the entire page
including its entire margins.

419 420
@node DocView Conversion
@subsection DocView Conversion
421 422 423

@vindex doc-view-cache-directory
@findex doc-view-clear-cache
424
  For efficiency, DocView caches the images produced by @command{gs}.
425 426 427 428 429 430
The name of this directory is given by the variable
@code{doc-view-cache-directory}.  You can clear the cache directory by
typing @code{M-x doc-view-clear-cache}.

@findex doc-view-kill-proc
@findex doc-view-kill-proc-and-buffer
431 432 433
  To force reconversion of the currently viewed document, type @kbd{r}
or @kbd{g} (@code{revert-buffer}).  To kill the converter process
associated with the current buffer, type @kbd{K}
434 435 436 437 438
(@code{doc-view-kill-proc}).  The command @kbd{k}
(@code{doc-view-kill-proc-and-buffer}) kills the converter process and
the DocView buffer.

@node Shell
Dave Love's avatar
#  
Dave Love committed
439 440 441 442
@section Running Shell Commands from Emacs
@cindex subshell
@cindex shell commands

443 444 445
  Emacs has commands for passing single command lines to shell
subprocesses, and for running a shell interactively with input and
output to an Emacs buffer, and for running a shell in a terminal
Dave Love's avatar
Dave Love committed
446 447
emulator window.

Dave Love's avatar
#  
Dave Love committed
448 449
@table @kbd
@item M-! @var{cmd} @key{RET}
Chong Yidong's avatar
Chong Yidong committed
450
Run the shell command @var{cmd} and display the output
Dave Love's avatar
#  
Dave Love committed
451 452
(@code{shell-command}).
@item M-| @var{cmd} @key{RET}
Chong Yidong's avatar
Chong Yidong committed
453
Run the shell command @var{cmd} with region contents as input;
Dave Love's avatar
#  
Dave Love committed
454 455
optionally replace the region with the output
(@code{shell-command-on-region}).
456
@item M-& @var{cmd} @key{RET}
Chong Yidong's avatar
Chong Yidong committed
457 458
Run the shell command @var{cmd} asynchronously, and display the output
(@code{async-shell-command}).
Dave Love's avatar
#  
Dave Love committed
459
@item M-x shell
Chong Yidong's avatar
Chong Yidong committed
460 461
Run a subshell with input and output through an Emacs buffer.  You can
then give commands interactively.
Dave Love's avatar
Dave Love committed
462
@item M-x term
Chong Yidong's avatar
Chong Yidong committed
463 464 465
Run a subshell with input and output through an Emacs buffer.  You can
then give commands interactively.  Full terminal emulation is
available.
Dave Love's avatar
#  
Dave Love committed
466 467
@end table

468 469 470 471 472 473 474 475 476
@vindex exec-path
  Whenever you specify a relative file name for an executable program
(either in the @var{cmd} argument to one of the above commands, or in
other contexts), Emacs searches for the program in the directories
specified by the variable @code{exec-path}.  The value of this
variable must be a list of directory names; the default value is
initialized from the environment variable @env{PATH} when Emacs is
started (@pxref{General Variables}).

Richard M. Stallman's avatar
Richard M. Stallman committed
477
  @kbd{M-x eshell} invokes a shell implemented entirely in Emacs.  It
Chong Yidong's avatar
Chong Yidong committed
478 479 480 481 482 483 484
is documented in its own manual.
@ifnottex
@xref{Top,Eshell,Eshell, eshell, Eshell: The Emacs Shell}.
@end ifnottex
@iftex
See the Eshell Info manual, which is distributed with Emacs.
@end iftex
Richard M. Stallman's avatar
Richard M. Stallman committed
485

Dave Love's avatar
#  
Dave Love committed
486 487 488 489
@menu
* Single Shell::           How to run one shell command and return.
* Interactive Shell::      Permanent shell taking input via Emacs.
* Shell Mode::             Special Emacs commands used with permanent shell.
490
* Shell Prompts::          Two ways to recognize shell prompts.
Dave Love's avatar
#  
Dave Love committed
491
* History: Shell History.  Repeating previous commands in a shell buffer.
492
* Directory Tracking::     Keeping track when the subshell changes directory.
Dave Love's avatar
#  
Dave Love committed
493
* Options: Shell Options.  Options for customizing Shell mode.
Dave Love's avatar
Dave Love committed
494 495
* Terminal emulator::      An Emacs window as a terminal emulator.
* Term Mode::              Special Emacs commands used in Term mode.
Dave Love's avatar
#  
Dave Love committed
496
* Remote Host::            Connecting to another computer.
497
* Serial Terminal::        Connecting to a serial port.
Dave Love's avatar
#  
Dave Love committed
498 499 500 501 502 503 504 505
@end menu

@node Single Shell
@subsection Single Shell Commands

@kindex M-!
@findex shell-command
  @kbd{M-!} (@code{shell-command}) reads a line of text using the
Chong Yidong's avatar
Chong Yidong committed
506
minibuffer and executes it as a shell command, in a subshell made just
Dave Love's avatar
#  
Dave Love committed
507
for that command.  Standard input for the command comes from the null
508 509
device.  If the shell command produces any output, the output appears
either in the echo area (if it is short), or in an Emacs buffer named
Chong Yidong's avatar
Chong Yidong committed
510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544
@samp{*Shell Command Output*}, displayed in another window (if the
output is long).

  For instance, one way to decompress a file named @file{foo.gz} is to
type @kbd{M-! gunzip foo.gz @key{RET}}.  That shell command normally
creates the file @file{foo} and produces no terminal output.

  A numeric argument to @code{shell-command}, e.g.@: @kbd{M-1 M-!},
causes it to insert terminal output into the current buffer instead of
a separate buffer.  It puts point before the output, and sets the mark
after the output.  For instance, @kbd{M-1 M-! gunzip < foo.gz
@key{RET}} would insert the uncompressed form of the file
@file{foo.gz} into the current buffer.

  Provided the specified shell command does not end with @samp{&}, it
runs @dfn{synchronously}, and you must wait for it to exit before
continuing to use Emacs.  To stop waiting, type @kbd{C-g} to quit;
this sends a @code{SIGINT} signal to terminate the shell command (this
is the same signal that @kbd{C-c} normally generates in the shell).
Emacs then waits until the command actually terminates.  If the shell
command doesn't stop (because it ignores the @code{SIGINT} signal),
type @kbd{C-g} again; this sends the command a @code{SIGKILL} signal,
which is impossible to ignore.

@kindex M-&
@findex async-shell-command
  A shell command that ends in @samp{&} is executed
@dfn{asynchronously}, and you can continue to use Emacs as it runs.
You can also type @kbd{M-&} (@code{async-shell-command}) to execute a
shell command asynchronously; this is exactly like calling @kbd{M-!}
with a trailing @samp{&}, except that you do not need the @samp{&}.
The output buffer for asynchronous shell commands is named
@samp{*Async Shell Command*}.  Emacs inserts the output into this
buffer as it comes in, whether or not the buffer is visible in a
window.
545

Dave Love's avatar
#  
Dave Love committed
546 547
@kindex M-|
@findex shell-command-on-region
Chong Yidong's avatar
Chong Yidong committed
548
  @kbd{M-|} (@code{shell-command-on-region}) is like @kbd{M-!}, but
Dave Love's avatar
#  
Dave Love committed
549
passes the contents of the region as the standard input to the shell
Chong Yidong's avatar
Chong Yidong committed
550 551 552 553 554 555 556 557
command, instead of no input.  With a numeric argument, it deletes the
old region and replaces it with the output from the shell command.

  For example, you can use @kbd{M-|} with the @command{gpg} program to
see what keys are in the buffer.  If the buffer contains a GnuPG key,
type @kbd{C-x h M-| gpg @key{RET}} to feed the entire buffer contents
to @command{gpg}.  This will output the list of keys to the
@samp{*Shell Command Output*} buffer.
558

Dave Love's avatar
#  
Dave Love committed
559
@vindex shell-file-name
Chong Yidong's avatar
Chong Yidong committed
560 561
  The above commands use the shell specified by the variable
@code{shell-file-name}.  Its default value is determined by the
Richard M. Stallman's avatar
Richard M. Stallman committed
562
@env{SHELL} environment variable when Emacs is started.  If the file
563 564
name is relative, Emacs searches the directories listed in
@code{exec-path} (@pxref{Shell}).
Dave Love's avatar
#  
Dave Love committed
565 566

  To specify a coding system for @kbd{M-!} or @kbd{M-|}, use the command
567
@kbd{C-x @key{RET} c} immediately beforehand.  @xref{Communication Coding}.
Dave Love's avatar
#  
Dave Love committed
568 569

@vindex shell-command-default-error-buffer
Chong Yidong's avatar
Chong Yidong committed
570 571 572 573
  By default, error output is intermixed with the regular output in
the output buffer.  But if you change the value of the variable
@code{shell-command-default-error-buffer} to a string, error output is
inserted into a buffer of that name.
Dave Love's avatar
#  
Dave Love committed
574 575

@node Interactive Shell
Chong Yidong's avatar
Chong Yidong committed
576
@subsection Interactive Subshell
Dave Love's avatar
#  
Dave Love committed
577 578

@findex shell
Chong Yidong's avatar
Chong Yidong committed
579 580 581 582 583 584 585 586 587 588 589 590
  To run a subshell interactively, type @kbd{M-x shell}.  This creates
(or reuses) a buffer named @samp{*shell*}, and runs a shell subprocess
with input coming from and output going to that buffer.  That is to
say, any terminal output from the subshell goes into the buffer,
advancing point, and any terminal input for the subshell comes from
text in the buffer.  To give input to the subshell, go to the end of
the buffer and type the input, terminated by @key{RET}.

  While the subshell is waiting or running a command, you can switch
windows or buffers and perform other editing in Emacs.  Emacs inserts
the output from the subshell into the Shell buffer whenever it has
time to process it (e.g.@: while waiting for keyboard input).
Dave Love's avatar
#  
Dave Love committed
591

592 593
@cindex @code{comint-highlight-input} face
@cindex @code{comint-highlight-prompt} face
Chong Yidong's avatar
Chong Yidong committed
594 595 596 597 598 599 600 601 602 603 604
  In the Shell buffer, prompts are displayed with the face
@code{comint-highlight-prompt}, and submitted input lines are
displayed with the face @code{comint-highlight-input}.  This makes it
easier to distinguish input lines from the shell output.
@xref{Faces}.

  To make multiple subshells, invoke @kbd{M-x shell} with a prefix
argument (e.g. @kbd{C-u M-x shell}).  Then the command will read a
buffer name, and create (or reuse) a subshell in that buffer.  You can
also rename the @samp{*shell*} buffer using @kbd{M-x rename-uniquely},
then create a new @samp{*shell*} buffer using plain @kbd{M-x shell}.
Richard M. Stallman's avatar
Richard M. Stallman committed
605
Subshells in different buffers run independently and in parallel.
Dave Love's avatar
#  
Dave Love committed
606 607

@vindex explicit-shell-file-name
608
@cindex environment variables for subshells
Gerd Moellmann's avatar
Gerd Moellmann committed
609 610
@cindex @env{ESHELL} environment variable
@cindex @env{SHELL} environment variable
Chong Yidong's avatar
Chong Yidong committed
611 612 613 614 615 616 617
  To specify the shell file name used by @kbd{M-x shell}, customize
the variable @code{explicit-shell-file-name}.  If this is @code{nil}
(the default), Emacs uses the environment variable @env{ESHELL} if it
exists.  Otherwise, it usually uses the variable
@code{shell-file-name} (@pxref{Single Shell}); but if the default
directory is remote (@pxref{Remote Files}), it prompts you for the
shell file name.
Dave Love's avatar
#  
Dave Love committed
618

619 620 621 622
  Emacs sends the new shell the contents of the file
@file{~/.emacs_@var{shellname}} as input, if it exists, where
@var{shellname} is the name of the file that the shell was loaded
from.  For example, if you use bash, the file sent to it is
Chong Yidong's avatar
Chong Yidong committed
623 624
@file{~/.emacs_bash}.  If this file is not found, Emacs tries with
@file{~/.emacs.d/init_@var{shellname}.sh}.
625

Dave Love's avatar
#  
Dave Love committed
626
  To specify a coding system for the shell, you can use the command
Richard M. Stallman's avatar
Richard M. Stallman committed
627 628 629 630
@kbd{C-x @key{RET} c} immediately before @kbd{M-x shell}.  You can
also change the coding system for a running subshell by typing
@kbd{C-x @key{RET} p} in the shell buffer.  @xref{Communication
Coding}.
Dave Love's avatar
#  
Dave Love committed
631

632
@cindex @env{INSIDE_EMACS} environment variable
633
@cindex @env{EMACS} environment variable
Chong Yidong's avatar
Chong Yidong committed
634 635 636 637 638 639 640 641
  Emacs sets the environment variable @env{INSIDE_EMACS} in the
subshell to @samp{@var{version},comint}, where @var{version} is the
Emacs version (e.g.@: @samp{24.1}).  Programs can check this variable
to determine whether they are running inside an Emacs subshell.  (It
also sets the @env{EMACS} environment variable to @code{t}, if that
environment variable is not already defined.  However, this
environment variable is deprecated; programs that use it should switch
to using @env{INSIDE_EMACS} instead.)
Dave Love's avatar
#  
Dave Love committed
642 643 644 645 646 647

@node Shell Mode
@subsection Shell Mode
@cindex Shell mode
@cindex mode, Shell

Chong Yidong's avatar
Chong Yidong committed
648 649 650 651 652
  The major mode for Shell buffers is Shell mode.  Many of its special
commands are bound to the @kbd{C-c} prefix, and resemble the usual
editing and job control characters present in ordinary shells, except
that you must type @kbd{C-c} first.  Here is a list of Shell mode
commands:
Dave Love's avatar
#  
Dave Love committed
653 654 655 656 657

@table @kbd
@item @key{RET}
@kindex RET @r{(Shell mode)}
@findex comint-send-input
Chong Yidong's avatar
Chong Yidong committed
658 659 660 661 662 663
Send the current line as input to the subshell
(@code{comint-send-input}).  Any shell prompt at the beginning of the
line is omitted (@pxref{Shell Prompts}).  If point is at the end of
buffer, this is like submitting the command line in an ordinary
interactive shell.  However, you can also invoke @key{RET} elsewhere
in the shell buffer to submit the current line as input.
Dave Love's avatar
#  
Dave Love committed
664 665 666

@item @key{TAB}
@kindex TAB @r{(Shell mode)}
Chong Yidong's avatar
Chong Yidong committed
667 668 669 670 671 672
@findex completion-at-point
Complete the command name or file name before point in the shell
buffer (@code{completion-at-point}).  This uses the usual Emacs
completion rules (@pxref{Completion}), with the completion
alternatives being file names, environment variable names, the shell
command history, and history references (@pxref{History References}).
Dave Love's avatar
#  
Dave Love committed
673 674 675 676

@vindex shell-completion-fignore
@vindex comint-completion-fignore
The variable @code{shell-completion-fignore} specifies a list of file
677 678 679
name extensions to ignore in Shell mode completion.  The default
setting is @code{nil}, but some users prefer @code{("~" "#" "%")} to
ignore file names ending in @samp{~}, @samp{#} or @samp{%}.  Other
Dave Love's avatar
#  
Dave Love committed
680 681 682 683 684 685
related Comint modes use the variable @code{comint-completion-fignore}
instead.

@item M-?
@kindex M-? @r{(Shell mode)}
@findex comint-dynamic-list-filename@dots{}
Chong Yidong's avatar
Chong Yidong committed
686 687
Display temporarily a list of the possible completions of the file
name before point (@code{comint-dynamic-list-filename-completions}).
Dave Love's avatar
#  
Dave Love committed
688 689 690 691

@item C-d
@kindex C-d @r{(Shell mode)}
@findex comint-delchar-or-maybe-eof
692
Either delete a character or send @acronym{EOF}
Dave Love's avatar
#  
Dave Love committed
693
(@code{comint-delchar-or-maybe-eof}).  Typed at the end of the shell
Chong Yidong's avatar
Chong Yidong committed
694 695
buffer, this sends @acronym{EOF} to the subshell.  Typed at any other
position in the buffer, this deletes a character as usual.
Dave Love's avatar
#  
Dave Love committed
696 697 698

@item C-c C-a
@kindex C-c C-a @r{(Shell mode)}
699
@findex comint-bol-or-process-mark
Dave Love's avatar
#  
Dave Love committed
700
Move to the beginning of the line, but after the prompt if any
701 702 703 704 705 706
(@code{comint-bol-or-process-mark}).  If you repeat this command twice
in a row, the second time it moves back to the process mark, which is
the beginning of the input that you have not yet sent to the subshell.
(Normally that is the same place---the end of the prompt on this
line---but after @kbd{C-c @key{SPC}} the process mark may be in a
previous line.)
Dave Love's avatar
#  
Dave Love committed
707 708 709 710 711 712 713 714 715 716 717 718

@item C-c @key{SPC}
Accumulate multiple lines of input, then send them together.  This
command inserts a newline before point, but does not send the preceding
text as input to the subshell---at least, not yet.  Both lines, the one
before this newline and the one after, will be sent together (along with
the newline that separates them), when you type @key{RET}.

@item C-c C-u
@kindex C-c C-u @r{(Shell mode)}
@findex comint-kill-input
Kill all text pending at end of buffer to be sent as input
719 720
(@code{comint-kill-input}).  If point is not at end of buffer,
this only kills the part of this text that precedes point.
Dave Love's avatar
#  
Dave Love committed
721 722 723 724 725 726 727 728 729 730 731 732 733 734 735 736 737 738 739 740 741 742 743 744 745 746 747 748

@item C-c C-w
@kindex C-c C-w @r{(Shell mode)}
Kill a word before point (@code{backward-kill-word}).

@item C-c C-c
@kindex C-c C-c @r{(Shell mode)}
@findex comint-interrupt-subjob
Interrupt the shell or its current subjob if any
(@code{comint-interrupt-subjob}).  This command also kills
any shell input pending in the shell buffer and not yet sent.

@item C-c C-z
@kindex C-c C-z @r{(Shell mode)}
@findex comint-stop-subjob
Stop the shell or its current subjob if any (@code{comint-stop-subjob}).
This command also kills any shell input pending in the shell buffer and
not yet sent.

@item C-c C-\
@findex comint-quit-subjob
@kindex C-c C-\ @r{(Shell mode)}
Send quit signal to the shell or its current subjob if any
(@code{comint-quit-subjob}).  This command also kills any shell input
pending in the shell buffer and not yet sent.

@item C-c C-o
@kindex C-c C-o @r{(Shell mode)}
Miles Bader's avatar
Miles Bader committed
749 750 751
@findex comint-delete-output
Delete the last batch of output from a shell command
(@code{comint-delete-output}).  This is useful if a shell command spews
752
out lots of output that just gets in the way.
Miles Bader's avatar
Miles Bader committed
753 754 755 756 757 758 759 760

@item C-c C-s
@kindex C-c C-s @r{(Shell mode)}
@findex comint-write-output
Write the last batch of output from a shell command to a file
(@code{comint-write-output}).  With a prefix argument, the file is
appended to instead.  Any prompt at the end of the output is not
written.
Dave Love's avatar
#  
Dave Love committed
761 762 763 764 765 766 767 768 769 770 771 772 773 774 775 776 777 778 779 780 781 782 783 784 785 786 787 788 789 790

@item C-c C-r
@itemx C-M-l
@kindex C-c C-r @r{(Shell mode)}
@kindex C-M-l @r{(Shell mode)}
@findex comint-show-output
Scroll to display the beginning of the last batch of output at the top
of the window; also move the cursor there (@code{comint-show-output}).

@item C-c C-e
@kindex C-c C-e @r{(Shell mode)}
@findex comint-show-maximum-output
Scroll to put the end of the buffer at the bottom of the window
(@code{comint-show-maximum-output}).

@item C-c C-f
@kindex C-c C-f @r{(Shell mode)}
@findex shell-forward-command
@vindex shell-command-regexp
Move forward across one shell command, but not beyond the current line
(@code{shell-forward-command}).  The variable @code{shell-command-regexp}
specifies how to recognize the end of a command.

@item C-c C-b
@kindex C-c C-b @r{(Shell mode)}
@findex shell-backward-command
Move backward across one shell command, but not beyond the current line
(@code{shell-backward-command}).

@item M-x dirs
Chong Yidong's avatar
Chong Yidong committed
791 792
Ask the shell for its working directory, and update the Shell buffer's
default directory.  @xref{Directory Tracking}.
Dave Love's avatar
#  
Dave Love committed
793 794 795 796 797 798 799

@item M-x send-invisible @key{RET} @var{text} @key{RET}
@findex send-invisible
Send @var{text} as input to the shell, after reading it without
echoing.  This is useful when a shell command runs a program that asks
for a password.

800 801 802
Please note that Emacs will not echo passwords by default.  If you
really want them to be echoed, evaluate the following Lisp
expression:
Dave Love's avatar
#  
Dave Love committed
803 804

@example
805 806
(remove-hook 'comint-output-filter-functions
             'comint-watch-for-password-prompt)
Dave Love's avatar
#  
Dave Love committed
807 808 809 810 811 812 813 814 815 816 817 818 819 820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835 836 837 838 839 840 841 842 843 844 845 846
@end example

@item M-x comint-continue-subjob
@findex comint-continue-subjob
Continue the shell process.  This is useful if you accidentally suspend
the shell process.@footnote{You should not suspend the shell process.
Suspending a subjob of the shell is a completely different matter---that
is normal practice, but you must use the shell to continue the subjob;
this command won't do it.}

@item M-x comint-strip-ctrl-m
@findex comint-strip-ctrl-m
Discard all control-M characters from the current group of shell output.
The most convenient way to use this command is to make it run
automatically when you get output from the subshell.  To do that,
evaluate this Lisp expression:

@example
(add-hook 'comint-output-filter-functions
          'comint-strip-ctrl-m)
@end example

@item M-x comint-truncate-buffer
@findex comint-truncate-buffer
This command truncates the shell buffer to a certain maximum number of
lines, specified by the variable @code{comint-buffer-maximum-size}.
Here's how to do this automatically each time you get output from the
subshell:

@example
(add-hook 'comint-output-filter-functions
          'comint-truncate-buffer)
@end example
@end table

@cindex Comint mode
@cindex mode, Comint
  Shell mode is a derivative of Comint mode, a general-purpose mode for
communicating with interactive subprocesses.  Most of the features of
Shell mode actually come from Comint mode, as you can see from the
847 848
command names listed above.  The special features of Shell mode include
the directory tracking feature, and a few user commands.
Dave Love's avatar
#  
Dave Love committed
849 850 851 852 853 854 855 856 857

  Other Emacs features that use variants of Comint mode include GUD
(@pxref{Debuggers}) and @kbd{M-x run-lisp} (@pxref{External Lisp}).

@findex comint-run
  You can use @kbd{M-x comint-run} to execute any program of your choice
in a subprocess using unmodified Comint mode---without the
specializations of Shell mode.

858 859 860 861 862 863
@node Shell Prompts
@subsection Shell Prompts

@cindex prompt, shell
  A prompt is text output by a program to show that it is ready to
accept new user input.  Normally, Comint mode (and thus Shell mode)
Chong Yidong's avatar
Chong Yidong committed
864 865 866 867 868 869 870 871 872 873 874 875 876 877 878 879 880 881 882 883 884 885 886 887 888 889 890 891 892
automatically figures out part of the buffer is a prompt, based on the
output of the subprocess.  (Specifically, it assumes that any received
output line which doesn't end with a newline is a prompt.)

  Comint mode divides the buffer into two types of @dfn{fields}: input
fields (where user input is typed) and output fields (everywhere
else).  Prompts are part of the output fields.  Most Emacs motion
commands do not cross field boundaries, unless they move over multiple
lines.  For instance, when point is in the input field on a shell
command line, @kbd{C-a} puts point at the beginning of the input
field, after the prompt.  Internally, the fields are implemented using
the @code{field} text property (@pxref{Text Properties,,, elisp, the
Emacs Lisp Reference Manual}).

@vindex comint-use-prompt-regexp
@vindex shell-prompt-pattern
  If you change the variable @code{comint-use-prompt-regexp} to a
non-@code{nil} value, then Comint mode recognize prompts using a
regular expression (@pxref{Regexps}).  In Shell mode, the regular
expression is specified by the variable @code{shell-prompt-pattern}.
The default value of @code{comint-use-prompt-regexp} is @code{nil},
because this method for recognizing prompts is unreliable, but you may
want to set it to a non-@code{nil} value in unusual circumstances.  In
that case, Emacs does not divide the Comint buffer into fields, so the
general motion commands behave as they normally do in buffers without
special text properties.  However, you can use the paragraph motion
commands to conveniently navigate the buffer (@pxref{Paragraphs}); in
Shell mode, Emacs uses @code{shell-prompt-pattern} as paragraph
boundaries.
893

Dave Love's avatar
#  
Dave Love committed
894 895 896 897
@node Shell History
@subsection Shell Command History

  Shell buffers support three ways of repeating earlier commands.  You
898 899 900 901 902 903
can use keys like those used for the minibuffer history; these work
much as they do in the minibuffer, inserting text from prior commands
while point remains always at the end of the buffer.  You can move
through the buffer to previous inputs in their original place, then
resubmit them or copy them to the end.  Or you can use a
@samp{!}-style history reference.
Dave Love's avatar
#  
Dave Love committed
904 905 906 907 908 909 910 911 912 913 914 915 916 917

@menu
* Ring: Shell Ring.             Fetching commands from the history list.
* Copy: Shell History Copying.  Moving to a command and then copying it.
* History References::          Expanding @samp{!}-style history references.
@end menu

@node Shell Ring
@subsubsection Shell History Ring

@table @kbd
@findex comint-previous-input
@kindex M-p @r{(Shell mode)}
@item M-p
918
@itemx C-@key{UP}
Dave Love's avatar
#  
Dave Love committed
919 920 921 922 923
Fetch the next earlier old shell command.

@kindex M-n @r{(Shell mode)}
@findex comint-next-input
@item M-n
924
@itemx C-@key{DOWN}
Dave Love's avatar
#  
Dave Love committed
925 926 927
Fetch the next later old shell command.

@kindex M-r @r{(Shell mode)}
928 929 930
@findex comint-history-isearch-backward-regexp
@item M-r
Begin an incremental regexp search of old shell commands.
Dave Love's avatar
#  
Dave Love committed
931

932 933
@item C-c C-x
@kindex C-c C-x @r{(Shell mode)}
Dave Love's avatar
#  
Dave Love committed
934 935
@findex comint-get-next-from-history
Fetch the next subsequent command from the history.
936

937 938
@item C-c .
@kindex C-c . @r{(Shell mode)}
939 940
@findex comint-input-previous-argument
Fetch one argument from an old shell command.
941 942 943 944 945 946

@item C-c C-l
@kindex C-c C-l @r{(Shell mode)}
@findex comint-dynamic-list-input-ring
Display the buffer's history of shell commands in another window
(@code{comint-dynamic-list-input-ring}).
Dave Love's avatar
#  
Dave Love committed
947 948
@end table

Chong Yidong's avatar
Chong Yidong committed
949 950 951 952 953 954
  Shell buffers provide a history of previously entered shell
commands.  To reuse shell commands from the history, use the editing
commands @kbd{M-p}, @kbd{M-n}, @kbd{M-r} and @kbd{M-s}.  These work
just like the minibuffer history commands (@pxref{Minibuffer
History}), except that they operate within the Shell buffer rather
than the minibuffer.
Dave Love's avatar
#  
Dave Love committed
955

956 957 958 959 960 961 962
  @kbd{M-p} fetches an earlier shell command to the end of the shell
buffer.  Successive use of @kbd{M-p} fetches successively earlier
shell commands, each replacing any text that was already present as
potential shell input.  @kbd{M-n} does likewise except that it finds
successively more recent shell commands from the buffer.
@kbd{C-@key{UP}} works like @kbd{M-p}, and @kbd{C-@key{DOWN}} like
@kbd{M-n}.
Dave Love's avatar
#  
Dave Love committed
963

964 965 966 967 968 969 970 971 972
  The history search command @kbd{M-r} begins an incremental regular
expression search of previous shell commands.  After typing @kbd{M-r},
start typing the desired string or regular expression; the last
matching shell command will be displayed in the current line.
Incremental search commands have their usual effects---for instance,
@kbd{C-s} and @kbd{C-r} search forward and backward for the next match
(@pxref{Incremental Search}).  When you find the desired input, type
@key{RET} to terminate the search.  This puts the input in the command
line.  Any partial input you were composing before navigating the
973 974
history list is restored when you go to the beginning or end of the
history ring.
Dave Love's avatar
#  
Dave Love committed
975 976 977 978 979 980 981 982 983

  Often it is useful to reexecute several successive shell commands that
were previously executed in sequence.  To do this, first find and
reexecute the first command of the sequence.  Then type @kbd{C-c C-x};
that will fetch the following command---the one that follows the command
you just repeated.  Then type @key{RET} to reexecute this command.  You
can reexecute several successive commands by typing @kbd{C-c C-x
@key{RET}} over and over.

984 985 986 987 988 989 990 991 992
  The command @kbd{C-c .}@: (@code{comint-input-previous-argument})
copies an individual argument from a previous command, like @kbd{ESC
.} in Bash.  The simplest use copies the last argument from the
previous shell command.  With a prefix argument @var{n}, it copies the
@var{n}th argument instead.  Repeating @kbd{C-c .} copies from an
earlier shell command instead, always using the same value of @var{n}
(don't give a prefix argument when you repeat the @kbd{C-c .}
command).

Dave Love's avatar
#  
Dave Love committed
993 994 995 996 997 998 999
  These commands get the text of previous shell commands from a special
history list, not from the shell buffer itself.  Thus, editing the shell
buffer, or even killing large parts of it, does not affect the history
that these commands access.

@vindex shell-input-ring-file-name
  Some shells store their command histories in files so that you can
1000
refer to commands from previous shell sessions.  Emacs reads
Dave Love's avatar
#  
Dave Love committed
1001 1002 1003 1004 1005 1006 1007 1008 1009 1010 1011 1012 1013 1014 1015 1016 1017 1018 1019
the command history file for your chosen shell, to initialize its own
command history.  The file name is @file{~/.bash_history} for bash,
@file{~/.sh_history} for ksh, and @file{~/.history} for other shells.

@node Shell History Copying
@subsubsection Shell History Copying

@table @kbd
@kindex C-c C-p @r{(Shell mode)}
@findex comint-previous-prompt
@item C-c C-p
Move point to the previous prompt (@code{comint-previous-prompt}).

@kindex C-c C-n @r{(Shell mode)}
@findex comint-next-prompt
@item C-c C-n
Move point to the following prompt (@code{comint-next-prompt}).

@kindex C-c RET @r{(Shell mode)}
1020
@findex comint-copy-old-input
Dave Love's avatar
#  
Dave Love committed
1021
@item C-c @key{RET}
1022 1023 1024 1025 1026 1027
Copy the input command at point, inserting the copy at the end of the
buffer (@code{comint-copy-old-input}).  This is useful if you move
point back to a previous command.  After you copy the command, you can
submit the copy as input with @key{RET}.  If you wish, you can edit
the copy before resubmitting it.  If you use this command on an output
line, it copies that line to the end of the buffer.
1028 1029

@item Mouse-2
1030 1031 1032 1033 1034
If @code{comint-use-prompt-regexp} is @code{nil} (the default), copy
the old input command that you click on, inserting the copy at the end
of the buffer (@code{comint-insert-input}).  If
@code{comint-use-prompt-regexp} is non-@code{nil}, or if the click is
not over old input, just yank as usual.
Dave Love's avatar
#  
Dave Love committed
1035 1036 1037
@end table

  Moving to a previous input and then copying it with @kbd{C-c
1038 1039 1040 1041 1042 1043
@key{RET}} or @kbd{Mouse-2} produces the same results---the same
buffer contents---that you would get by using @kbd{M-p} enough times
to fetch that previous input from the history list.  However, @kbd{C-c
@key{RET}} copies the text from the buffer, which can be different
from what is in the history list if you edit the input text in the
buffer after it has been sent.
Dave Love's avatar
#  
Dave Love committed
1044 1045 1046 1047 1048

@node History References
@subsubsection Shell History References
@cindex history reference

1049 1050 1051 1052 1053 1054 1055 1056 1057 1058 1059 1060 1061 1062 1063 1064 1065 1066 1067 1068
  Various shells including csh and bash support @dfn{history
references} that begin with @samp{!} and @samp{^}.  Shell mode
recognizes these constructs, and can perform the history substitution
for you.

  If you insert a history reference and type @key{TAB}, this searches
the input history for a matching command, performs substitution if
necessary, and places the result in the buffer in place of the history
reference.  For example, you can fetch the most recent command
beginning with @samp{mv} with @kbd{! m v @key{TAB}}.  You can edit the
command if you wish, and then resubmit the command to the shell by
typing @key{RET}.

@vindex comint-input-autoexpand
@findex comint-magic-space
  Shell mode can optionally expand history references in the buffer
when you send them to the shell.  To request this, set the variable
@code{comint-input-autoexpand} to @code{input}.  You can make
@key{SPC} perform history expansion by binding @key{SPC} to the
command @code{comint-magic-space}.
Dave Love's avatar
#  
Dave Love committed
1069

1070
  Shell mode recognizes history references when they follow a prompt.
1071
@xref{Shell Prompts}, for how Shell mode recognizes prompts.
1072 1073 1074 1075

@node Directory Tracking
@subsection Directory Tracking
@cindex directory tracking
Dave Love's avatar
#  
Dave Love committed
1076

1077 1078 1079 1080
@vindex shell-pushd-regexp
@vindex shell-popd-regexp
@vindex shell-cd-regexp
  Shell mode keeps track of @samp{cd}, @samp{pushd} and @samp{popd}
Chong Yidong's avatar
Chong Yidong committed
1081 1082 1083 1084
commands given to the subshell, in order to keep the Shell buffer's
default directory (@pxref{File Names}) the same as the shell's working
directory.  It recognizes these commands by examining lines of input
that you send.
Dave Love's avatar
#  
Dave Love committed
1085

1086
  If you use aliases for these commands, you can tell Emacs to
Chong Yidong's avatar
Chong Yidong committed
1087 1088 1089 1090 1091 1092 1093
recognize them also, by setting the variables
@code{shell-pushd-regexp}, @code{shell-popd-regexp}, and
@code{shell-cd-regexp} to the appropriate regular expressions
(@pxref{Regexps}).  For example, if @code{shell-pushd-regexp} matches
the beginning of a shell command line, that line is regarded as a
@code{pushd} command.  These commands are recognized only at the
beginning of a shell command line.
1094 1095

@findex dirs
Chong Yidong's avatar
Chong Yidong committed
1096 1097 1098 1099 1100
  If Emacs gets confused about changes in the working directory of the
subshell, type @kbd{M-x dirs}.  This command asks the shell for its
working directory and updates the default directory accordingly.  It
works for shells that support the most common command syntax, but may
not work for unusual shells.
1101 1102

@findex dirtrack-mode
Chong Yidong's avatar
Chong Yidong committed
1103 1104 1105 1106 1107 1108 1109 1110 1111 1112 1113 1114
@cindex Dirtrack mode
@cindex mode, Dirtrack
@vindex dirtrack-list
  You can also use Dirtrack mode, a buffer-local minor mode that
implements an alternative method of tracking the shell's working
directory.  To use this method, your shell prompt must contain the
working directory at all times, and you must supply a regular
expression for recognizing which part of the prompt contains the
working directory; see the documentation of the variable
@code{dirtrack-list} for details.  To use Dirtrack mode, type @kbd{M-x
dirtrack-mode} in the Shell buffer, or add @code{dirtrack-mode} to
@code{shell-mode-hook} (@pxref{Hooks}).
Dave Love's avatar
#  
Dave Love committed
1115 1116 1117 1118 1119 1120 1121

@node Shell Options
@subsection Shell Mode Options

@vindex comint-scroll-to-bottom-on-input
  If the variable @code{comint-scroll-to-bottom-on-input} is
non-@code{nil}, insertion and yank commands scroll the selected window
1122
to the bottom before inserting.  The default is @code{nil}.
Dave Love's avatar
#  
Dave Love committed
1123 1124 1125

@vindex comint-scroll-show-maximum-output
  If @code{comint-scroll-show-maximum-output} is non-@code{nil}, then
1126 1127
arrival of output when point is at the end tries to scroll the last
line of text to the bottom line of the window, showing as much useful
1128 1129
text as possible.  (This mimics the scrolling behavior of most
terminals.)  The default is @code{t}.
Dave Love's avatar
#  
Dave Love committed
1130

1131 1132
@vindex comint-move-point-for-output
  By setting @code{comint-move-point-for-output}, you can opt for
Dave Love's avatar
#  
Dave Love committed
1133 1134 1135
having point jump to the end of the buffer whenever output arrives---no
matter where in the buffer point was before.  If the value is
@code{this}, point jumps in the selected window.  If the value is
1136
@code{all}, point jumps in each window that shows the Comint buffer.  If
Dave Love's avatar
#  
Dave Love committed
1137 1138 1139 1140
the value is @code{other}, point jumps in all nonselected windows that
show the current buffer.  The default value is @code{nil}, which means
point does not jump to the end.

1141 1142
@vindex comint-prompt-read-only
  If you set @code{comint-prompt-read-only}, the prompts in the Comint
1143
buffer are read-only.
1144

Dave Love's avatar
#  
Dave Love committed
1145 1146 1147 1148 1149 1150 1151 1152 1153 1154 1155 1156 1157 1158 1159 1160 1161 1162 1163 1164
@vindex comint-input-ignoredups
  The variable @code{comint-input-ignoredups} controls whether successive
identical inputs are stored in the input history.  A non-@code{nil}
value means to omit an input that is the same as the previous input.
The default is @code{nil}, which means to store each input even if it is
equal to the previous input.

@vindex comint-completion-addsuffix
@vindex comint-completion-recexact
@vindex comint-completion-autolist
  Three variables customize file name completion.  The variable
@code{comint-completion-addsuffix} controls whether completion inserts a
space or a slash to indicate a fully completed file or directory name
(non-@code{nil} means do insert a space or slash).
@code{comint-completion-recexact}, if non-@code{nil}, directs @key{TAB}
to choose the shortest possible completion if the usual Emacs completion
algorithm cannot add even a single character.
@code{comint-completion-autolist}, if non-@code{nil}, says to list all
the possible completions whenever completion is not exact.

1165
@vindex shell-completion-execonly
Dave Love's avatar
#  
Dave Love committed
1166
  Command completion normally considers only executable files.
1167
If you set @code{shell-completion-execonly} to @code{nil},
Dave Love's avatar
#  
Dave Love committed
1168 1169 1170 1171 1172 1173 1174 1175 1176 1177 1178 1179 1180
it considers nonexecutable files as well.

@findex shell-pushd-tohome
@findex shell-pushd-dextract
@findex shell-pushd-dunique
  You can configure the behavior of @samp{pushd}.  Variables control
whether @samp{pushd} behaves like @samp{cd} if no argument is given
(@code{shell-pushd-tohome}), pop rather than rotate with a numeric
argument (@code{shell-pushd-dextract}), and only add directories to the
directory stack if they are not already on it
(@code{shell-pushd-dunique}).  The values you choose should match the
underlying shell, of course.

Dave Love's avatar
Dave Love committed
1181
@node Terminal emulator
1182
@subsection Emacs Terminal Emulator
Dave Love's avatar
Dave Love committed
1183 1184
@findex term

1185 1186 1187 1188
  To run a subshell in a terminal emulator, use @kbd{M-x term}.  This
creates (or reuses) a buffer named @samp{*terminal*}, and runs a
subshell with input coming from your keyboard, and output going to
that buffer.
1189 1190

  The terminal emulator uses Term mode, which has two input modes.  In
Chong Yidong's avatar
Chong Yidong committed
1191
line mode, Term basically acts like Shell mode (@pxref{Shell Mode}).
Dave Love's avatar
Dave Love committed
1192

Chong Yidong's avatar
Chong Yidong committed
1193 1194
  In char mode, each character is sent directly to the subshell, as
``terminal input.''  Any ``echoing'' of your input is the
1195 1196
responsibility of the subshell.  The sole exception is the terminal
escape character, which by default is @kbd{C-c} (@pxref{Term Mode}).
Dave Love's avatar
Dave Love committed
1197 1198 1199
Any ``terminal output'' from the subshell goes into the buffer,
advancing point.

1200 1201 1202 1203 1204 1205 1206 1207 1208 1209
  Some programs (such as Emacs itself) need to control the appearance
on the terminal screen in detail.  They do this by sending special
control codes.  The exact control codes needed vary from terminal to
terminal, but nowadays most terminals and terminal emulators
(including @code{xterm}) understand the ANSI-standard (VT100-style)
escape sequences.  Term mode recognizes these escape sequences, and
handles each one appropriately, changing the buffer so that the
appearance of the window matches what it would be on a real terminal.
You can actually run Emacs inside an Emacs Term window.

Chong Yidong's avatar
Chong Yidong committed
1210 1211
  You can also Term mode to communicate with a device connected to a
serial port.  @xref{Serial Terminal}.
1212 1213

  The file name used to load the subshell is determined the same way
1214
as for Shell mode.  To make multiple terminal emulators, rename the
1215
buffer @samp{*terminal*} to something different using @kbd{M-x
1216 1217 1218 1219 1220 1221
rename-uniquely}, just as with Shell mode.

  Unlike Shell mode, Term mode does not track the current directory by
examining your input.  But some shells can tell Term what the current
directory is.  This is done automatically by @code{bash} version 1.15
and later.
Dave Love's avatar
Dave Love committed
1222 1223 1224 1225 1226 1227

@node Term Mode
@subsection Term Mode
@cindex Term mode
@cindex mode, Term

1228
  The terminal emulator uses Term mode, which has two input modes.  In
Chong Yidong's avatar
Chong Yidong committed
1229 1230 1231
line mode, Term basically acts like Shell mode (@pxref{Shell Mode}).
In char mode, each character is sent directly to the subshell, except
for the Term escape character, normally @kbd{C-c}.
1232 1233

  To switch between line and char mode, use these commands:
Dave Love's avatar
Dave Love committed
1234 1235

@table @kbd
1236
@kindex C-c C-j @r{(Term mode)}
Chong Yidong's avatar
Chong Yidong committed
1237
@findex term-line-mode
1238
@item C-c C-j
Chong Yidong's avatar
Chong Yidong committed
1239 1240
Switch to line mode (@code{term-line-mode}).  Do nothing if already in
line mode.
Dave Love's avatar
Dave Love committed
1241

1242
@kindex C-c C-k @r{(Term mode)}
Chong Yidong's avatar
Chong Yidong committed
1243
@findex term-char-mode
1244
@item C-c C-k
Chong Yidong's avatar
Chong Yidong committed
1245 1246
Switch to char mode (@code{term-char-mode}).  Do nothing if already in
char mode.
Dave Love's avatar
Dave Love committed
1247 1248
@end table

1249 1250
  The following commands are only available in char mode:

Dave Love's avatar
Dave Love committed
1251 1252 1253 1254
@table @kbd
@item C-c C-c
Send a literal @key{C-c} to the sub-shell.

1255 1256 1257 1258
@item C-c @var{char}
This is equivalent to @kbd{C-x @var{char}} in normal Emacs.  For
example, @kbd{C-c o} invokes the global binding of @kbd{C-x o}, which
is normally @samp{other-window}.
Dave Love's avatar
Dave Love committed
1259 1260
@end table

Chong Yidong's avatar
Chong Yidong committed
1261 1262 1263
@cindex paging in Term mode
  Term mode has a page-at-a-time feature.  When enabled, it makes
output pause at the end of each screenful:
Dave Love's avatar
Dave Love committed
1264 1265 1266 1267 1268

@table @kbd
@kindex C-c C-q @r{(Term mode)}
@findex term-pager-toggle
@item C-c C-q
1269
Toggle the page-at-a-time feature.  This command works in both line
Chong Yidong's avatar
Chong Yidong committed
1270 1271 1272 1273 1274 1275
and char modes.  When the feature is enabled, the mode-line displays
the word @samp{page}, and each time Term receives more than a
screenful of output, it pauses and displays @samp{**MORE**} in the
mode-line.  Type @key{SPC} to display the next screenful of output, or
@kbd{?} to see your other options.  The interface is similar to the
@code{more} program.
Dave Love's avatar
Dave Love committed
1276 1277
@end table

Dave Love's avatar
#  
Dave Love committed
1278 1279 1280 1281 1282 1283 1284
@node Remote Host
@subsection Remote Host Shell
@cindex remote host
@cindex connecting to remote host
@cindex Telnet