misc.texi 104 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-2014 Free Software
3
@c 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
  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}.

56
  The @dfn{group buffer} contains a list of article sources (e.g.,
57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80
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
@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
95
by the @env{NNTPSERVER} environment variable.
96 97 98 99 100 101 102 103 104 105 106 107

  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
Toggle the subscription status of the group on the current line
169
(i.e., turn a subscribed group into an unsubscribed group, or vice
170 171
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

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?

414 415 416 417
  The most convenient way is to set the optimal slice by using
BoundingBox information automatically determined from the document by
typing @kbd{s b} (@code{doc-view-set-slice-using-mouse}).

418 419 420 421 422
@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.

423 424
@node DocView Conversion
@subsection DocView Conversion
425 426 427

@vindex doc-view-cache-directory
@findex doc-view-clear-cache
428
  For efficiency, DocView caches the images produced by @command{gs}.
429 430 431 432 433 434
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
435 436 437
  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}
438 439 440 441
(@code{doc-view-kill-proc}).  The command @kbd{k}
(@code{doc-view-kill-proc-and-buffer}) kills the converter process and
the DocView buffer.

Rüdiger Sonderfeld's avatar
Rüdiger Sonderfeld committed
442 443 444 445 446 447 448 449 450 451 452 453
@node EWW
@section Web Browsing with EWW

@findex eww
@findex eww-open-file
  @dfn{EWW}, the Emacs Web Wowser, is a web browser package for Emacs.
It allows browsing URLs within an Emacs buffer.  The command @kbd{M-x
eww} can be used to open a URL or search the web.  A file can be
opened using the command @kbd{M-x eww-open-file}.  EWW can be used as
web browser for @code{browse-url}, see @ref{Browse-URL}.  For full
details, see @ref{Top, EWW,, eww, The Emacs Web Wowser Manual}.

454
@node Shell
Dave Love's avatar
#  
Dave Love committed
455 456 457 458
@section Running Shell Commands from Emacs
@cindex subshell
@cindex shell commands

459 460 461
  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
462 463
emulator window.

Dave Love's avatar
#  
Dave Love committed
464 465
@table @kbd
@item M-! @var{cmd} @key{RET}
Chong Yidong's avatar
Chong Yidong committed
466
Run the shell command @var{cmd} and display the output
Dave Love's avatar
#  
Dave Love committed
467 468
(@code{shell-command}).
@item M-| @var{cmd} @key{RET}
Chong Yidong's avatar
Chong Yidong committed
469
Run the shell command @var{cmd} with region contents as input;
Dave Love's avatar
#  
Dave Love committed
470 471
optionally replace the region with the output
(@code{shell-command-on-region}).
472
@item M-& @var{cmd} @key{RET}
Chong Yidong's avatar
Chong Yidong committed
473 474
Run the shell command @var{cmd} asynchronously, and display the output
(@code{async-shell-command}).
Dave Love's avatar
#  
Dave Love committed
475
@item M-x shell
Chong Yidong's avatar
Chong Yidong committed
476 477
Run a subshell with input and output through an Emacs buffer.  You can
then give commands interactively.
Dave Love's avatar
Dave Love committed
478
@item M-x term
Chong Yidong's avatar
Chong Yidong committed
479 480 481
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
482 483
@end table

484 485 486 487 488 489 490 491 492
@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
493
  @kbd{M-x eshell} invokes a shell implemented entirely in Emacs.  It
Chong Yidong's avatar
Chong Yidong committed
494 495 496 497 498 499 500
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
501

Dave Love's avatar
#  
Dave Love committed
502 503 504 505
@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.
506
* Shell Prompts::          Two ways to recognize shell prompts.
Dave Love's avatar
#  
Dave Love committed
507
* History: Shell History.  Repeating previous commands in a shell buffer.
508
* Directory Tracking::     Keeping track when the subshell changes directory.
Dave Love's avatar
#  
Dave Love committed
509
* Options: Shell Options.  Options for customizing Shell mode.
Dave Love's avatar
Dave Love committed
510 511
* 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
512
* Remote Host::            Connecting to another computer.
513
* Serial Terminal::        Connecting to a serial port.
Dave Love's avatar
#  
Dave Love committed
514 515 516 517 518 519 520 521
@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
522
minibuffer and executes it as a shell command, in a subshell made just
Dave Love's avatar
#  
Dave Love committed
523
for that command.  Standard input for the command comes from the null
524 525
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
526
@file{*Shell Command Output*}, displayed in another window (if the
Chong Yidong's avatar
Chong Yidong committed
527 528 529 530 531 532
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.

533
  A numeric argument to @code{shell-command}, e.g., @kbd{M-1 M-!},
Chong Yidong's avatar
Chong Yidong committed
534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556
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{&}.
557
The default output buffer for asynchronous shell commands is named
Chong Yidong's avatar
Chong Yidong committed
558 559 560
@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.
561

562 563 564 565 566 567 568 569
@vindex async-shell-command-buffer
  If you want to run more than one asynchronous shell command at the
same time, they could end up competing for the output buffer.  The
option @code{async-shell-command-buffer} specifies what to do about
this; e.g., whether to rename the pre-existing output buffer, or to
use a different buffer for the new command.  Consult the variable's
documentation for more possibilities.

Dave Love's avatar
#  
Dave Love committed
570 571
@kindex M-|
@findex shell-command-on-region
Chong Yidong's avatar
Chong Yidong committed
572
  @kbd{M-|} (@code{shell-command-on-region}) is like @kbd{M-!}, but
Dave Love's avatar
#  
Dave Love committed
573
passes the contents of the region as the standard input to the shell
Chong Yidong's avatar
Chong Yidong committed
574 575 576 577 578 579 580
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
581
@file{*Shell Command Output*} buffer.
582

Dave Love's avatar
#  
Dave Love committed
583
@vindex shell-file-name
Chong Yidong's avatar
Chong Yidong committed
584 585
  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
586
@env{SHELL} environment variable when Emacs is started.  If the file
587 588
name is relative, Emacs searches the directories listed in
@code{exec-path} (@pxref{Shell}).
Dave Love's avatar
#  
Dave Love committed
589 590

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

@vindex shell-command-default-error-buffer
Chong Yidong's avatar
Chong Yidong committed
594 595 596 597
  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
598 599

@node Interactive Shell
Chong Yidong's avatar
Chong Yidong committed
600
@subsection Interactive Subshell
Dave Love's avatar
#  
Dave Love committed
601 602

@findex shell
Chong Yidong's avatar
Chong Yidong committed
603
  To run a subshell interactively, type @kbd{M-x shell}.  This creates
604
(or reuses) a buffer named @file{*shell*}, and runs a shell subprocess
Chong Yidong's avatar
Chong Yidong committed
605 606 607 608 609 610 611 612 613
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
614
time to process it (e.g., while waiting for keyboard input).
Dave Love's avatar
#  
Dave Love committed
615

616 617
@cindex @code{comint-highlight-input} face
@cindex @code{comint-highlight-prompt} face
Chong Yidong's avatar
Chong Yidong committed
618 619 620 621 622 623 624
  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
625
argument (e.g., @kbd{C-u M-x shell}).  Then the command will read a
Chong Yidong's avatar
Chong Yidong committed
626
buffer name, and create (or reuse) a subshell in that buffer.  You can
627 628
also rename the @file{*shell*} buffer using @kbd{M-x rename-uniquely},
then create a new @file{*shell*} buffer using plain @kbd{M-x shell}.
Richard M. Stallman's avatar
Richard M. Stallman committed
629
Subshells in different buffers run independently and in parallel.
Dave Love's avatar
#  
Dave Love committed
630 631

@vindex explicit-shell-file-name
632
@cindex environment variables for subshells
Gerd Moellmann's avatar
Gerd Moellmann committed
633 634
@cindex @env{ESHELL} environment variable
@cindex @env{SHELL} environment variable
Chong Yidong's avatar
Chong Yidong committed
635 636 637 638 639 640 641
  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
642

643 644 645 646
  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
647 648
@file{~/.emacs_bash}.  If this file is not found, Emacs tries with
@file{~/.emacs.d/init_@var{shellname}.sh}.
649

Dave Love's avatar
#  
Dave Love committed
650
  To specify a coding system for the shell, you can use the command
Richard M. Stallman's avatar
Richard M. Stallman committed
651 652 653 654
@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
655

656
@cindex @env{INSIDE_EMACS} environment variable
657
@cindex @env{EMACS} environment variable
Chong Yidong's avatar
Chong Yidong committed
658 659
  Emacs sets the environment variable @env{INSIDE_EMACS} in the
subshell to @samp{@var{version},comint}, where @var{version} is the
660
Emacs version (e.g., @samp{24.1}).  Programs can check this variable
Chong Yidong's avatar
Chong Yidong committed
661 662 663 664 665
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
666 667 668 669 670 671

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

Chong Yidong's avatar
Chong Yidong committed
672 673 674 675 676
  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
677 678 679 680 681

@table @kbd
@item @key{RET}
@kindex RET @r{(Shell mode)}
@findex comint-send-input
Chong Yidong's avatar
Chong Yidong committed
682 683 684 685 686 687
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
688 689 690

@item @key{TAB}
@kindex TAB @r{(Shell mode)}
Chong Yidong's avatar
Chong Yidong committed
691
@findex completion-at-point
692
@cindex shell completion
Chong Yidong's avatar
Chong Yidong committed
693 694 695 696 697
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}).
698
For options controlling the completion, @pxref{Shell Options}.
Dave Love's avatar
#  
Dave Love committed
699 700 701 702

@item M-?
@kindex M-? @r{(Shell mode)}
@findex comint-dynamic-list-filename@dots{}
Chong Yidong's avatar
Chong Yidong committed
703 704
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
705 706 707 708

@item C-d
@kindex C-d @r{(Shell mode)}
@findex comint-delchar-or-maybe-eof
709
Either delete a character or send @acronym{EOF}
Dave Love's avatar
#  
Dave Love committed
710
(@code{comint-delchar-or-maybe-eof}).  Typed at the end of the shell
Chong Yidong's avatar
Chong Yidong committed
711 712
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
713 714 715

@item C-c C-a
@kindex C-c C-a @r{(Shell mode)}
716
@findex comint-bol-or-process-mark
Dave Love's avatar
#  
Dave Love committed
717
Move to the beginning of the line, but after the prompt if any
718 719 720 721 722 723
(@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
724 725 726 727 728 729 730 731 732 733 734 735

@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
736 737
(@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
738 739 740 741 742 743 744 745 746 747 748 749 750 751 752 753 754 755 756 757 758 759 760 761 762 763 764 765

@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
766 767 768
@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
769
out lots of output that just gets in the way.
Miles Bader's avatar
Miles Bader committed
770 771 772 773 774 775 776 777

@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
778 779 780 781 782 783 784 785 786 787 788 789 790 791 792 793 794 795 796 797 798 799 800 801 802 803 804 805 806 807

@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
808 809
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
810 811 812 813 814 815 816

@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.

817
Please note that Emacs will not echo passwords by default.  If you
Xue Fuqiao's avatar
Xue Fuqiao committed
818 819
really want them to be echoed, evaluate (@pxref{Lisp Eval}) the
following Lisp expression:
Dave Love's avatar
#  
Dave Love committed
820 821

@example
822 823
(remove-hook 'comint-output-filter-functions
             'comint-watch-for-password-prompt)
Dave Love's avatar
#  
Dave Love committed
824 825 826 827 828 829 830 831 832 833 834 835 836 837 838 839 840 841 842 843 844 845 846 847 848 849 850 851 852 853 854 855 856 857 858 859 860 861 862 863
@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
864 865
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
866 867 868 869 870 871 872 873 874

  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.

875 876 877 878 879 880
@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
881 882 883 884 885 886 887 888 889 890 891 892 893 894 895 896 897 898 899 900 901 902 903 904 905 906 907 908 909
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.
910

Dave Love's avatar
#  
Dave Love committed
911 912 913 914
@node Shell History
@subsection Shell Command History

  Shell buffers support three ways of repeating earlier commands.  You
915 916 917 918 919 920
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
921 922 923 924 925 926 927 928 929 930 931 932 933 934

@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
935
@itemx C-@key{UP}
Dave Love's avatar
#  
Dave Love committed
936 937 938 939 940
Fetch the next earlier old shell command.

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

@kindex M-r @r{(Shell mode)}
945 946 947
@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
948

949 950
@item C-c C-x
@kindex C-c C-x @r{(Shell mode)}
Dave Love's avatar
#  
Dave Love committed
951 952
@findex comint-get-next-from-history
Fetch the next subsequent command from the history.
953

954 955
@item C-c .
@kindex C-c . @r{(Shell mode)}
956 957
@findex comint-input-previous-argument
Fetch one argument from an old shell command.
958 959 960 961 962 963

@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
964 965
@end table

Chong Yidong's avatar
Chong Yidong committed
966 967 968 969 970 971
  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
972

973 974 975 976 977 978 979
  @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
980

981 982 983 984 985 986 987 988 989
  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
990 991
history list is restored when you go to the beginning or end of the
history ring.
Dave Love's avatar
#  
Dave Love committed
992 993 994 995 996 997 998 999 1000

  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.

1001 1002 1003 1004 1005 1006 1007 1008 1009
  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
1010 1011 1012 1013 1014 1015 1016
  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
1017
refer to commands from previous shell sessions.  Emacs reads
Dave Love's avatar
#  
Dave Love committed
1018 1019 1020 1021 1022 1023 1024 1025 1026 1027 1028 1029 1030 1031 1032 1033 1034 1035 1036
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)}
1037
@findex comint-copy-old-input
Dave Love's avatar
#  
Dave Love committed
1038
@item C-c @key{RET}
1039 1040 1041 1042 1043 1044
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.
1045 1046

@item Mouse-2
1047 1048 1049 1050 1051
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
1052 1053 1054
@end table

  Moving to a previous input and then copying it with @kbd{C-c
1055 1056 1057 1058 1059 1060
@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
1061 1062 1063 1064 1065

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

1066 1067 1068 1069 1070 1071 1072 1073 1074 1075 1076 1077 1078 1079 1080 1081 1082 1083 1084 1085
  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
1086

1087
  Shell mode recognizes history references when they follow a prompt.
1088
@xref{Shell Prompts}, for how Shell mode recognizes prompts.
1089 1090 1091 1092

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

1094 1095 1096 1097
@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
1098 1099 1100 1101
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
1102

1103
  If you use aliases for these commands, you can tell Emacs to
Chong Yidong's avatar
Chong Yidong committed
1104 1105 1106 1107 1108 1109 1110
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.
1111 1112

@findex dirs
Chong Yidong's avatar
Chong Yidong committed
1113 1114 1115 1116 1117
  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.
1118 1119

@findex dirtrack-mode
Chong Yidong's avatar
Chong Yidong committed
1120 1121 1122 1123 1124 1125 1126 1127 1128 1129 1130 1131
@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
1132 1133 1134 1135 1136 1137 1138

@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
1139
to the bottom before inserting.  The default is @code{nil}.
Dave Love's avatar
#  
Dave Love committed
1140 1141 1142

@vindex comint-scroll-show-maximum-output
  If @code{comint-scroll-show-maximum-output} is non-@code{nil}, then
1143 1144
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
1145 1146
text as possible.  (This mimics the scrolling behavior of most
terminals.)  The default is @code{t}.
Dave Love's avatar
#  
Dave Love committed
1147

1148 1149
@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
1150 1151 1152
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
1153
@code{all}, point jumps in each window that shows the Comint buffer.  If
Dave Love's avatar
#  
Dave Love committed
1154 1155 1156 1157
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.

1158 1159
@vindex comint-prompt-read-only
  If you set @code{comint-prompt-read-only}, the prompts in the Comint
1160
buffer are read-only.
1161

Dave Love's avatar
#  
Dave Love committed
1162 1163 1164 1165 1166 1167 1168 1169 1170 1171 1172 1173 1174 1175 1176 1177 1178 1179 1180 1181
@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.

1182
@vindex shell-completion-execonly
Dave Love's avatar
#  
Dave Love committed
1183
  Command completion normally considers only executable files.
1184
If you set @code{shell-completion-execonly} to @code{nil},
Dave Love's avatar
#  
Dave Love committed
1185 1186
it considers nonexecutable files as well.

1187 1188 1189 1190 1191 1192 1193 1194 1195 1196 1197 1198 1199 1200
@vindex shell-completion-fignore
@vindex comint-completion-fignore
The variable @code{shell-completion-fignore} specifies a list of file
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
related Comint modes use the variable @code{comint-completion-fignore}
instead.

@findex shell-dynamic-complete-command
Some implementation details of the shell command completion may also be found
in the lisp documentation of the @code{shell-dynamic-complete-command}
function.

Dave Love's avatar
#  
Dave Love committed
1201 1202 1203 1204 1205 1206 1207 1208 1209 1210 1211
@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
1212
@node Terminal emulator
1213
@subsection Emacs Terminal Emulator
Dave Love's avatar
Dave Love committed
1214 1215
@findex term

1216 1217
  To run a subshell in a text terminal emulator, use @kbd{M-x term}.
This creates (or reuses) a buffer named @file{*terminal*}, and runs a
1218 1219
subshell with input coming from your keyboard, and output going to
that buffer.
1220

1221 1222
@cindex line mode @r{(terminal emulator)}
@cindex char mode @r{(terminal emulator)}
1223
  The terminal emulator uses Term mode, which has two input modes.  In
1224 1225 1226 1227 1228 1229 1230
@dfn{line mode}, Term basically acts like Shell mode (@pxref{Shell
Mode}).  In @dfn{char mode}, each character is sent directly to the
subshell, as terminal input; the sole exception is the terminal escape
character, which by default is @kbd{C-c} (@pxref{Term Mode}).  Any
echoing of your input is the responsibility of the subshell; any
terminal output from the subshell goes into the buffer, advancing
point.
Dave Love's avatar
Dave Love committed
1231

1232
  Some programs (such as Emacs itself) need to control the appearance
1233 1234 1235 1236 1237 1238
of the terminal screen in detail.  They do this by emitting special
control codes.  Term mode recognizes and handles ANSI-standard
VT100-style escape sequences, which are accepted by most modern
terminals, including @command{xterm}.  (Hence, you can actually run
Emacs inside an Emacs Term window.)

1239
  The @code{term} face specifies the default appearance of text
1240 1241 1242 1243 1244 1245 1246 1247 1248
in the terminal emulator (the default is the same appearance as the
@code{default} face).  When terminal control codes are used to change
the appearance of text, these are represented in the terminal emulator
by the faces @code{term-color-black}, @code{term-color-red},
@code{term-color-green}, @code{term-color-yellow}
@code{term-color-blue}, @code{term-color-magenta},
@code{term-color-cyan}, @code{term-color-white},
@code{term-color-underline}, and @code{term-color-bold}.
@xref{Faces}.
1249

Chong Yidong's avatar
Chong Yidong committed
1250 1251
  You can also Term mode to communicate with a device connected to a
serial port.  @xref{Serial Terminal}.
1252 1253

  The file name used to load the subshell is determined the same way
1254
as for Shell mode.  To make multiple terminal emulators, rename the
1255
buffer @file{*terminal*} to something different using @kbd{M-x