This is ../../info/emacs, produced by makeinfo version 4.11 from emacs.texi. This is the Sixteenth edition of the `GNU Emacs Manual', updated for Emacs version 23.2. Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 Free Software Foundation, Inc. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with the Invariant Sections being "The GNU Manifesto," "Distribution" and "GNU GENERAL PUBLIC LICENSE," with the Front-Cover texts being "A GNU Manual," and with the Back-Cover Texts as in (a) below. A copy of the license is included in the section entitled "GNU Free Documentation License." (a) The FSF's Back-Cover Text is: "You have the freedom to copy and modify this GNU manual. Buying copies from the FSF supports it in developing GNU and promoting software freedom." INFO-DIR-SECTION Emacs START-INFO-DIR-ENTRY * Emacs: (emacs). The extensible self-documenting text editor. END-INFO-DIR-ENTRY  File: emacs, Node: Other GDB-UI Buffers, Next: Watch Expressions, Prev: Stack Buffer, Up: GDB Graphical Interface 31.6.5.5 Other Buffers ...................... Input/Output Buffer If the variable `gdb-use-separate-io-buffer' is non-`nil', the program being debugged takes its input and displays its output here. Otherwise it uses the GUD buffer for that. To toggle whether GUD mode uses this buffer, do `M-x gdb-use-separate-io-buffer'. This takes effect when you next restart the program you are debugging. The history and replay commands from Shell mode are available here, as are the commands to send signals to the debugged program. *Note Shell Mode::. Locals Buffer The locals buffer displays the values of local variables of the current frame for simple data types (*note Frame Info: (gdb)Frame Info.). Press or click `Mouse-2' on the value if you want to edit it. Arrays and structures display their type only. With GDB 6.4 or later, move point to their name and press , or alternatively click `Mouse-2' there, to examine their values. With earlier versions of GDB, use `Mouse-2' or on the type description (`[struct/union]' or `[array]'). *Note Watch Expressions::. Registers Buffer The registers buffer displays the values held by the registers (*note Registers: (gdb)Registers.). Press or click `Mouse-2' on a register if you want to edit its value. With GDB 6.4 or later, recently changed register values display with `font-lock-warning-face'. With earlier versions of GDB, you can press to toggle the display of floating point registers (`toggle-gdb-all-registers'). Assembler Buffer The assembler buffer displays the current frame as machine code. An arrow points to the current instruction, and you can set and remove breakpoints as in a source buffer. Breakpoint icons also appear in the fringe or margin. Threads Buffer The threads buffer displays a summary of all threads currently in your program (*note Threads: (gdb)Threads.). Move point to any thread in the list and press to select it (`gdb-threads-select') and display the associated source in the primary source buffer. Alternatively, click `Mouse-2' on a thread to select it. If the locals buffer is visible, its contents update to display the variables that are local in the new thread. When there is more than one main thread and the threads buffer is present, Emacs displays the selected thread number in the mode line of many of the GDB-UI Buffers. Memory Buffer The memory buffer lets you examine sections of program memory (*note Memory: (gdb)Memory.). Click `Mouse-1' on the appropriate part of the header line to change the starting address or number of data items that the buffer displays. Alternatively, use `S' or `N' respectively. Click `Mouse-3' on the header line to select the display format or unit size for these data items. When `gdb-many-windows' is non-`nil', the threads buffer shares its window with the breakpoints buffer, and the locals buffer with the registers buffer. To switch from one to the other click with `Mouse-1' on the relevant button in the header line.  File: emacs, Node: Watch Expressions, Next: Reverse Debugging, Prev: Other GDB-UI Buffers, Up: GDB Graphical Interface 31.6.5.6 Watch Expressions .......................... If you want to see how a variable changes each time your program stops, move point into the variable name and click on the watch icon in the tool bar (`gud-watch') or type `C-x C-a C-w'. If you specify a prefix argument, you can enter the variable name in the minibuffer. Each watch expression is displayed in the speedbar. Complex data types, such as arrays, structures and unions are represented in a tree format. Leaves and simple data types show the name of the expression and its value and, when the speedbar frame is selected, display the type as a tooltip. Higher levels show the name, type and address value for pointers and just the name and type otherwise. Root expressions also display the frame address as a tooltip to help identify the frame in which they were defined. To expand or contract a complex data type, click `Mouse-2' or press on the tag to the left of the expression. Emacs asks for confirmation before expanding the expression if its number of immediate children exceeds the value of the variable `gdb-max-children'. To delete a complex watch expression, move point to the root expression in the speedbar and type `D' (`gdb-var-delete'). To edit a variable with a simple data type, or a simple element of a complex data type, move point there in the speedbar and type (`gdb-edit-value'). Or you can click `Mouse-2' on a value to edit it. Either way, this reads the new value using the minibuffer. If you set the variable `gdb-show-changed-values' to non-`nil' (the default value), Emacs uses `font-lock-warning-face' to highlight values that have recently changed and `shadow' face to make variables which have gone out of scope less noticeable. When a variable goes out of scope you can't edit its value. If the variable `gdb-delete-out-of-scope' is non-`nil' (the default value), Emacs automatically deletes watch expressions which go out of scope. Sometimes, when re-entering the same function, it may be useful to set this value to `nil' so that you don't need to recreate the watch expression. If the variable `gdb-use-colon-colon-notation' is non-`nil', Emacs uses the `FUNCTION::VARIABLE' format. This allows the user to display watch expressions which share the same variable name. The default value is `nil'. To automatically raise the speedbar every time the display of watch expressions updates, set `gdb-speedbar-auto-raise' to non-`nil'. This can be useful if you are debugging with a full screen Emacs frame.  File: emacs, Node: Reverse Debugging, Prev: Watch Expressions, Up: GDB Graphical Interface 31.6.5.7 Reverse Debugging .......................... The GDB tool bar shares many buttons with the other GUD debuggers for tasks like stepping and printing expressions. It also has a further set of buttons that allow reverse debugging (*note Process Record and Replay: (gdb)Process Record and Replay.). This is useful when it takes a long time to reproduce the conditions where your program fails or for transient problems, like race conditions in multi-threaded programs, where a failure might otherwise be hard to reproduce. To use reverse debugging, set a breakpoint slightly before the location of interest and run your program to that point. Enable process recording by clicking on the record button. At this point, a new set of buttons appear. These buttons allow program execution in the reverse direction. Run your program over the code where the problem occurs, and then use the new set of buttons to retrace your steps, examine values, and analyze the problem. When analysis is complete, turn off process recording by clicking on the record button again.  File: emacs, Node: Executing Lisp, Next: Lisp Libraries, Prev: Debuggers, Up: Building 31.7 Executing Lisp Expressions =============================== Emacs has several different major modes for Lisp and Scheme. They are the same in terms of editing commands, but differ in the commands for executing Lisp expressions. Each mode has its own purpose. Emacs-Lisp mode The mode for editing source files of programs to run in Emacs Lisp. This mode defines `C-M-x' to evaluate the current defun. *Note Lisp Libraries::. Lisp Interaction mode The mode for an interactive session with Emacs Lisp. It defines `C-j' to evaluate the sexp before point and insert its value in the buffer. *Note Lisp Interaction::. Lisp mode The mode for editing source files of programs that run in Lisps other than Emacs Lisp. This mode defines `C-M-x' to send the current defun to an inferior Lisp process. *Note External Lisp::. Inferior Lisp mode The mode for an interactive session with an inferior Lisp process. This mode combines the special features of Lisp mode and Shell mode (*note Shell Mode::). Scheme mode Like Lisp mode but for Scheme programs. Inferior Scheme mode The mode for an interactive session with an inferior Scheme process. Most editing commands for working with Lisp programs are in fact available globally. *Note Programs::.  File: emacs, Node: Lisp Libraries, Next: Lisp Eval, Prev: Executing Lisp, Up: Building 31.8 Libraries of Lisp Code for Emacs ===================================== Lisp code for Emacs editing commands is stored in files whose names conventionally end in `.el'. This ending tells Emacs to edit them in Emacs-Lisp mode (*note Executing Lisp::). Emacs Lisp code can be compiled into byte-code, which loads faster, takes up less space, and executes faster. *Note Byte Compilation: (elisp)Byte Compilation. By convention, the compiled code for a library goes in a separate file whose name ends in `.elc'. Thus, the compiled code for `foo.el' goes in `foo.elc'. To execute a file of Emacs Lisp code, use `M-x load-file'. This command reads a file name using the minibuffer and then executes the contents of that file as Lisp code. It is not necessary to visit the file first; in any case, this command reads the file as found on disk, not text in an Emacs buffer. Once a file of Lisp code is installed in the Emacs Lisp library directories, users can load it using `M-x load-library'. Programs can load it by calling `load', a more primitive function that is similar but accepts some additional arguments. `M-x load-library' differs from `M-x load-file' in that it searches a sequence of directories and tries three file names in each directory. Suppose your argument is LIB; the three names are `LIB.elc', `LIB.el', and lastly just `LIB'. If `LIB.elc' exists, it is by convention the result of compiling `LIB.el'; it is better to load the compiled file, since it will load and run faster. If `load-library' finds that `LIB.el' is newer than `LIB.elc' file, it issues a warning, because it's likely that somebody made changes to the `.el' file and forgot to recompile it. Nonetheless, it loads `LIB.elc'. This is because people often leave unfinished edits the source file, and don't recompile it until they think it is ready to use. The variable `load-path' specifies the sequence of directories searched by `M-x load-library'. Its value should be a list of strings that are directory names; in addition, `nil' in this list stands for the current default directory. (Generally, it is not a good idea to put `nil' in the list; if you find yourself wishing that `nil' were in the list, most likely what you really want is to do `M-x load-file' this once.) The default value of `load-path' is a list of directories where the Lisp code for Emacs itself is stored. If you have libraries of your own, put them in a single directory and add that directory to `load-path', by adding a line like this to your init file (*note Init File::): (add-to-list 'load-path "/path/to/lisp/libraries") Some commands are "autoloaded": when you run them, Emacs will automatically load the associated library first. For instance, the `compile' and `compilation-mode' commands (*note Compilation::) are autoloaded; if you call either command, Emacs automatically loads the `compile' library. In contrast, the command `recompile' is not autoloaded, so it is unavailable until you load the `compile' library. By default, Emacs refuses to load compiled Lisp files which were compiled with XEmacs, a modified versions of Emacs--they can cause Emacs to crash. Set the variable `load-dangerous-libraries' to `t' if you want to try loading them.  File: emacs, Node: Lisp Eval, Next: Lisp Interaction, Prev: Lisp Libraries, Up: Building 31.9 Evaluating Emacs Lisp Expressions ====================================== Lisp programs intended to be run in Emacs should be edited in Emacs-Lisp mode; this happens automatically for file names ending in `.el'. By contrast, Lisp mode itself is used for editing Lisp programs intended for other Lisp systems. To switch to Emacs-Lisp mode explicitly, use the command `M-x emacs-lisp-mode'. For testing of Lisp programs to run in Emacs, it is often useful to evaluate part of the program as it is found in the Emacs buffer. For example, after changing the text of a Lisp function definition, evaluating the definition installs the change for future calls to the function. Evaluation of Lisp expressions is also useful in any kind of editing, for invoking noninteractive functions (functions that are not commands). `M-:' Read a single Lisp expression in the minibuffer, evaluate it, and print the value in the echo area (`eval-expression'). `C-x C-e' Evaluate the Lisp expression before point, and print the value in the echo area (`eval-last-sexp'). `C-M-x' Evaluate the defun containing or after point, and print the value in the echo area (`eval-defun'). `M-x eval-region' Evaluate all the Lisp expressions in the region. `M-x eval-buffer' Evaluate all the Lisp expressions in the buffer. `M-:' (`eval-expression') is the most basic command for evaluating a Lisp expression interactively. It reads the expression using the minibuffer, so you can execute any expression on a buffer regardless of what the buffer contains. When the expression is evaluated, the current buffer is once again the buffer that was current when `M-:' was typed. In Emacs-Lisp mode, the key `C-M-x' is bound to the command `eval-defun', which parses the defun containing or following point as a Lisp expression and evaluates it. The value is printed in the echo area. This command is convenient for installing in the Lisp environment changes that you have just made in the text of a function definition. `C-M-x' treats `defvar' expressions specially. Normally, evaluating a `defvar' expression does nothing if the variable it defines already has a value. But `C-M-x' unconditionally resets the variable to the initial value specified in the `defvar' expression. `defcustom' expressions are treated similarly. This special feature is convenient for debugging Lisp programs. Typing `C-M-x' on a `defface' expression reinitializes the face according to the `defface' specification. The command `C-x C-e' (`eval-last-sexp') evaluates the Lisp expression preceding point in the buffer, and displays the value in the echo area. It is available in all major modes, not just Emacs-Lisp mode. It does not treat `defvar' specially. When the result of an evaluation is an integer, you can type `C-x C-e' a second time to display the value of the integer result in additional formats (octal, hexadecimal, and character). If `C-x C-e', or `M-:' is given a numeric argument, it inserts the value into the current buffer at point, rather than displaying it in the echo area. The argument's value does not matter. `C-M-x' with a numeric argument instruments the function definition for Edebug (*note Instrumenting for Edebug: (elisp)Instrumenting.). The most general command for evaluating Lisp expressions from a buffer is `eval-region'. `M-x eval-region' parses the text of the region as one or more Lisp expressions, evaluating them one by one. `M-x eval-buffer' is similar but evaluates the entire buffer. This is a reasonable way to install the contents of a file of Lisp code that you are ready to test. Later, as you find bugs and change individual functions, use `C-M-x' on each function that you change. This keeps the Lisp world in step with the source file. The two customizable variables `eval-expression-print-level' and `eval-expression-print-length' control the maximum depth and length of lists to print in the result of the evaluation commands before abbreviating them. `eval-expression-debug-on-error' controls whether evaluation errors invoke the debugger when these commands are used; its default is `t'.  File: emacs, Node: Lisp Interaction, Next: External Lisp, Prev: Lisp Eval, Up: Building 31.10 Lisp Interaction Buffers ============================== When Emacs starts up, it contains a buffer named `*scratch*', which is provided for evaluating Lisp expressions interactively inside Emacs. Its major mode is Lisp Interaction mode. The simplest way to use the `*scratch*' buffer is to insert Lisp expressions and type `C-j' (`eval-print-last-sexp') after each expression. This command reads the Lisp expression before point, evaluates it, and inserts the value in printed representation before point. The result is a complete typescript of the expressions you have evaluated and their values. At startup, the `*scratch*' buffer contains a short message, in the form of a Lisp comment, that explains what it is for. This message is controlled by the variable `initial-scratch-message', which should be either a string or `nil'. If you set it to the empty string, or `nil', the initial message is suppressed. All other commands in Lisp Interaction mode are the same as in Emacs Lisp mode. You can enable Lisp Interaction mode by typing `M-x lisp-interaction-mode'. An alternative way of evaluating Emacs Lisp expressions interactively is to use Inferior Emacs-Lisp mode, which provides an interface rather like Shell mode (*note Shell Mode::) for evaluating Emacs Lisp expressions. Type `M-x ielm' to create an `*ielm*' buffer which uses this mode. For more information see that command's documentation.  File: emacs, Node: External Lisp, Prev: Lisp Interaction, Up: Building 31.11 Running an External Lisp ============================== Emacs has facilities for running programs in other Lisp systems. You can run a Lisp process as an inferior of Emacs, and pass expressions to it to be evaluated. You can also pass changed function definitions directly from the Emacs buffers in which you edit the Lisp programs to the inferior Lisp process. To run an inferior Lisp process, type `M-x run-lisp'. This runs the program named `lisp', the same program you would run by typing `lisp' as a shell command, with both input and output going through an Emacs buffer named `*lisp*'. That is to say, any "terminal output" from Lisp will go into the buffer, advancing point, and any "terminal input" for Lisp comes from text in the buffer. (You can change the name of the Lisp executable file by setting the variable `inferior-lisp-program'.) To give input to Lisp, go to the end of the buffer and type the input, terminated by . The `*lisp*' buffer is in Inferior Lisp mode, which combines the special characteristics of Lisp mode with most of the features of Shell mode (*note Shell Mode::). The definition of to send a line to a subprocess is one of the features of Shell mode. For the source files of programs to run in external Lisps, use Lisp mode. You can switch to this mode with `M-x lisp-mode', and it is used automatically for files whose names end in `.l', `.lsp', or `.lisp'. When you edit a function in a Lisp program you are running, the easiest way to send the changed definition to the inferior Lisp process is the key `C-M-x'. In Lisp mode, this runs the function `lisp-eval-defun', which finds the defun around or following point and sends it as input to the Lisp process. (Emacs can send input to any inferior process regardless of what buffer is current.) Contrast the meanings of `C-M-x' in Lisp mode (for editing programs to be run in another Lisp system) and Emacs-Lisp mode (for editing Lisp programs to be run in Emacs; see *note Lisp Eval::): in both modes it has the effect of installing the function definition that point is in, but the way of doing so is different according to where the relevant Lisp environment is found.  File: emacs, Node: Maintaining, Next: Abbrevs, Prev: Building, Up: Top 32 Maintaining Large Programs ***************************** This chapter describes Emacs features for maintaining large programs. * Menu: * Version Control:: Using version control systems. * Change Log:: Maintaining a change history for your program. * Tags:: Go directly to any function in your program in one command. Tags remembers which file it is in. * EDE:: An integrated development environment for Emacs. * Emerge:: A convenient way of merging two versions of a program.  File: emacs, Node: Version Control, Next: Change Log, Up: Maintaining 32.1 Version Control ==================== A "version control system" is a package that can record multiple versions of a source file, storing information such as the creation time of each version, who created it, and a description of what was changed in that version. The Emacs version control interface is called VC. Its commands work with several different version control systems; currently, it supports GNU Arch, Bazaar, CVS, Git, Mercurial, Monotone, RCS, SCCS/CSSC, and Subversion. Of these, the GNU project distributes CVS, GNU Arch, RCS, and Bazaar. VC is enabled automatically whenever you visit a file that is governed by a version control system. To disable VC entirely, set the customizable variable `vc-handled-backends' to `nil' (*note Customizing VC::). * Menu: * Introduction to VC:: How version control works in general. * VC Mode Line:: How the mode line shows version control status. * Basic VC Editing:: How to edit a file under version control. * Old Revisions:: Examining and comparing old versions. * Secondary VC Commands:: The commands used a little less frequently. * VC Directory Mode:: Listing files managed by version control. * Branches:: Multiple lines of development. * Remote Repositories:: Efficient access to remote CVS servers. * Revision Tags:: Symbolic names for revisions. * Miscellaneous VC:: Various other commands and features of VC. * Customizing VC:: Variables that change VC's behavior.  File: emacs, Node: Introduction to VC, Next: VC Mode Line, Up: Version Control 32.1.1 Introduction to Version Control -------------------------------------- VC allows you to use a version control system from within Emacs, integrating the version control operations smoothly with editing. Though VC cannot completely bridge the gaps between version control systems with widely differing capabilities, it does provide a uniform interface to many version control operations. Regardless of which version control system is in use, you will be able to do basic operations in much the same way. This section provides a general overview of version control, and describes the version control systems that VC supports. You can skip this section if you are already familiar with the version control system you want to use. * Menu: * Why Version Control?:: Understanding the problems it addresses. * Version Control Systems:: Supported version control back-end systems. * VCS Concepts:: Words and concepts related to version control. * Types of Log File:: The VCS log in contrast to the ChangeLog.  File: emacs, Node: Why Version Control?, Next: Version Control Systems, Up: Introduction to VC 32.1.1.1 Understanding the problems it addresses ................................................ Version control systems provide you with three important capabilities: * "Reversibility": the ability to back up to a previous state if you discover that some modification you did was a mistake or a bad idea. * "Concurrency": the ability to have many people modifying the same collection of files knowing that conflicting modifications can be detected and resolved. * "History": the ability to attach historical data to your data, such as explanatory comments about the intention behind each change to it. Even for a programmer working solo, change histories are an important aid to memory; for a multi-person project, they are a vitally important form of communication among developers.  File: emacs, Node: Version Control Systems, Next: VCS Concepts, Prev: Why Version Control?, Up: Introduction to VC 32.1.1.2 Supported Version Control Systems .......................................... VC currently works with many different version control systems or "back ends": * SCCS was the first version control system ever built, and was long ago superseded by more advanced ones. VC compensates for certain features missing in SCCS (e.g., tag names for releases) by implementing them itself. Other VC features, such as multiple branches, are simply unavailable. Since SCCS is non-free, we recommend avoiding it. * CSSC is a free replacement for SCCS. You should use CSSC only if, for some reason, you cannot use a more recent and better-designed version control system. * RCS is the free version control system around which VC was initially built. Almost everything you can do with RCS can be done through VC. However, you cannot use RCS over the network, and it only works at the level of individual files rather than projects. * CVS is the free version control system that was, until recently (circa 2008), used by the majority of free software projects. Nowadays, it is slowly being superseded by newer systems. CVS allows concurrent multi-user development either locally or over the network. It lacks support for atomic commits or file moving/renaming. VC supports all basic editing operations under CVS. For some less common tasks, you still need to call CVS from the command line. Note also that before using CVS you must set up a repository, which is a subject too complex to treat here. * Subversion (SVN) is a free version control system designed to be similar to CVS but without its problems. It supports atomic commits of filesets, and versioning of directories, symbolic links, meta-data, renames, copies, and deletes. * GNU Arch is a version control system designed for distributed work. It differs in many ways from older systems like CVS and RCS. It provides different methods for interoperating between users, support for offline operations, and good branching and merging features. It also supports atomic commits of filesets and file moving/renaming. VC does not support all operations provided by GNU Arch, so you must sometimes invoke it from the command line. * Git is a distributed version control system invented by Linus Torvalds to support development of Linux (his kernel). It supports atomic commits of filesets and file moving/renaming. One significant feature of git is that it largely abolishes the notion of a single centralized repository; instead, each working copy of a git project is its own repository and coordination is done through repository-sync operations. VC supports most git operations, with the exception of news merges and repository syncing; these must be done from the command line. * Mercurial (hg) is a distributed version control system broadly resembling GNU Arch and git, with atomic fileset commits and file moving/renaming. Like git, it is fully decentralized. VC supports most Mercurial commands, with the exception of repository sync operations; this needs to be done from the command line. * Bazaar (bzr) is a distributed version control system that supports both repository-based and distributed versioning, with atomic fileset commits and file moving/renaming. VC supports most basic editing operations under Bazaar. Previous versions of VC supported a version control system known as Meta-CVS. This support has been dropped because of limited interest from users and developers.  File: emacs, Node: VCS Concepts, Next: Types of Log File, Prev: Version Control Systems, Up: Introduction to VC 32.1.1.3 Concepts of Version Control .................................... When a file is under version control, we say that it is "registered" in the version control system. The system has a "repository" which stores both the file's present state and its change history--enough to reconstruct the current version or any earlier version. The repository also contains other information, such as "log entries" that describe the changes made to each file. A file "checked out" of a repository is called the "work file". You edit the work file and make changes in it, as you would with an ordinary file. After you are done with a set of changes, you "check in" or "commit" the file; this records the changes in the repository, along with a log entry for those changes. A copy of a file stored in a repository is called a "revision". The history of a file is a sequence of revisions. Each revision is named by a "revision ID". The format of the revision ID depends on the version control system; in the simplest case, it is just an integer. To go beyond these basic concepts, you will need to understand three aspects in which version control systems differ. They can be locking-based or merging-based; they can be file-based or changeset-based; and they can be centralized or decentralized. VC handles all these modes of operation, but it cannot hide the differences. A version control system typically has some mechanism to coordinate between users who want to change the same file. There are two ways to do this: merging and locking. In a version control system that uses merging, each user may check out and modify a work file at any time. The system lets you "merge" your work file, which may contain changes that have not been checked in, with the latest changes that others have checked into the repository. Older version control systems use a "locking" scheme instead. Here, work files are normally read-only. To edit a file, you ask the version control system to make it writable for you by "locking" it; only one user can lock a given file at any given time. This procedure is analogous to, but different from, the locking that Emacs uses to detect simultaneous editing of ordinary files (*note Interlocking::). When you check in your changes, that unlocks the file, and the work file becomes read-only again. Other users may then lock the file to make their own changes. Both locking and merging systems can have problems when multiple users try to modify the same file at the same time. Locking systems have "lock conflicts"; a user may try to check a file out and be unable to because it is locked. In merging systems, "merge conflicts" happen when you check in a change to a file that conflicts with a change checked in by someone else after your checkout. Both kinds of conflict have to be resolved by human judgment and communication. Experience has shown that merging is superior to locking, both in convenience to developers and in minimizing the number and severity of conflicts that actually occur. SCCS always uses locking. RCS is lock-based by default but can be told to operate in a merging style. CVS and Subversion are merge-based by default but can be told to operate in a locking mode. Distributed version control systems, such as GNU Arch, git, and Mercurial, are exclusively merging-based. VC mode supports both locking and merging version control. The terms "checkin" and "checkout" come from locking-based version control systems; newer version control systems have slightly different operations usually called "commit" and "update", but VC hides the differences between them as much as possible. On SCCS, RCS, CVS, and other early version control systems, version control operations are "file-based": each file has its own comment and revision history separate from that of all other files in the system. Later systems, beginning with Subversion, are "changeset-based": a checkin may include changes to several files, and the entire set of changes is treated as a unit by the system. Any comment associated with the change does not belong to a single file, but to the changeset itself. Changeset-based version control is more flexible and powerful than file-based version control; usually, when a change to multiple files has to be reversed, it's good to be able to easily identify and remove all of it. Early version control systems were designed around a "centralized" model in which each project has only one repository used by all developers. SCCS, RCS, CVS, and Subversion share this kind of model. One of its drawbacks is that the repository is a choke point for reliability and efficiency. GNU Arch pioneered the concept of "decentralized" version control, later implemented in git, Mercurial, and Bazaar. A project may have several different repositories, and these systems support a sort of super-merge between repositories that tries to reconcile their change histories. At the limit, each developer has his/her own repository, and repository merges replace checkin/commit operations. VC's job is to help you manage the traffic between your personal workfiles and a repository. Whether that repository is a single master or one of a network of peer repositories is not something VC has to care about. Thus, the difference between a centralized and a decentralized version control system is invisible to VC mode.  File: emacs, Node: Types of Log File, Prev: VCS Concepts, Up: Introduction to VC 32.1.1.4 Types of Log File .......................... Projects that use a version control system can have two types of log for changes. One is the log maintained by the version control system: each time you check in a change, you fill out a "log entry" for the change (*note Log Buffer::). This is called the "version control log". The other kind of log is the file `ChangeLog' (*note Change Log::). It provides a chronological record of all changes to a large portion of a program--typically one directory and its subdirectories. A small program would use one `ChangeLog' file; a large program may have a `ChangeLog' file in each major directory. *Note Change Log::. Programmers have used change logs since long before version control systems. Changeset-based version systems typically maintain a changeset-based modification log for the entire system, which makes change log files somewhat redundant. One advantage that they retain is that it is sometimes useful to be able to view the transaction history of a single directory separately from those of other directories. A project maintained with version control can use just the version control log, or it can use both kinds of logs. It can handle some files one way and some files the other way. Each project has its policy, which you should follow. When the policy is to use both, you typically want to write an entry for each change just once, then put it into both logs. You can write the entry in `ChangeLog', then copy it to the log buffer with `C-c C-a' when checking in the change (*note Log Buffer::). Or you can write the entry in the log buffer while checking in the change, and later use the `C-x v a' command to copy it to `ChangeLog' (*note Change Logs and VC::).  File: emacs, Node: VC Mode Line, Next: Basic VC Editing, Prev: Introduction to VC, Up: Version Control 32.1.2 Version Control and the Mode Line ---------------------------------------- When you visit a file that is under version control, Emacs indicates this on the mode line. For example, `RCS-1.3' says that RCS is used for that file, and the current version is 1.3. The character between the back-end name and the revision ID indicates the version control status of the file. `-' means that the work file is not locked (if locking is in use), or not modified (if locking is not in use). `:' indicates that the file is locked, or that it is modified. If the file is locked by some other user (for instance, `jim'), that is displayed as `RCS:jim:1.3'. On a graphical display, you can move the mouse over this mode line indicator to pop up a "tool-tip", which displays a more verbose description of the version control status. Pressing `Mouse-1' over the indicator pops up a menu of VC commands. This menu is identical to the `Tools / Version Control' menu item. When Auto Revert mode (*note Reverting::) reverts a buffer that is under version control, it updates the version control information in the mode line. However, Auto Revert mode may not properly update this information if the version control status changes without changes to the work file, from outside the current Emacs session. If you set `auto-revert-check-vc-info' to `t', Auto Revert mode updates the version control status information every `auto-revert-interval' seconds, even if the work file itself is unchanged. The resulting CPU usage depends on the version control system, but is usually not excessive.  File: emacs, Node: Basic VC Editing, Next: Old Revisions, Prev: VC Mode Line, Up: Version Control 32.1.3 Basic Editing under Version Control ------------------------------------------ Most VC commands operate on "VC filesets". A VC fileset is a collection of one or more files that a VC operation acts on. When you type VC commands in a buffer visiting a version-controlled file, the VC fileset is simply that one file. When you type them in a VC Directory buffer, and some files in it are marked, the VC fileset consists of the marked files (*note VC Directory Mode::). The principal VC command is an all-purpose command, `C-x v v' (`vc-next-action'), that performs either registration, locking, merging or a check-in (depending on the situation) on the current VC fileset. You can use `C-x v v' in a file-visiting buffer or in a VC Directory buffer. `C-x v v' Perform the appropriate next version control operation on the VC fileset. The precise action of `C-x v v' depends on the state of the VC fileset, and whether the version control system uses locking or merging. This is described in detail in the subsequent sections. VC filesets are the way that VC mode bridges the gap between file-based and changeset-based version control systems. They are, essentially, a way to pass multiple file arguments as a group to version control commands. For example, on Subversion, a checkin with a multi-file VC fileset becomes a joint commit, as though you had typed `svn commit' with those file arguments at the shell command line. All files in a VC fileset must be under the same version control system; if they are not, Emacs signals an error when you attempt to execute a command on the fileset. Support for VC filesets and changeset-based version control systems is the main improvement to VC in Emacs 23. When you mark multi-file VC in a VC Directory buffer, VC operations treat them as a VC fileset, and operate on them all at once if the version control system is changeset-based. *Note VC Directory Mode::. VC filesets are distinct from the "named filesets" used for viewing and visiting files in functional groups (*note Filesets::). Unlike named filesets, VC filesets are not named and don't persist across sessions. * Menu: * VC With A Merging VCS:: Without locking: default mode for CVS. * VC With A Locking VCS:: RCS in its default mode, SCCS, and optionally CVS. * Advanced C-x v v:: Advanced features available with a prefix argument. * Log Buffer:: Features available in log entry buffers.  File: emacs, Node: VC With A Merging VCS, Next: VC With A Locking VCS, Up: Basic VC Editing 32.1.3.1 Basic Version Control with Merging ........................................... When your version control system is merging-based (the default for CVS and all newer version control systems), work files are always writable; you need not do anything special to begin editing a file. The status indicator on the mode line is `-' if the file is unmodified; it flips to `:' as soon as you save any changes (*note VC Mode Line::). Here is what `C-x v v' does when using a merging-based system: * If the work file is in a directory that is not controlled by any version control system, prompt for a repository type. Then, create a version control repository of that type and register the file with it. * If the work file is in a directory that is controlled by a version control system but not registered with it, register the file. * If the work file is the same as in the repository, do nothing. * If you have not changed the work file, but some other user has checked in changes to the repository, merge those changes into the work file. * If you have made modifications to the work file, attempts to check in your changes. To do this, Emacs first reads the log entry for the new revision (*note Log Buffer::). If some other user has checked in changes to the repository since you last checked it out, the checkin fails. In that case, type `C-x v v' again to merge those changes into your own work file; this puts the work file into a "conflicted" state. Type `C-x v v' to clear the "conflicted" state; VC then regards the file as up-to-date and modified, and you can try to check it in again. To pick up any recent changes from the repository _without_ trying to commit your own changes, type `C-x v m '. *Note Merging::. These rules also apply when you use RCS in its "non-locking" mode, except that changes are not automatically merged from the repository. Nothing informs you if another user has checked in changes in the same file since you began editing it; when you check in your revision, his changes are removed (however, they remain in the repository and are thus not irrevocably lost). Therefore, you must verify that the current revision is unchanged before checking in your changes. In addition, locking is possible with RCS even in this mode: `C-x v v' with an unmodified file locks the file, just as it does with RCS in its normal locking mode (*note VC With A Locking VCS::).  File: emacs, Node: VC With A Locking VCS, Next: Advanced C-x v v, Prev: VC With A Merging VCS, Up: Basic VC Editing 32.1.3.2 Basic Version Control with Locking ........................................... Under a locking-based version control system (such as SCCS, and RCS in its default mode), `C-x v v' does the following: * If the file is not locked, lock it and make it writable, so that you can change it. * If the file is locked by you, and contains changes, check in the changes. In order to do this, Emacs first reads the log entry for the new revision. *Note Log Buffer::. * If the file is locked by you, but you have not changed it since you locked it, release the lock and makes the file read-only again. * If the file is locked by some other user, ask whether you want to "steal the lock" from that user. If you say yes, the file becomes locked by you, but a message is sent to the person who had formerly locked the file, to inform him of what has happened. These rules also apply when you use CVS in locking mode, except that there is no such thing as stealing a lock.  File: emacs, Node: Advanced C-x v v, Next: Log Buffer, Prev: VC With A Locking VCS, Up: Basic VC Editing 32.1.3.3 Advanced Control in `C-x v v' ...................................... When you give a prefix argument to `vc-next-action' (`C-u C-x v v'), it still performs the next logical version control operation, but accepts additional arguments to specify precisely how to do the operation. * If the file is modified (or locked), you can specify the revision ID to use for the new version that you check in. This is one way to create a new branch (*note Branches::). * If the file is not modified (and unlocked), you can specify the revision to select; this lets you start working from an older revision, or on another branch. If you do not enter any revision, that takes you to the highest ("head") revision on the current branch; therefore `C-u C-x v v ' is a convenient way to get the latest version of a file from the repository. * Instead of the revision ID, you can also specify the name of a version control system. This is useful when one file is being managed with two version control systems at the same time (*note Local Version Control::).  File: emacs, Node: Log Buffer, Prev: Advanced C-x v v, Up: Basic VC Editing 32.1.3.4 Features of the Log Entry Buffer ......................................... When you check in changes, Emacs pops up a buffer called `*VC-Log*' for you to enter a log entry. After you have finished editing the log message, type `C-c C-c' to exit the buffer and commit the change. In the `*VC-Log*' buffer, typing `C-c C-f' (`log-edit-show-files') displays a list of files in the VC fileset you are committing. If you called `C-x v v' directly from a work file, the VC fileset consists of that single file, so this command is not very useful. If you called `C-x v v' from a VC directory buffer, the VC fileset may consist of multiple files (*note VC Directory Mode::). Type `C-c C-d' (`log-edit-show-diff') to show a "diff" of the changes you have made (i.e., the differences between the work file and the repository revision from which you started editing the file). The diff is displayed in a special buffer in another window. *Note Comparing Files::. If you have written an entry in the `ChangeLog' (*note Change Log::), type `C-c C-a' (`log-edit-insert-changelog') to pull it into the `*VC-Log*' buffer. If the topmost item in the `ChangeLog' was made under your user name on the current date, this command searches that item for entries that match the file(s) to be committed; if found, these entries are inserted. *Note Change Logs and VC::, for the opposite way of working--generating ChangeLog entries from the revision control log. To abort a check-in, just *don't* type `C-c C-c' in that buffer. You can switch buffers and do other editing. As long as you don't try to check in another file, the entry you were editing remains in the `*VC-Log*' buffer, and you can go back to that buffer at any time to complete the check-in. If you change several source files for the same reason, it is often convenient to specify the same log entry for many of the files. (This is the normal way to do things on a changeset-oriented system, where comments are attached to changesets rather than the history of individual files.) The most convenient way to do this is to mark all the files in VC Directory Mode and check in from there; the log buffer will carry the fileset information with it and do a group commit when you type `C-c C-c'. You can also browse the history of previous log entries to duplicate a checkin comment. This can be useful when you want several files to have checkin comments that vary only slightly from each other. The commands `M-n', `M-p', `M-s' and `M-r' for doing this work just like the minibuffer history commands (except that these versions are used outside the minibuffer). Each time you check in a change, the log entry buffer is put into VC Log Edit mode, which involves running two hooks: `text-mode-hook' and `vc-log-mode-hook'. *Note Hooks::.  File: emacs, Node: Old Revisions, Next: Secondary VC Commands, Prev: Basic VC Editing, Up: Version Control 32.1.4 Examining And Comparing Old Revisions -------------------------------------------- One of the convenient features of version control is the ability to examine any revision of a file, or compare two revisions. `C-x v ~' Prompt for a revision of the current file, and visit it in a buffer of its own (`vc-revision-other-window'). `C-x v =' Compare the files in the current fileset with the working revision(s) you started from (`vc-diff'). With a prefix argument, prompt for two revisions of the current fileset and compare them. You can call this command from a Dired buffer (*note Dired::). `C-x v D' Compare the entire tree corresponding to the current fileset with the tree you started from (`vc-root-diff'). With a prefix argument, prompt for two revisions and compare their trees. `C-x v g' Display an annotated version of the file: for each line, show the latest revision in which it was modified (`vc-annotate'). To examine an old revision, visit the work file and type `C-x v ~ REVISION ' (`vc-revision-other-window'). Here, REVISION is either the desired revision ID (*note VCS Concepts::), or the name of a tag or branch (*note Tags::). This command puts the text of the old revision in a file named `FILENAME.~REVISION~', and visits it in its own buffer in a separate window. `C-x v =' (`vc-diff') compares each file in the current VC fileset (saving them if necessary) with the repository revision(s) from which you started editing. Note that the latter may or may not be the latest revision of the file(s). The diff is displayed in a special buffer in another window. *Note Comparing Files::. To compare two arbitrary revisions of the current VC fileset, call `vc-diff' with a prefix argument: `C-u C-x v ='. This prompts for two revision IDs, using the minibuffer, and displays the diff in a special buffer in another window. Instead of providing a revision ID, you can give an empty input, which specifies the current contents of the work file; or a tag or branch name (*note Tags::). If your version control system is file-based (e.g. CVS) rather than changeset-based (Subversion, GNU Arch, git, Mercurial), supplying a revision ID for a multi-file fileset (as opposed to a symbolic tag name) is unlikely to return diffs that are connected in any meaningful way. The command `C-x v D' (`vc-root-diff') is similar to `C-x v =', but it compares the entire tree associated with the current VC fileset with the tree you started with. This means all the files controlled by the current version control repository, even those that are not part of the current VC fileset. If you invoke `C-x v =' or `C-u C-x v =' from a buffer that is neither visiting a version-controlled file nor a VC directory buffer, these commands generate a diff of all registered files in the current directory and its subdirectories. `C-x v =' works by running a variant of the `diff' utility designed to work with the version control system in use. The options to pass to the `diff' command are taken from the first non-`nil' value of `vc-BACKEND-diff-switches', `vc-diff-switches', and `diff-switches' (*note Comparing Files::), in that order. Since `nil' means to check the next variable in the sequence, either of the first two may use the value `t' to mean no switches at all. Most of the `vc...diff-switches' variables default to `nil', but some default to `t'. These are for those version control systems (e.g. SVN) whose `diff' implementations do not accept common options (e.g. `-c') likely to be in `diff-switches'. The buffer produced by `C-x v =' supports the commands of Compilation mode (*note Compilation Mode::), such as `C-x `' and `C-c C-c', in both the "old" and "new" text, and they always find the corresponding locations in the current work file. (Older revisions are not, in general, present as files on your disk.) For some back ends, you can display the file "annotated" with per-line revision information, by typing `C-x v g' (`vc-annotate'). This creates a new buffer (the "annotate buffer") displaying the file's text, with each part colored to show how old it is. Text colored red is new, blue means old, and intermediate colors indicate intermediate ages. By default, the color is scaled over the full range of ages, such that the oldest changes are blue, and the newest changes are red. When you give a prefix argument to this command, Emacs reads two arguments using the minibuffer: the ID of which revision to display and annotate (instead of the current file contents), and the time span in days the color range should cover. From the annotate buffer, these and other color scaling options are available from the `VC-Annotate' menu. In this buffer, you can also use the following keys to browse the annotations of past revisions, view diffs, or view log entries: `p' Annotate the previous revision, that is to say, the revision before the one currently annotated. A numeric prefix argument is a repeat count, so `C-u 10 p' would take you back 10 revisions. `n' Annotate the next revision--the one after the revision currently annotated. A numeric prefix argument is a repeat count. `j' Annotate the revision indicated by the current line. `a' Annotate the revision before the one indicated by the current line. This is useful to see the state the file was in before the change on the current line was made. `f' Show in a buffer the file revision indicated by the current line. `d' Display the diff between the current line's revision and the previous revision. This is useful to see what the current line's revision actually changed in the file. `D' Display the diff between the current line's revision and the previous revision for all files in the changeset (for VC systems that support changesets). This is useful to see what the current line's revision actually changed in the tree. `l' Show the log of the current line's revision. This is useful to see the author's description of the changes in the revision on the current line. `w' Annotate the working revision-the one you are editing. If you used `p' and `n' to browse to other revisions, use this key to return to your working revision. `v' Toggle the annotation visibility. This is useful for looking just at the file contents without distraction from the annotations.  File: emacs, Node: Secondary VC Commands, Next: VC Directory Mode, Prev: Old Revisions, Up: Version Control 32.1.5 The Secondary Commands of VC ----------------------------------- This section explains the secondary commands of VC. * Menu: * Registering:: Putting a file under version control. * VC Change Log:: Viewing the VC Change Log. * VC Undo:: Canceling changes before or after check-in.  File: emacs, Node: Registering, Next: VC Change Log, Up: Secondary VC Commands 32.1.5.1 Registering a File for Version Control ............................................... You can put any file under version control by simply visiting it, and then typing `C-x v i' (`vc-register'). `C-x v i' Register the visited file for version control. To register the file, Emacs must choose which version control system to use for it. If the file's directory already contains files registered in a version control system, Emacs uses that system. If there is more than one system in use for a directory, Emacs uses the one that appears first in `vc-handled-backends' (*note Customizing VC::). On the other hand, if there are no files already registered, Emacs uses the first system from `vc-handled-backends' that could register the file (for example, you cannot register a file under CVS if its directory is not already part of a CVS tree); with the default value of `vc-handled-backends', this means that Emacs uses RCS in this situation. If locking is in use, `C-x v i' leaves the file unlocked and read-only. Type `C-x v v' if you wish to start editing it. After registering a file with CVS, you must subsequently commit the initial revision by typing `C-x v v'. Until you do that, the revision ID appears as `@@' in the mode line. The default initial revision ID for a newly registered file varies by what VCS you are using; normally it will be 1.1 on VCSes that use dot-pair revision IDs and 1 on VCSes that use monotonic IDs. You can specify a different default by setting the variable `vc-default-init-revision', or you can give `C-x v i' a numeric argument; then it reads the initial revision ID for this particular file using the minibuffer. If `vc-initial-comment' is non-`nil', `C-x v i' reads an initial comment to describe the purpose of this source file. Reading the initial comment works like reading a log entry (*note Log Buffer::).  File: emacs, Node: VC Change Log, Next: VC Undo, Prev: Registering, Up: Secondary VC Commands 32.1.5.2 VC Change Log ...................... `C-x v l' Display revision control state and change history (`vc-print-log'). `C-x v L' Display the change history for the current repository (`vc-print-root-log'). The command `C-x v l' (`vc-print-log') displays a buffer named `*vc-change-log*' in a new window. This buffer lists the changes to the current file, including the associated log entries. (These are the log entries associated with the version control system, i.e. the ones you enter via the `*VC-Log*' buffer. *Note Log Buffer::.) Point is centered at the revision of the file currently being visited. With a prefix argument, the command prompts for the revision to center on, and the maximum number of revisions to display. You can call this command from a Dired buffer (*note Dired::). Type `C-x v L' (`vc-print-root-log') to display a `*vc-change-log*' buffer showing the history of the version-controlled directory tree as a whole. With a prefix argument, the command prompts for the maximum number of revisions to display. RCS, SCCS, and CVS do not support this feature. In the `*vc-change-log*' buffer, you can use the following keys to move between the logs of revisions and of files, to view past revisions, to modify change comments, to view annotations and to view diffs: `p' Move to the previous revision-item in the buffer. (Revision entries in the log buffer are usually in reverse-chronological order, so the previous revision-item usually corresponds to a newer revision.) A numeric prefix argument is a repeat count. `n' Move to the next revision-item (which most often corresponds to the previous revision of the file). A numeric prefix argument is a repeat count. `P' Move to the log of the previous file, when the logs of multiple files are in the log buffer (*note VC Directory Mode::). Otherwise, just move to the beginning of the log. A numeric prefix argument is a repeat count, so `C-u 10 P' would move backward 10 files. `N' Move to the log of the next file, when the logs of multiple files are in the log buffer (*note VC Directory Mode::). It also takes a numeric prefix argument as a repeat count. `a' Annotate the revision indicated by the current line. `e' Modify the change comment displayed at point. Note that not all VC systems support modifying change comments. `f' Visit the revision indicated at the current line, like typing `C-x v ~' and specifying this revision's ID (*note Old Revisions::). `d' Display the diff (*note Comparing Files::) between the revision indicated at the current line and the next earlier revision. This is useful to see what actually changed in the file when the revision indicated on the current line was committed. `D' Display the changeset diff (*note Comparing Files::) between the revision indicated at the current line and the next earlier revision. This is useful to see all the changes to all files that the revision indicated on the current line did when it was committed. Because fetching many log entries can be slow, the `*vc-change-log*' buffer displays no more than 2000 revisions by default. The variable `vc-log-show-limit' specifies this limit; if you set the value to zero, that removes the limit. You can also increase the number of revisions shown in an existing `*vc-change-log*' buffer by clicking on the `Show 2X entries' or `Show unlimited entries' buttons at the end of the buffer. However, RCS, SCCS, and CVS do not support this feature.  File: emacs, Node: VC Undo, Prev: VC Change Log, Up: Secondary VC Commands 32.1.5.3 Undoing Version Control Actions ........................................ `C-x v u' Revert the buffer and the file to the working revision from which you started editing the file. `C-x v c' Remove the last-entered change from the master for the visited file. This undoes your last check-in. If you want to discard your current set of changes and revert to the working revision from which you started editing the file, use `C-x v u' (`vc-revert-buffer'). If the version control system is locking-based, this leaves the file unlocked, and you must lock it again before making new changes. `C-x v u' requires confirmation, unless it sees that you haven't made any changes with respect to the master copy of the working revision. `C-x v u' is also the command to unlock a file if you lock it and then decide not to change it. To cancel a change that you already checked in, use `C-x v c' (`vc-rollback'). This command discards all record of the most recent checked-in revision, but only if your work file corresponds to that revision--you cannot use `C-x v c' to cancel a revision that is not the latest on its branch. Note that many version control systems do not support rollback at all; this command is something of a historical relic.  File: emacs, Node: VC Directory Mode, Next: Branches, Prev: Secondary VC Commands, Up: Version Control 32.1.6 VC Directory Mode ------------------------ When you are working on a large program, it is often useful to find out which files have changed within an entire directory tree, or to view the status of all files under version control at once, and to perform version control operations on collections of files. You can use the command `C-x v d' (`vc-dir') to make a directory listing that includes only files relevant for version control. This creates a "VC Directory buffer" and displays it in a separate window. The VC Directory buffer works with all the version control systems that VC supports. For CVS, Emacs also offers a more powerful facility called PCL-CVS. *Note About PCL-CVS: (pcl-cvs)Top. * Menu: * Buffer: VC Directory Buffer. What the buffer looks like and means. * Commands: VC Directory Commands. Commands to use in a VC directory buffer.  File: emacs, Node: VC Directory Buffer, Next: VC Directory Commands, Up: VC Directory Mode 32.1.6.1 The VC Directory Buffer ................................ The VC Directory buffer contains a list of version-controlled files in the current directory and its subdirectories. Files which are up-to-date (have no local differences from the repository copy) are usually hidden; if all files in a subdirectory are up-to-date, the subdirectory is hidden as well. There is an exception to this rule: if VC mode detects that a file has changed to an up-to-date state since you last looked at it, that file and its state are shown. If a directory uses more that one version control system, you can select which system to use for the `vc-dir' command by invoking `vc-dir' with a prefix argument: `C-u C-x v d'. The line for an individual file shows the version control state of the file. Under RCS and SCCS, the name of the user locking the file is shown; under CVS, an abbreviated version of the `cvs status' output is used. Here is an example using CVS: ./ modified file1.c needs-update file2.c needs-merge file3.c In this example, `file1.c' is modified with respect to the repository, and `file2.c' is not. `file3.c' is modified, but other changes have also been checked in to the repository--you need to merge them with the work file before you can check it in. In the above, if the repository were on a remote machine, VC only contacts it when the variable `vc-stay-local' (or `vc-cvs-stay-local') is `nil' (*note CVS Options::). This is because access to the repository may be slow, or you may be working offline and not have access to the repository at all. As a consequence, VC would not be able to tell you that `file3.c' is in the "merge" state; you would learn that only when you try to check-in your modified copy of the file, or use a command such as `C-x v m'. In practice, this is not a problem because CVS handles this case consistently whenever it arises. In VC, you'll simply get prompted to merge the remote changes into your work file first. The benefits of less network communication usually outweigh the disadvantage of not seeing remote changes immediately. When a VC directory displays subdirectories it omits some that should never contain any files under version control. By default, this includes Version Control subdirectories such as `RCS' and `CVS'; you can customize this by setting the variable `vc-directory-exclusion-list'.  File: emacs, Node: VC Directory Commands, Prev: VC Directory Buffer, Up: VC Directory Mode 32.1.6.2 VC Directory Commands .............................. VC Directory mode has a full set of navigation and marking commands for picking out filesets. Some of these are also available in a context menu invoked by the `mouse-2' button. Up- and down-arrow keys move in the buffer; `n' and `p' also move vertically as in other list-browsing modes. and behave like down-arrow, and behaves like up-arrow. Both `C-m' and `f' visit the file on the current line. `o' visits that file in another window. `q' dismisses the directory buffer. `x' hides up-to-date files. `m' marks the file or directory on the current line. If the region is active, `m' marks all the files in the region. There are some restrictions when marking: a file cannot be marked if any of its parent directories are marked, and a directory cannot be marked if any files in it or in its child directories are marked. `M' marks all the files with the same VC state as the current file if the cursor is on a file. If the cursor is on a directory, it marks all child files. With a prefix argument: marks all files and directories. `u' unmarks the file or directory on the current line. If the region is active, it unmarks all the files in the region. `U' marks all the files with the same VC state as the current file if the cursor is on a file. If the cursor is on a directory, it unmarks all child files. With a prefix argument: unmarks all marked files and directories. It is possible to do search, search and replace, incremental search, and incremental regexp search on multiple files. These commands will work on all the marked files or the current file if nothing is marked. If a directory is marked, the files in that directory shown in the VC directory buffer will be used. `S' searches the marked files. `Q' does a query replace on the marked files. `M-s a C-s' does an incremental search on the marked files. `M-s a C-M-s' does an incremental search on the marked files. Commands are also accessible from the VC-dir menu. Note that some VC backends use the VC-dir menu to make available extra, backend-specific, commands. For example, Git and Bazaar allow you to manipulate "stashes" and "shelves". (These provide a mechanism to temporarily store uncommitted changes somewhere out of the way, and bring them back at a later time.) Normal VC commands with the `C-x v' prefix work in VC directory buffers. Some single-key shortcuts are available as well; `=', `+', `l', `i', and `v' behave as through prefixed with `C-x v'. The command `C-x v v' (`vc-next-action') operates on all the marked files, so that you can check in several files at once. If the underlying VC supports atomic commits of multiple-file changesets, `C-x v v' with a selected set of modified but not committed files will commit all of them at once as a single changeset. When `C-x v v' (`vc-next-action') operates on multiple files, all of those files must be either in the same state or in compatible states (added, modified and removed states are considered compatible). Otherwise it signals an error. This differs from the behavior of older versions of VC, which did not have fileset operations and simply did `vc-next-action' on each file individually. If any files are in a state that calls for commit, `C-x v v' reads a single log entry and uses it for the changeset as a whole. If the underling VCS is file- rather than changeset-oriented, the log entry will be replicated into the history of each file.  File: emacs, Node: Branches, Next: Remote Repositories, Prev: VC Directory Mode, Up: Version Control 32.1.7 Multiple Branches of a File ---------------------------------- One use of version control is to maintain multiple "current" revisions of a file. For example, you might have different revisions of a program in which you are gradually adding various unfinished new features. Each such independent line of development is called a "branch". VC allows you to create branches, switch between different branches, and merge changes from one branch to another. Please note, however, that branches are not supported for SCCS. A file's main line of development is usually called the "trunk". You can create multiple branches from the trunk. How the difference between trunk and branch is made visible is dependent on whether the VCS uses dot-pair or monotonic version IDs. In VCSes with dot-pair revision IDs, the revisions on the trunk are normally IDed 1.1, 1.2, 1.3, etc. At any such revision, you can start an independent branch. A branch starting at revision 1.2 would have revision ID 1.2.1.1, and consecutive revisions on this branch would have IDs 1.2.1.2, 1.2.1.3, 1.2.1.4, and so on. If there is a second branch also starting at revision 1.2, it would consist of revisions 1.2.2.1, 1.2.2.2, 1.2.2.3, etc. In VCSes with monotonic revision IDs, trunk revisions are IDed as 1, 2, 3, etc. A branch from (say) revision 2 might start with 2.1 and continue through 2.2, 2.3, etc. But naming conventions for branches and subbranches vary widely on these systems, and some (like Mercurial) never depart from the monotonic integer sequence at all. Consult the documentation of the VCS you are using. If you omit the final component of a dot-pair revision ID, that is called a "branch ID". It refers to the highest existing revision on that branch--the "head revision" of that branch. The branches in the dot-pair example above have branch IDs 1.2.1 and 1.2.2. * Menu: * Switching Branches:: How to get to another existing branch. * Creating Branches:: How to start a new branch. * Merging:: Transferring changes between branches. * Multi-User Branching:: Multiple users working at multiple branches in parallel.  File: emacs, Node: Switching Branches, Next: Creating Branches, Up: Branches 32.1.7.1 Switching between Branches ................................... To switch between branches, type `C-u C-x v v' and specify the revision ID you want to select. On a locking-based system, this version is then visited _unlocked_ (write-protected), so you can examine it before locking it. Switching branches in this way is allowed only when the file is not locked. On a VCS with dot-pair IDs, you can omit the minor part, thus giving only the branch ID; this takes you to the head version on the chosen branch. If you only type , Emacs goes to the highest version on the trunk. After you have switched to any branch (including the main branch), you stay on it for subsequent VC commands, until you explicitly select some other branch.  File: emacs, Node: Creating Branches, Next: Merging, Prev: Switching Branches, Up: Branches 32.1.7.2 Creating New Branches .............................. To create a new branch from a head revision (one that is the latest in the branch that contains it), first select that revision if necessary, lock it with `C-x v v', and make whatever changes you want. Then, when you check in the changes, use `C-u C-x v v'. This lets you specify the revision ID for the new revision. You should specify a suitable branch ID for a branch starting at the current revision. For example, if the current revision is 2.5, the branch ID should be 2.5.1, 2.5.2, and so on, depending on the number of existing branches at that point. To create a new branch at an older revision (one that is no longer the head of a branch), first select that revision (*note Switching Branches::). Your procedure will then differ depending on whether you are using a locking or merging-based VCS. On a locking VCS, you will need to lock the old revision branch with `C-x v v'. You'll be asked to confirm, when you lock the old revision, that you really mean to create a new branch--if you say no, you'll be offered a chance to lock the latest revision instead. On a merging-based VCS you will skip this step. Then make your changes and type `C-x v v' again to check in a new revision. This automatically creates a new branch starting from the selected revision. You need not specially request a new branch, because that's the only way to add a new revision at a point that is not the head of a branch. After the branch is created, you "stay" on it. That means that subsequent check-ins create new revisions on that branch. To leave the branch, you must explicitly select a different revision with `C-u C-x v v'. To transfer changes from one branch to another, use the merge command, described in the next section.  File: emacs, Node: Merging, Next: Multi-User Branching, Prev: Creating Branches, Up: Branches 32.1.7.3 Merging Branches ......................... When you have finished the changes on a certain branch, you will often want to incorporate them into the file's main line of development (the trunk). This is not a trivial operation, because development might also have proceeded on the trunk, so that you must "merge" the changes into a file that has already been changed otherwise. VC allows you to do this (and other things) with the `vc-merge' command. `C-x v m (vc-merge)' Merge changes into the work file. `C-x v m' (`vc-merge') takes a set of changes and merges it into the current version of the work file. It firsts asks you in the minibuffer where the changes should come from. If you just type , Emacs merges any changes that were made on the same branch since you checked the file out (we call this "merging the news"). This is the common way to pick up recent changes from the repository, regardless of whether you have already changed the file yourself. You can also enter a branch ID or a pair of revision IDs in the minibuffer. Then `C-x v m' finds the changes from that branch, or the differences between the two revisions you specified, and merges them into the current revision of the current file. As an example, suppose that you have finished a certain feature on branch 1.3.1. In the meantime, development on the trunk has proceeded to revision 1.5. To merge the changes from the branch to the trunk, first go to the head revision of the trunk, by typing `C-u C-x v v '. Revision 1.5 is now current. If locking is used for the file, type `C-x v v' to lock revision 1.5 so that you can change it. Next, type `C-x v m 1.3.1 '. This takes the entire set of changes on branch 1.3.1 (relative to revision 1.3, where the branch started, up to the last revision on the branch) and merges it into the current revision of the work file. You can now check in the changed file, thus creating revision 1.6 containing the changes from the branch. It is possible to do further editing after merging the branch, before the next check-in. But it is usually wiser to check in the merged revision, then lock it and make the further changes. This will keep a better record of the history of changes. When you merge changes into a file that has itself been modified, the changes might overlap. We call this situation a "conflict", and reconciling the conflicting changes is called "resolving a conflict". Whenever conflicts occur during merging, VC detects them, tells you about them in the echo area, and asks whether you want help in merging. If you say yes, it starts an Ediff session (*note Ediff: (ediff)Top.). If you say no, the conflicting changes are both inserted into the file, surrounded by "conflict markers". The example below shows how a conflict region looks; the file is called `name' and the current master file revision with user B's changes in it is 1.11. <<<<<<< name USER A'S VERSION ======= USER B'S VERSION >>>>>>> 1.11 Then you can resolve the conflicts by editing the file manually. Or you can type `M-x vc-resolve-conflicts' after visiting the file. This starts an Ediff session, as described above. Don't forget to check in the merged version afterwards.  File: emacs, Node: Multi-User Branching, Prev: Merging, Up: Branches 32.1.7.4 Multi-User Branching ............................. It is often useful for multiple developers to work simultaneously on different branches of a file. CVS and later systems allow this by default; for RCS, it is possible if you create multiple source directories. Each source directory should have a link named `RCS' which points to a common directory of RCS master files. Then each source directory can have its own choice of selected revisions, but all share the same common RCS records. This technique works reliably and automatically, provided that the source files contain RCS version headers (*note Version Headers::). The headers enable Emacs to be sure, at all times, which revision ID is present in the work file. If the files do not have version headers, you must instead tell Emacs explicitly in each session which branch you are working on. To do this, first find the file, then type `C-u C-x v v' and specify the correct branch ID. This ensures that Emacs knows which branch it is using during this particular editing session.  File: emacs, Node: Remote Repositories, Next: Revision Tags, Prev: Branches, Up: Version Control 32.1.8 Remote Repositories -------------------------- A common way of using CVS and other more advanced VCSes is to set up a central repository on some Internet host, then have each developer check out a personal working copy of the files on his local machine. Committing changes to the repository, and picking up changes from other users into one's own working area, then works by direct interactions with the repository server. One difficulty is that access to a repository server is often slow, and that developers might need to work off-line as well. While only third-generation decentralized VCses such as GNU Arch or Mercurial really solve this problem, VC is designed to reduce the amount of network interaction necessary. If you are using a truly decentralized VCS you can skip the rest of this section. It describes backup and local-repository techniques that are only useful for Subversion and earlier VCSes. * Menu: * Version Backups:: Keeping local copies of repository versions. * Local Version Control:: Using another version system for local editing.  File: emacs, Node: Version Backups, Next: Local Version Control, Up: Remote Repositories 32.1.8.1 Version Backups ........................ When VC sees that the repository for a file is on a remote machine, it automatically makes local backups of unmodified versions of the file--"automatic version backups". This means that you can compare the file to the repository version (`C-x v ='), or revert to that version (`C-x v u'), without any network interactions. The local copy of the unmodified file is called a "version backup" to indicate that it corresponds exactly to a version that is stored in the repository. Note that version backups are not the same as ordinary Emacs backup files (*note Backup::). But they follow a similar naming convention. For a file that comes from a remote repository, VC makes a version backup whenever you save the first changes to the file, and removes it after you have committed your modified version to the repository. You can disable the making of automatic version backups by setting `vc-cvs-stay-local' to `nil' (*note CVS Options::). The name of the automatic version backup for version VERSION of file FILE is `FILE.~VERSION.~'. This is almost the same as the name used by `C-x v ~' (*note Old Revisions::), the only difference being the additional dot (`.') after the version number. This similarity is intentional, because both kinds of files store the same kind of information. The file made by `C-x v ~' acts as a "manual version backup". All the VC commands that operate on old versions of a file can use both kinds of version backups. For instance, `C-x v ~' uses either an automatic or a manual version backup, if possible, to get the contents of the version you request. Likewise, `C-x v =' and `C-x v u' use either an automatic or a manual version backup, if one of them exists, to get the contents of a version to compare or revert to. If you changed a file outside of Emacs, so that no automatic version backup was created for the previous text, you can create a manual backup of that version using `C-x v ~', and thus obtain the benefit of the local copy for Emacs commands. The only difference in Emacs's handling of manual and automatic version backups, once they exist, is that Emacs deletes automatic version backups when you commit to the repository. By contrast, manual version backups remain until you delete them.  File: emacs, Node: Local Version Control, Prev: Version Backups, Up: Remote Repositories 32.1.8.2 Local Version Control .............................. When you make many changes to a file that comes from a remote repository, it can be convenient to have version control on your local machine as well. You can then record intermediate versions, revert to a previous state, etc., before you actually commit your changes to the remote server. VC lets you do this by putting a file under a second, local version control system, so that the file is effectively registered in two systems at the same time. For the description here, we will assume that the remote system is CVS, and you use RCS locally, although the mechanism works with any combination of version control systems ("back ends"). To make it work with other back ends, you must make sure that the "more local" back end comes before the "more remote" back end in the setting of `vc-handled-backends' (*note Customizing VC::). By default, this variable is set up so that you can use remote CVS and local RCS as described here. To start using local RCS for a file that comes from a remote CVS server, you must _register the file in RCS_, by typing `C-u C-x v v rcs '. (In other words, use `vc-next-action' with a prefix argument, and specify RCS as the back end.) You can do this at any time; it does not matter whether you have already modified the file with respect to the version in the CVS repository. If possible, VC tries to make the RCS master start with the unmodified repository version, then checks in any local changes as a new version. This works if you have not made any changes yet, or if the unmodified repository version exists locally as a version backup (*note Version Backups::). If the unmodified version is not available locally, the RCS master starts with the modified version; the only drawback to this is that you cannot compare your changes locally to what is stored in the repository. The version number of the RCS master is derived from the current CVS version, starting a branch from it. For example, if the current CVS version is 1.23, the local RCS branch will be 1.23.1. Version 1.23 in the RCS master will be identical to version 1.23 under CVS; your first changes are checked in as 1.23.1.1. (If the unmodified file is not available locally, VC will check in the modified file twice, both as 1.23 and 1.23.1.1, to make the revision numbers consistent.) If you do not use locking under CVS (the default), locking is also disabled for RCS, so that editing under RCS works exactly as under CVS. When you are done with local editing, you can commit the final version back to the CVS repository by typing `C-u C-x v v cvs '. This initializes the log entry buffer (*note Log Buffer::) to contain all the log entries you have recorded in the RCS master; you can edit them as you wish, and then commit in CVS by typing `C-c C-c'. If the commit is successful, VC removes the RCS master, so that the file is once again registered under CVS only. (The RCS master is not actually deleted, just renamed by appending `~' to the name, so that you can refer to it later if you wish.) While using local RCS, you can pick up recent changes from the CVS repository into your local file, or commit some of your changes back to CVS, without terminating local RCS version control. To do this, switch to the CVS back end temporarily, with the `C-x v b' command: `C-x v b' Switch to another back end that the current file is registered under (`vc-switch-backend'). `C-u C-x v b BACKEND ' Switch to BACKEND for the current file. `C-x v b' does not change the buffer contents, or any files; it only changes VC's perspective on how to handle the file. Any subsequent VC commands for that file will operate on the back end that is currently selected. If the current file is registered in more than one back end, typing `C-x v b' "cycles" through all of these back ends. With a prefix argument, it asks for the back end to use in the minibuffer. Thus, if you are using local RCS, and you want to pick up some recent changes in the file from remote CVS, first visit the file, then type `C-x v b' to switch to CVS, and finally use `C-x v m ' to merge the news (*note Merging::). You can then switch back to RCS by typing `C-x v b' again, and continue to edit locally. But if you do this, the revision numbers in the RCS master no longer correspond to those of CVS. Technically, this is not a problem, but it can become difficult to keep track of what is in the CVS repository and what is not. So we suggest that you return from time to time to CVS-only operation, by committing your local changes back to the repository using `C-u C-x v v cvs '.  File: emacs, Node: Revision Tags, Next: Miscellaneous VC, Prev: Remote Repositories, Up: Version Control 32.1.9 Revision Tags -------------------- In a VCS with per-file revision numbers (such as SCCS, RCS, or CVS) "tag" is a named set of file versions (one for each registered file) that you can treat as a unit. In a VCS with per-repository version numbers (Subversion and most later ones) a tag is simply a symbolic name for a revision. One important kind of tag is a "release", a (theoretically) stable version of the system that is ready for distribution to users. * Menu: * Making Revision Tags:: The tag facilities. * Revision Tag Caveats:: Things to be careful of when using tags.  File: emacs, Node: Making Revision Tags, Next: Revision Tag Caveats, Up: Revision Tags 32.1.9.1 Making and Using Revision Tags ....................................... There are two basic commands for tags; one makes a tag with a given name, the other retrieves a named tag. `C-x v s NAME ' Define the working revision of every registered file in or under the current directory as a tag named NAME (`vc-create-tag'). `C-x v r NAME ' For all registered files at or below the current directory level, retrieve the tagged revision NAME. This command will switch to a branch if NAME is a branch name and your VCS distinguishes branches from tags. (`vc-retrieve-tag'). This command reports an error if any files are locked at or below the current directory, without changing anything; this is to avoid overwriting work in progress. Tags are inexpensive, so you need not hesitate to create them whenever they are useful. Branches vary in cost depending on your VCS; in older ones they may be expensive. You can give a tag or branch name as an argument to `C-x v =' or `C-x v ~' (*note Old Revisions::). Thus, you can use it to compare a tagged version against the current files, or two tagged versions against each other.  File: emacs, Node: Revision Tag Caveats, Prev: Making Revision Tags, Up: Revision Tags 32.1.9.2 Revision Tag Caveats ............................. For SCCS, VC implements tags itself; these tags are visible only through VC. Most later systems (including CVS, Subversion, bzr, git, and hg) have a native tag facility, and VC uses it where available; those tags will be visible even when you bypass VC. There is no support for VC tags using GNU Arch yet. Under older VCSes (SCCS, RCS, CVS, early versions of Subversion), renaming and deletion could create some difficulties with tags. This is not a VC-specific problem, but a general design issue in version control systems that was not solved effectively until the earliest third-generation systems. In a file-oriented VCS, when you rename a registered file you need to rename its master along with it; the command `vc-rename-file' will do this automatically. If you are using SCCS, you must also update the records of the tag, to mention the file by its new name (`vc-rename-file' does this, too). An old tag that refers to a master file that no longer exists under the recorded name is invalid; VC can no longer retrieve it. It would be beyond the scope of this manual to explain enough about RCS and SCCS to explain how to update the tags by hand. Using `vc-rename-file' makes the tag remain valid for retrieval, but it does not solve all problems. For example, some of the files in your program probably refer to others by name. At the very least, the makefile probably mentions the file that you renamed. If you retrieve an old tag, the renamed file is retrieved under its new name, which is not the name that the makefile expects. So the program won't really work as retrieved.  File: emacs, Node: Miscellaneous VC, Next: Customizing VC, Prev: Revision Tags, Up: Version Control 32.1.10 Miscellaneous Commands and Features of VC ------------------------------------------------- This section explains the less-frequently-used features of VC. * Menu: * Change Logs and VC:: Generating a change log file from log entries. * Renaming and VC:: A command to rename both the source and master file correctly. * Version Headers:: Inserting version control headers into working files.  File: emacs, Node: Change Logs and VC, Next: Renaming and VC, Up: Miscellaneous VC 32.1.10.1 Change Logs and VC ............................ If you use RCS or CVS for a program and also maintain a change log file for it (*note Change Log::), you can generate change log entries automatically from the version control log entries: `C-x v a' Visit the current directory's change log file and, for registered files in that directory, create new entries for versions checked in since the most recent entry in the change log file. (`vc-update-change-log'). This command works with RCS or CVS only, not with any of the other back ends. `C-u C-x v a' As above, but only find entries for the current buffer's file. `M-1 C-x v a' As above, but find entries for all the currently visited files that are maintained with version control. This works only with RCS, and it puts all entries in the log for the default directory, which may not be appropriate. For example, suppose the first line of `ChangeLog' is dated 1999-04-10, and that the only check-in since then was by Nathaniel Bowditch to `rcs2log' on 1999-05-22 with log text `Ignore log messages that start with `#'.'. Then `C-x v a' visits `ChangeLog' and inserts text like this: 1999-05-22 Nathaniel Bowditch * rcs2log: Ignore log messages that start with `#'. You can then edit the new change log entry further as you wish. Some of the new change log entries may duplicate what's already in ChangeLog. You will have to remove these duplicates by hand. Normally, the log entry for file `foo' is displayed as `* foo: TEXT OF LOG ENTRY'. The `:' after `foo' is omitted if the text of the log entry starts with `(FUNCTIONNAME): '. For example, if the log entry for `vc.el' is `(vc-do-command): Check call-process status.', then the text in `ChangeLog' looks like this: 1999-05-06 Nathaniel Bowditch * vc.el (vc-do-command): Check call-process status. When `C-x v a' adds several change log entries at once, it groups related log entries together if they all are checked in by the same author at nearly the same time. If the log entries for several such files all have the same text, it coalesces them into a single entry. For example, suppose the most recent check-ins have the following log entries: * For `vc.texinfo': `Fix expansion typos.' * For `vc.el': `Don't call expand-file-name.' * For `vc-hooks.el': `Don't call expand-file-name.' They appear like this in `ChangeLog': 1999-04-01 Nathaniel Bowditch * vc.texinfo: Fix expansion typos. * vc.el, vc-hooks.el: Don't call expand-file-name. Normally, `C-x v a' separates log entries by a blank line, but you can mark several related log entries to be clumped together (without an intervening blank line) by starting the text of each related log entry with a label of the form `{CLUMPNAME} '. The label itself is not copied to `ChangeLog'. For example, suppose the log entries are: * For `vc.texinfo': `{expand} Fix expansion typos.' * For `vc.el': `{expand} Don't call expand-file-name.' * For `vc-hooks.el': `{expand} Don't call expand-file-name.' Then the text in `ChangeLog' looks like this: 1999-04-01 Nathaniel Bowditch * vc.texinfo: Fix expansion typos. * vc.el, vc-hooks.el: Don't call expand-file-name. A log entry whose text begins with `#' is not copied to `ChangeLog'. For example, if you merely fix some misspellings in comments, you can log the change with an entry beginning with `#' to avoid putting such trivia into `ChangeLog'.  File: emacs, Node: Renaming and VC, Next: Version Headers, Prev: Change Logs and VC, Up: Miscellaneous VC 32.1.10.2 Renaming VC Work Files and Master Files ................................................. When you rename a registered file, you must also rename its master file correspondingly to get proper results. Use `vc-rename-file' to rename the source file as you specify, and rename its master file accordingly. It also updates any tags (*note Revision Tags::) that mention the file, so that they use the new name; despite this, the tag thus modified may not completely work (*note Revision Tag Caveats::). Some back ends do not provide an explicit rename operation to their repositories. After issuing `vc-rename-file', use `C-x v v' on the original and renamed buffers and provide the necessary edit log. You cannot use `vc-rename-file' on a file that is locked by someone else.  File: emacs, Node: Version Headers, Prev: Renaming and VC, Up: Miscellaneous VC 32.1.10.3 Inserting Version Control Headers ........................................... Sometimes it is convenient to put version identification strings directly into working files. Certain special strings called "version headers" are replaced in each successive version by the number of that version, the name of the user who created it, and other relevant information. All of the back ends that VC supports have such a mechanism, except GNU Arch. VC does not normally use the information contained in these headers. The exception is RCS--with RCS, version headers are sometimes more reliable than the master file to determine which version of the file you are editing. Note that in a multi-branch environment, version headers are necessary to make VC behave correctly (*note Multi-User Branching::). Searching for RCS version headers is controlled by the variable `vc-consult-headers'. If it is non-`nil' (the default), Emacs searches for headers to determine the version number you are editing. Setting it to `nil' disables this feature. Note that although CVS uses the same kind of version headers as RCS does, VC never searches for these headers if you are using CVS, regardless of the above setting. You can use the `C-x v h' command (`vc-insert-headers') to insert a suitable header string. `C-x v h' Insert headers in a file for use with your version-control system. The default header string is `$Id$' for RCS and `%W%' for SCCS. You can specify other headers to insert by setting the variables `vc-BACKEND-header' where BACKEND is `rcs' or `sccs'. Instead of a single string, you can specify a list of strings; then each string in the list is inserted as a separate header on a line of its own. It may be necessary to use apparently-superfluous backslashes when writing the strings that you put in this variable. For instance, you might write `"$Id\$"' rather than `"$Id$"'. The extra backslash prevents the string constant from being interpreted as a header, if the Emacs Lisp file containing it is maintained with version control. Each header is inserted surrounded by tabs, inside comment delimiters, on a new line at point. Normally the ordinary comment start and comment end strings of the current mode are used, but for certain modes, there are special comment delimiters for this purpose; the variable `vc-comment-alist' specifies them. Each element of this list has the form `(MODE STARTER ENDER)'. The variable `vc-static-header-alist' specifies further strings to add based on the name of the buffer. Its value should be a list of elements of the form `(REGEXP . FORMAT)'. Whenever REGEXP matches the buffer name, FORMAT is inserted as part of the header. A header line is inserted for each element that matches the buffer name, and for each string specified by `vc-BACKEND-header'. The header line is made by processing the string from `vc-BACKEND-header' with the format taken from the element. The default value for `vc-static-header-alist' is as follows: (("\\.c$" . "\n#ifndef lint\nstatic char vcid[] = \"\%s\";\n\ #endif /* lint */\n")) It specifies insertion of text of this form: #ifndef lint static char vcid[] = "STRING"; #endif /* lint */ Note that the text above starts with a blank line. If you use more than one version header in a file, put them close together in the file. The mechanism in `revert-buffer' that preserves markers may not handle markers positioned between two version headers.  File: emacs, Node: Customizing VC, Prev: Miscellaneous VC, Up: Version Control 32.1.11 Customizing VC ---------------------- The variable `vc-handled-backends' determines which version control systems VC should handle. The default value is `(RCS CVS SVN SCCS BZR GIT HG Arch)', so it contains all the version systems that are currently supported. If you want VC to ignore one or more of these systems, exclude its name from the list. To disable VC entirely, set this variable to `nil'. The order of systems in the list is significant: when you visit a file registered in more than one system (*note Local Version Control::), VC uses the system that comes first in `vc-handled-backends' by default. The order is also significant when you register a file for the first time, see *note Registering::, for details. * Menu: * General VC Options:: Options that apply to multiple back ends. * RCS and SCCS:: Options for RCS and SCCS. * CVS Options:: Options for CVS.  File: emacs, Node: General VC Options, Next: RCS and SCCS, Up: Customizing VC 32.1.11.1 General Options ......................... Emacs normally does not save backup files for source files that are maintained with version control. If you want to make backup files even for files that use version control, set the variable `vc-make-backup-files' to a non-`nil' value. Normally the work file exists all the time, whether it is locked or not. If you set `vc-keep-workfiles' to `nil', then checking in a new version with `C-x v v' deletes the work file; but any attempt to visit the file with Emacs creates it again. (With CVS, work files are always kept.) Editing a version-controlled file through a symbolic link can be dangerous. It bypasses the version control system--you can edit the file without locking it, and fail to check your changes in. Also, your changes might overwrite those of another user. To protect against this, VC checks each symbolic link that you visit, to see if it points to a file under version control. The variable `vc-follow-symlinks' controls what to do when a symbolic link points to a version-controlled file. If it is `nil', VC only displays a warning message. If it is `t', VC automatically follows the link, and visits the real file instead, telling you about this in the echo area. If the value is `ask' (the default), VC asks you each time whether to follow the link. If `vc-suppress-confirm' is non-`nil', then `C-x v v' and `C-x v i' can save the current buffer without asking, and `C-x v u' also operates without asking for confirmation. (This variable does not affect `C-x v c'; that operation is so drastic that it should always ask for confirmation.) VC mode does much of its work by running the shell commands for RCS, CVS and SCCS. If `vc-command-messages' is non-`nil', VC displays messages to indicate which shell commands it runs, and additional messages when the commands finish. You can specify additional directories to search for version control programs by setting the variable `vc-path'. These directories are searched before the usual search path. It is rarely necessary to set this variable, because VC normally finds the proper files automatically.  File: emacs, Node: RCS and SCCS, Next: CVS Options, Prev: General VC Options, Up: Customizing VC 32.1.11.2 Options for RCS and SCCS .................................. By default, RCS uses locking to coordinate the activities of several users, but there is a mode called "non-strict locking" in which you can check-in changes without locking the file first. Use `rcs -U' to switch to non-strict locking for a particular file, see the `rcs' manual page for details. When deducing the version control state of an RCS file, VC first looks for an RCS version header string in the file (*note Version Headers::). If there is no header string, VC normally looks at the file permissions of the work file; this is fast. But there might be situations when the file permissions cannot be trusted. In this case the master file has to be consulted, which is rather expensive. Also the master file can only tell you _if_ there's any lock on the file, but not whether your work file really contains that locked version. You can tell VC not to use version headers to determine the file status by setting `vc-consult-headers' to `nil'. VC then always uses the file permissions (if it is supposed to trust them), or else checks the master file. You can specify the criterion for whether to trust the file permissions by setting the variable `vc-mistrust-permissions'. Its value can be `t' (always mistrust the file permissions and check the master file), `nil' (always trust the file permissions), or a function of one argument which makes the decision. The argument is the directory name of the `RCS' subdirectory. A non-`nil' value from the function says to mistrust the file permissions. If you find that the file permissions of work files are changed erroneously, set `vc-mistrust-permissions' to `t'. Then VC always checks the master file to determine the file's status. VC determines the version control state of files under SCCS much as with RCS. It does not consider SCCS version headers, though. Thus, the variable `vc-mistrust-permissions' affects SCCS use, but `vc-consult-headers' does not.  File: emacs, Node: CVS Options, Prev: RCS and SCCS, Up: Customizing VC 32.1.11.3 Options specific for CVS .................................. By default, CVS does not use locking to coordinate the activities of several users; anyone can change a work file at any time. However, there are ways to restrict this, resulting in behavior that resembles locking. For one thing, you can set the `CVSREAD' environment variable (the value you use makes no difference). If this variable is defined, CVS makes your work files read-only by default. In Emacs, you must type `C-x v v' to make the file writable, so that editing works in fact similar as if locking was used. Note however, that no actual locking is performed, so several users can make their files writable at the same time. When setting `CVSREAD' for the first time, make sure to check out all your modules anew, so that the file protections are set correctly. Another way to achieve something similar to locking is to use the "watch" feature of CVS. If a file is being watched, CVS makes it read-only by default, and you must also use `C-x v v' in Emacs to make it writable. VC calls `cvs edit' to make the file writable, and CVS takes care to notify other developers of the fact that you intend to change the file. See the CVS documentation for details on using the watch feature. When a file's repository is on a remote machine, VC tries to keep network interactions to a minimum. This is controlled by the variable `vc-cvs-stay-local'. There is another variable, `vc-stay-local', which enables the feature also for other back ends that support it, including CVS. In the following, we will talk only about `vc-cvs-stay-local', but everything applies to `vc-stay-local' as well. If `vc-cvs-stay-local' is `t' (the default), then VC uses only the entry in the local CVS subdirectory to determine the file's state (and possibly information returned by previous CVS commands). One consequence of this is that when you have modified a file, and somebody else has already checked in other changes to the file, you are not notified of it until you actually try to commit. (But you can try to pick up any recent changes from the repository first, using `C-x v m ', *note Merging::). When `vc-cvs-stay-local' is `t', VC also makes local version backups, so that simple diff and revert operations are completely local (*note Version Backups::). On the other hand, if you set `vc-cvs-stay-local' to `nil', then VC queries the remote repository _before_ it decides what to do in `vc-next-action' (`C-x v v'), just as it does for local repositories. It also does not make any version backups. You can also set `vc-cvs-stay-local' to a regular expression that is matched against the repository host name; VC then stays local only for repositories from hosts that match the pattern. You can specify additional command line options to pass to all CVS operations in the variable `vc-cvs-global-switches'. These switches are inserted immediately after the `cvs' command, before the name of the operation to invoke.  File: emacs, Node: Change Log, Next: Tags, Prev: Version Control, Up: Maintaining 32.2 Change Logs ================ A change log file contains a chronological record of when and why you have changed a program, consisting of a sequence of entries describing individual changes. Normally it is kept in a file called `ChangeLog' in the same directory as the file you are editing, or one of its parent directories. A single `ChangeLog' file can record changes for all the files in its directory and all its subdirectories. * Menu: * Change Log Commands:: Commands for editing change log files. * Format of ChangeLog:: What the change log file looks like.  File: emacs, Node: Change Log Commands, Next: Format of ChangeLog, Up: Change Log 32.2.1 Change Log Commands -------------------------- The Emacs command `C-x 4 a' adds a new entry to the change log file for the file you are editing (`add-change-log-entry-other-window'). If that file is actually a backup file, it makes an entry appropriate for the file's parent--that is useful for making log entries for functions that have been deleted in the current version. `C-x 4 a' visits the change log file and creates a new entry unless the most recent entry is for today's date and your name. It also creates a new item for the current file. For many languages, it can even guess the name of the function or other object that was changed. When the variable `add-log-keep-changes-together' is non-`nil', `C-x 4 a' adds to any existing item for the file rather than starting a new item. If `add-log-always-start-new-record' is non-`nil', `C-x 4 a' always makes a new entry, even if the last entry was made by you and on the same date. If the value of the variable `change-log-version-info-enabled' is non-`nil', `C-x 4 a' adds the file's version number to the change log entry. It finds the version number by searching the first ten percent of the file, using regular expressions from the variable `change-log-version-number-regexp-list'. The change log file is visited in Change Log mode. In this major mode, each bunch of grouped items counts as one paragraph, and each entry is considered a page. This facilitates editing the entries. `C-j' and auto-fill indent each new line like the previous line; this is convenient for entering the contents of an entry. You can use the `next-error' command (by default bound to `C-x `') to move between entries in the Change Log, when Change Log mode is on. You will jump to the actual site in the file that was changed, not just to the next Change Log entry. You can also use `previous-error' to move back in the same list. You can use the command `M-x change-log-merge' to merge other log files into a buffer in Change Log Mode, preserving the date ordering of entries. Version control systems are another way to keep track of changes in your program and keep a change log. In the VC log buffer, typing `C-c C-a' (`log-edit-insert-changelog') inserts the relevant Change Log entry, if one exists (*note Log Buffer::). You can also insert a VC log entry into a Change Log buffer by typing `C-x v a' (`vc-update-change-log') in the Change Log buffer (*note Change Logs and VC::).  File: emacs, Node: Format of ChangeLog, Prev: Change Log Commands, Up: Change Log 32.2.2 Format of ChangeLog -------------------------- A change log entry starts with a header line that contains the current date, your name, and your email address (taken from the variable `add-log-mailing-address'). Aside from these header lines, every line in the change log starts with a space or a tab. The bulk of the entry consists of "items", each of which starts with a line starting with whitespace and a star. Here are two entries, both dated in May 1993, with two items and one item respectively. 1993-05-25 Richard Stallman * man.el: Rename symbols `man-*' to `Man-*'. (manual-entry): Make prompt string clearer. * simple.el (blink-matching-paren-distance): Change default to 12,000. 1993-05-24 Richard Stallman * vc.el (minor-mode-map-alist): Don't use it if it's void. (vc-cancel-version): Doc fix. One entry can describe several changes; each change should have its own item, or its own line in an item. Normally there should be a blank line between items. When items are related (parts of the same change, in different places), group them by leaving no blank line between them. You should put a copyright notice and permission notice at the end of the change log file. Here is an example: Copyright 1997, 1998 Free Software Foundation, Inc. Copying and distribution of this file, with or without modification, are permitted provided the copyright notice and this notice are preserved. Of course, you should substitute the proper years and copyright holder.  File: emacs, Node: Tags, Next: EDE, Prev: Change Log, Up: Maintaining 32.3 Tags Tables ================ A "tag" is a reference to a subunit in a program or in a document. In program source code, tags reference syntactic elements of the program: functions, subroutines, data types, macros, etc. In a document, tags reference chapters, sections, appendices, etc. Each tag specifies the name of the file where the corresponding subunit is defined, and the position of the subunit's definition in that file. A "tags table" records the tags extracted by scanning the source code of a certain program or a certain document. Tags extracted from generated files reference the original files, rather than the generated files that were scanned during tag extraction. Examples of generated files include C files generated from Cweb source files, from a Yacc parser, or from Lex scanner definitions; `.i' preprocessed C files; and Fortran files produced by preprocessing `.fpp' source files. To produce a tags table, you use the `etags' command, submitting it a document or the source code of a program. `etags' writes the tags to a "tags table file", or "tags file" in short. The conventional name for a tags file is `TAGS'. Emacs uses the information recorded in tags tables in commands that search or replace through multiple source files: these commands use the names of the source files recorded in the tags table to know which files to search. Other commands, such as `M-.', which finds the definition of a function, use the recorded information about the function names and positions to find the source file and the position within that file where the function is defined. See also the Ebrowse facility, which is tailored for C++. *Note Ebrowse: (ebrowse)Top. * Menu: * Tag Syntax:: Tag syntax for various types of code and text files. * Create Tags Table:: Creating a tags table with `etags'. * Etags Regexps:: Create arbitrary tags using regular expressions. * Select Tags Table:: How to visit a tags table. * Find Tag:: Commands to find the definition of a specific tag. * Tags Search:: Using a tags table for searching and replacing. * List Tags:: Listing and finding tags defined in a file.  File: emacs, Node: Tag Syntax, Next: Create Tags Table, Up: Tags 32.3.1 Source File Tag Syntax ----------------------------- Here is how tag syntax is defined for the most popular languages: * In C code, any C function or typedef is a tag, and so are definitions of `struct', `union' and `enum'. `#define' macro definitions, `#undef' and `enum' constants are also tags, unless you specify `--no-defines' when making the tags table. Similarly, global variables are tags, unless you specify `--no-globals', and so are struct members, unless you specify `--no-members'. Use of `--no-globals', `--no-defines' and `--no-members' can make the tags table file much smaller. You can tag function declarations and external variables in addition to function definitions by giving the `--declarations' option to `etags'. * In C++ code, in addition to all the tag constructs of C code, member functions are also recognized; member variables are also recognized, unless you use the `--no-members' option. Tags for variables and functions in classes are named `CLASS::VARIABLE' and `CLASS::FUNCTION'. `operator' definitions have tag names like `operator+'. * In Java code, tags include all the constructs recognized in C++, plus the `interface', `extends' and `implements' constructs. Tags for variables and functions in classes are named `CLASS.VARIABLE' and `CLASS.FUNCTION'. * In LaTeX text, the argument of any of the commands `\chapter', `\section', `\subsection', `\subsubsection', `\eqno', `\label', `\ref', `\cite', `\bibitem', `\part', `\appendix', `\entry', `\index', `\def', `\newcommand', `\renewcommand', `\newenvironment' or `\renewenvironment' is a tag. Other commands can make tags as well, if you specify them in the environment variable `TEXTAGS' before invoking `etags'. The value of this environment variable should be a colon-separated list of command names. For example, TEXTAGS="mycommand:myothercommand" export TEXTAGS specifies (using Bourne shell syntax) that the commands `\mycommand' and `\myothercommand' also define tags. * In Lisp code, any function defined with `defun', any variable defined with `defvar' or `defconst', and in general the first argument of any expression that starts with `(def' in column zero is a tag. * In Scheme code, tags include anything defined with `def' or with a construct whose name starts with `def'. They also include variables set with `set!' at top level in the file. Several other languages are also supported: * In Ada code, functions, procedures, packages, tasks and types are tags. Use the `--packages-only' option to create tags for packages only. In Ada, the same name can be used for different kinds of entity (e.g., for a procedure and for a function). Also, for things like packages, procedures and functions, there is the spec (i.e. the interface) and the body (i.e. the implementation). To make it easier to pick the definition you want, Ada tag name have suffixes indicating the type of entity: `/b' package body. `/f' function. `/k' task. `/p' procedure. `/s' package spec. `/t' type. Thus, `M-x find-tag bidule/b ' will go directly to the body of the package `bidule', while `M-x find-tag bidule ' will just search for any tag `bidule'. * In assembler code, labels appearing at the beginning of a line, followed by a colon, are tags. * In Bison or Yacc input files, each rule defines as a tag the nonterminal it constructs. The portions of the file that contain C code are parsed as C code. * In Cobol code, tags are paragraph names; that is, any word starting in column 8 and followed by a period. * In Erlang code, the tags are the functions, records and macros defined in the file. * In Fortran code, functions, subroutines and block data are tags. * In HTML input files, the tags are the `title' and the `h1', `h2', `h3' headers. Also, tags are `name=' in anchors and all occurrences of `id='. * In Lua input files, all functions are tags. * In makefiles, targets are tags; additionally, variables are tags unless you specify `--no-globals'. * In Objective C code, tags include Objective C definitions for classes, class categories, methods and protocols. Tags for variables and functions in classes are named `CLASS::VARIABLE' and `CLASS::FUNCTION'. * In Pascal code, the tags are the functions and procedures defined in the file. * In Perl code, the tags are the packages, subroutines and variables defined by the `package', `sub', `my' and `local' keywords. Use `--globals' if you want to tag global variables. Tags for subroutines are named `PACKAGE::SUB'. The name for subroutines defined in the default package is `main::SUB'. * In PHP code, tags are functions, classes and defines. Vars are tags too, unless you use the `--no-members' option. * In PostScript code, the tags are the functions. * In Prolog code, tags are predicates and rules at the beginning of line. * In Python code, `def' or `class' at the beginning of a line generate a tag. You can also generate tags based on regexp matching (*note Etags Regexps::) to handle other formats and languages.  File: emacs, Node: Create Tags Table, Next: Etags Regexps, Prev: Tag Syntax, Up: Tags 32.3.2 Creating Tags Tables --------------------------- The `etags' program is used to create a tags table file. It knows the syntax of several languages, as described in *note Tag Syntax::. Here is how to run `etags': etags INPUTFILES... The `etags' program reads the specified files, and writes a tags table named `TAGS' in the current working directory. You can optionally specify a different file name for the tags table by using the `--output=FILE' option; specifying `-' as a file name prints the tags table to standard output. If the specified files don't exist, `etags' looks for compressed versions of them and uncompresses them to read them. Under MS-DOS, `etags' also looks for file names like `mycode.cgz' if it is given `mycode.c' on the command line and `mycode.c' does not exist. `etags' recognizes the language used in an input file based on its file name and contents. You can specify the language with the `--language=NAME' option, described below. If the tags table data become outdated due to changes in the files described in the table, the way to update the tags table is the same way it was made in the first place. If the tags table fails to record a tag, or records it for the wrong file, then Emacs cannot possibly find its definition until you update the tags table. However, if the position recorded in the tags table becomes a little bit wrong (due to other editing), the worst consequence is a slight delay in finding the tag. Even if the stored position is very far wrong, Emacs will still find the tag, after searching most of the file for it. That delay is hardly noticeable with today's computers. Thus, there is no need to update the tags table after each edit. You should update a tags table when you define new tags that you want to have listed, or when you move tag definitions from one file to another, or when changes become substantial. One tags table can virtually include another. Specify the included tags file name with the `--include=FILE' option when creating the file that is to include it. The latter file then acts as if it covered all the source files specified in the included file, as well as the files it directly contains. If you specify the source files with relative file names when you run `etags', the tags file will contain file names relative to the directory where the tags file was initially written. This way, you can move an entire directory tree containing both the tags file and the source files, and the tags file will still refer correctly to the source files. If the tags file is `-' or is in the `/dev' directory, however, the file names are made relative to the current working directory. This is useful, for example, when writing the tags to `/dev/stdout'. When using a relative file name, it should not be a symbolic link pointing to a tags file in a different directory, because this would generally render the file names invalid. If you specify absolute file names as arguments to `etags', then the tags file will contain absolute file names. This way, the tags file will still refer to the same files even if you move it, as long as the source files remain in the same place. Absolute file names start with `/', or with `DEVICE:/' on MS-DOS and MS-Windows. When you want to make a tags table from a great number of files, you may have problems listing them on the command line, because some systems have a limit on its length. The simplest way to circumvent this limit is to tell `etags' to read the file names from its standard input, by typing a dash in place of the file names, like this: find . -name "*.[chCH]" -print | etags - Use the option `--language=NAME' to specify the language explicitly. You can intermix these options with file names; each one applies to the file names that follow it. Specify `--language=auto' to tell `etags' to resume guessing the language from the file names and file contents. Specify `--language=none' to turn off language-specific processing entirely; then `etags' recognizes tags by regexp matching alone (*note Etags Regexps::). The option `--parse-stdin=FILE' is mostly useful when calling `etags' from programs. It can be used (only once) in place of a file name on the command line. `Etags' will read from standard input and mark the produced tags as belonging to the file FILE. `etags --help' outputs the list of the languages `etags' knows, and the file name rules for guessing the language. It also prints a list of all the available `etags' options, together with a short explanation. If followed by one or more `--language=LANG' options, it outputs detailed information about how tags are generated for LANG.  File: emacs, Node: Etags Regexps, Next: Select Tags Table, Prev: Create Tags Table, Up: Tags 32.3.3 Etags Regexps -------------------- The `--regex' option provides a general way of recognizing tags based on regexp matching. You can freely intermix this option with file names, and each one applies to the source files that follow it. If you specify multiple `--regex' options, all of them are used in parallel. The syntax is: --regex=[{LANGUAGE}]/TAGREGEXP/[NAMEREGEXP/]MODIFIERS The essential part of the option value is TAGREGEXP, the regexp for matching tags. It is always used anchored, that is, it only matches at the beginning of a line. If you want to allow indented tags, use a regexp that matches initial whitespace; start it with `[ \t]*'. In these regular expressions, `\' quotes the next character, and all the GCC character escape sequences are supported (`\a' for bell, `\b' for back space, `\d' for delete, `\e' for escape, `\f' for formfeed, `\n' for newline, `\r' for carriage return, `\t' for tab, and `\v' for vertical tab). Ideally, TAGREGEXP should not match more characters than are needed to recognize what you want to tag. If the syntax requires you to write TAGREGEXP so it matches more characters beyond the tag itself, you should add a NAMEREGEXP, to pick out just the tag. This will enable Emacs to find tags more accurately and to do completion on tag names more reliably. You can find some examples below. The MODIFIERS are a sequence of zero or more characters that modify the way `etags' does the matching. A regexp with no modifiers is applied sequentially to each line of the input file, in a case-sensitive way. The modifiers and their meanings are: `i' Ignore case when matching this regexp. `m' Match this regular expression against the whole file, so that multi-line matches are possible. `s' Match this regular expression against the whole file, and allow `.' in TAGREGEXP to match newlines. The `-R' option cancels all the regexps defined by preceding `--regex' options. It too applies to the file names following it. Here's an example: etags --regex=/REG1/i voo.doo --regex=/REG2/m \ bar.ber -R --lang=lisp los.er Here `etags' chooses the parsing language for `voo.doo' and `bar.ber' according to their contents. `etags' also uses REG1 to recognize additional tags in `voo.doo', and both REG1 and REG2 to recognize additional tags in `bar.ber'. REG1 is checked against each line of `voo.doo' and `bar.ber', in a case-insensitive way, while REG2 is checked against the whole `bar.ber' file, permitting multi-line matches, in a case-sensitive way. `etags' uses only the Lisp tags rules, with no user-specified regexp matching, to recognize tags in `los.er'. You can restrict a `--regex' option to match only files of a given language by using the optional prefix {LANGUAGE}. (`etags --help' prints the list of languages recognized by `etags'.) This is particularly useful when storing many predefined regular expressions for `etags' in a file. The following example tags the `DEFVAR' macros in the Emacs source files, for the C language only: --regex='{c}/[ \t]*DEFVAR_[A-Z_ \t(]+"\([^"]+\)"/' When you have complex regular expressions, you can store the list of them in a file. The following option syntax instructs `etags' to read two files of regular expressions. The regular expressions contained in the second file are matched without regard to case. --regex=@CASE-SENSITIVE-FILE --ignore-case-regex=@IGNORE-CASE-FILE A regex file for `etags' contains one regular expression per line. Empty lines, and lines beginning with space or tab are ignored. When the first character in a line is `@', `etags' assumes that the rest of the line is the name of another file of regular expressions; thus, one such file can include another file. All the other lines are taken to be regular expressions. If the first non-whitespace text on the line is `--', that line is a comment. For example, we can create a file called `emacs.tags' with the following contents: -- This is for GNU Emacs C source files {c}/[ \t]*DEFVAR_[A-Z_ \t(]+"\([^"]+\)"/\1/ and then use it like this: etags --regex=@emacs.tags *.[ch] */*.[ch] Here are some more examples. The regexps are quoted to protect them from shell interpretation. * Tag Octave files: etags --language=none \ --regex='/[ \t]*function.*=[ \t]*\([^ \t]*\)[ \t]*(/\1/' \ --regex='/###key \(.*\)/\1/' \ --regex='/[ \t]*global[ \t].*/' \ *.m Note that tags are not generated for scripts, so that you have to add a line by yourself of the form `###key SCRIPTNAME' if you want to jump to it. * Tag Tcl files: etags --language=none --regex='/proc[ \t]+\([^ \t]+\)/\1/' *.tcl * Tag VHDL files: etags --language=none \ --regex='/[ \t]*\(ARCHITECTURE\|CONFIGURATION\) +[^ ]* +OF/' \ --regex='/[ \t]*\(ATTRIBUTE\|ENTITY\|FUNCTION\|PACKAGE\ \( BODY\)?\|PROCEDURE\|PROCESS\|TYPE\)[ \t]+\([^ \t(]+\)/\3/'  File: emacs, Node: Select Tags Table, Next: Find Tag, Prev: Etags Regexps, Up: Tags 32.3.4 Selecting a Tags Table ----------------------------- Emacs has at any time one "selected" tags table, and all the commands for working with tags tables use the selected one. To select a tags table, type `M-x visit-tags-table', which reads the tags table file name as an argument, with `TAGS' in the default directory as the default. Emacs does not actually read in the tags table contents until you try to use them; all `visit-tags-table' does is store the file name in the variable `tags-file-name', and setting the variable yourself is just as good. The variable's initial value is `nil'; that value tells all the commands for working with tags tables that they must ask for a tags table file name to use. Using `visit-tags-table' when a tags table is already loaded gives you a choice: you can add the new tags table to the current list of tags tables, or start a new list. The tags commands use all the tags tables in the current list. If you start a new list, the new tags table is used _instead_ of others. If you add the new table to the current list, it is used _as well as_ the others. You can specify a precise list of tags tables by setting the variable `tags-table-list' to a list of strings, like this: (setq tags-table-list '("~/emacs" "/usr/local/lib/emacs/src")) This tells the tags commands to look at the `TAGS' files in your `~/emacs' directory and in the `/usr/local/lib/emacs/src' directory. The order depends on which file you are in and which tags table mentions that file, as explained above. Do not set both `tags-file-name' and `tags-table-list'.  File: emacs, Node: Find Tag, Next: Tags Search, Prev: Select Tags Table, Up: Tags 32.3.5 Finding a Tag -------------------- The most important thing that a tags table enables you to do is to find the definition of a specific tag. `M-. TAG ' Find first definition of TAG (`find-tag'). `C-u M-.' Find next alternate definition of last tag specified. `C-u - M-.' Go back to previous tag found. `C-M-. PATTERN ' Find a tag whose name matches PATTERN (`find-tag-regexp'). `C-u C-M-.' Find the next tag whose name matches the last pattern used. `C-x 4 . TAG ' Find first definition of TAG, but display it in another window (`find-tag-other-window'). `C-x 5 . TAG ' Find first definition of TAG, and create a new frame to select the buffer (`find-tag-other-frame'). `M-*' Pop back to where you previously invoked `M-.' and friends. `M-.' (`find-tag') is the command to find the definition of a specified tag. It searches through the tags table for that tag, as a string, and then uses the tags table info to determine the file that the definition is in and the approximate character position in the file of the definition. Then `find-tag' visits that file, moves point to the approximate character position, and searches ever-increasing distances away to find the tag definition. If an empty argument is given (just type ), the balanced expression in the buffer before or around point is used as the TAG argument. *Note Expressions::. You don't need to give `M-.' the full name of the tag; a part will do. This is because `M-.' finds tags in the table which contain TAG as a substring. However, it prefers an exact match to a substring match. To find other tags that match the same substring, give `find-tag' a numeric argument, as in `C-u M-.'; this does not read a tag name, but continues searching the tags table's text for another tag containing the same substring last used. If you have a real key, `M-0 M-.' is an easier alternative to `C-u M-.'. Like most commands that can switch buffers, `find-tag' has a variant that displays the new buffer in another window, and one that makes a new frame for it. The former is `C-x 4 .', which invokes the command `find-tag-other-window'. The latter is `C-x 5 .', which invokes `find-tag-other-frame'. To move back to places you've found tags recently, use `C-u - M-.'; more generally, `M-.' with a negative numeric argument. This command can take you to another buffer. `C-x 4 .' with a negative argument finds the previous tag location in another window. As well as going back to places you've found tags recently, you can go back to places _from where_ you found them. Use `M-*', which invokes the command `pop-tag-mark', for this. Typically you would find and study the definition of something with `M-.' and then return to where you were with `M-*'. Both `C-u - M-.' and `M-*' allow you to retrace your steps to a depth determined by the variable `find-tag-marker-ring-length'. The command `C-M-.' (`find-tag-regexp') visits the tags that match a specified regular expression. It is just like `M-.' except that it does regexp matching instead of substring matching.  File: emacs, Node: Tags Search, Next: List Tags, Prev: Find Tag, Up: Tags 32.3.6 Searching and Replacing with Tags Tables ----------------------------------------------- The commands in this section visit and search all the files listed in the selected tags table, one by one. For these commands, the tags table serves only to specify a sequence of files to search. These commands scan the list of tags tables starting with the first tags table (if any) that describes the current file, proceed from there to the end of the list, and then scan from the beginning of the list until they have covered all the tables in the list. `M-x tags-search REGEXP ' Search for REGEXP through the files in the selected tags table. `M-x tags-query-replace REGEXP REPLACEMENT ' Perform a `query-replace-regexp' on each file in the selected tags table. `M-,' Restart one of the commands above, from the current location of point (`tags-loop-continue'). `M-x tags-search' reads a regexp using the minibuffer, then searches for matches in all the files in the selected tags table, one file at a time. It displays the name of the file being searched so you can follow its progress. As soon as it finds an occurrence, `tags-search' returns. Having found one match, you probably want to find all the rest. To find one more match, type `M-,' (`tags-loop-continue') to resume the `tags-search'. This searches the rest of the current buffer, followed by the remaining files of the tags table. `M-x tags-query-replace' performs a single `query-replace-regexp' through all the files in the tags table. It reads a regexp to search for and a string to replace with, just like ordinary `M-x query-replace-regexp'. It searches much like `M-x tags-search', but repeatedly, processing matches according to your input. *Note Replace::, for more information on query replace. You can control the case-sensitivity of tags search commands by customizing the value of the variable `tags-case-fold-search'. The default is to use the same setting as the value of `case-fold-search' (*note Search Case::). It is possible to get through all the files in the tags table with a single invocation of `M-x tags-query-replace'. But often it is useful to exit temporarily, which you can do with any input event that has no special query replace meaning. You can resume the query replace subsequently by typing `M-,'; this command resumes the last tags search or replace command that you did. For instance, to skip the rest of the current file, you can type `M-> M-,'. The commands in this section carry out much broader searches than the `find-tag' family. The `find-tag' commands search only for definitions of tags that match your substring or regexp. The commands `tags-search' and `tags-query-replace' find every occurrence of the regexp, as ordinary search commands and replace commands do in the current buffer. These commands create buffers only temporarily for the files that they have to search (those which are not already visited in Emacs buffers). Buffers in which no match is found are quickly killed; the others continue to exist. It may have struck you that `tags-search' is a lot like `grep'. You can also run `grep' itself as an inferior of Emacs and have Emacs show you the matching lines one by one. *Note Grep Searching::.  File: emacs, Node: List Tags, Prev: Tags Search, Up: Tags 32.3.7 Tags Table Inquiries --------------------------- `M-x list-tags FILE ' Display a list of the tags defined in the program file FILE. `M-x tags-apropos REGEXP ' Display a list of all tags matching REGEXP. `M-x list-tags' reads the name of one of the files described by the selected tags table, and displays a list of all the tags defined in that file. The "file name" argument is really just a string to compare against the file names recorded in the tags table; it is read as a string rather than as a file name. Therefore, completion and defaulting are not available, and you must enter the file name the same way it appears in the tags table. Do not include a directory as part of the file name unless the file name recorded in the tags table includes a directory. `M-x tags-apropos' is like `apropos' for tags (*note Apropos::). It finds all the tags in the selected tags table whose entries match REGEXP, and displays them. If the variable `tags-apropos-verbose' is non-`nil', it displays the names of the tags files together with the tag names. You can customize the appearance of the output by setting the variable `tags-tag-face' to a face. You can display additional output with `M-x tags-apropos' by customizing the variable `tags-apropos-additional-actions'--see its documentation for details. You can also use the collection of tag names to complete a symbol name in the buffer. *Note Symbol Completion::.  File: emacs, Node: Emerge, Prev: EDE, Up: Maintaining 32.4 Merging Files with Emerge ============================== It's not unusual for programmers to get their signals crossed and modify the same program in two different directions. To recover from this confusion, you need to merge the two versions. Emerge makes this easier. For other ways to compare files, see *note Comparing Files::, and *note Ediff: (ediff)Top. * Menu: * Overview of Emerge:: How to start Emerge. Basic concepts. * Submodes of Emerge:: Fast mode vs. Edit mode. Skip Prefers mode and Auto Advance mode. * State of Difference:: You do the merge by specifying state A or B for each difference. * Merge Commands:: Commands for selecting a difference, changing states of differences, etc. * Exiting Emerge:: What to do when you've finished the merge. * Combining in Emerge:: How to keep both alternatives for a difference. * Fine Points of Emerge:: Miscellaneous issues.  File: emacs, Node: Overview of Emerge, Next: Submodes of Emerge, Up: Emerge 32.4.1 Overview of Emerge ------------------------- To start Emerge, run one of these four commands: `M-x emerge-files' Merge two specified files. `M-x emerge-files-with-ancestor' Merge two specified files, with reference to a common ancestor. `M-x emerge-buffers' Merge two buffers. `M-x emerge-buffers-with-ancestor' Merge two buffers with reference to a common ancestor in a third buffer. The Emerge commands compare two files or buffers, and display the comparison in three buffers: one for each input text (the "A buffer" and the "B buffer"), and one (the "merge buffer") where merging takes place. The merge buffer shows the full merged text, not just the differences. Wherever the two input texts differ, you can choose which one of them to include in the merge buffer. The Emerge commands that take input from existing buffers use only the accessible portions of those buffers, if they are narrowed. *Note Narrowing::. If a common ancestor version is available, from which the two texts to be merged were both derived, Emerge can use it to guess which alternative is right. Wherever one current version agrees with the ancestor, Emerge presumes that the other current version is a deliberate change which should be kept in the merged version. Use the `with-ancestor' commands if you want to specify a common ancestor text. These commands read three file or buffer names--variant A, variant B, and the common ancestor. After the comparison is done and the buffers are prepared, the interactive merging starts. You control the merging by typing special "merge commands" in the merge buffer (*note Merge Commands::). For each run of differences between the input texts, you can choose which one of them to keep, or edit them both together. The merge buffer uses a special major mode, Emerge mode, with commands for making these choices. But you can also edit the buffer with ordinary Emacs commands. At any given time, the attention of Emerge is focused on one particular difference, called the "selected" difference. This difference is marked off in the three buffers like this: vvvvvvvvvvvvvvvvvvvv TEXT THAT DIFFERS ^^^^^^^^^^^^^^^^^^^^ Emerge numbers all the differences sequentially and the mode line always shows the number of the selected difference. Normally, the merge buffer starts out with the A version of the text. But when the A version of a difference agrees with the common ancestor, then the B version is initially preferred for that difference. Emerge leaves the merged text in the merge buffer when you exit. At that point, you can save it in a file with `C-x C-w'. If you give a numeric argument to `emerge-files' or `emerge-files-with-ancestor', it reads the name of the output file using the minibuffer. (This is the last file name those commands read.) Then exiting from Emerge saves the merged text in the output file. Normally, Emerge commands save the output buffer in its file when you exit. If you abort Emerge with `C-]', the Emerge command does not save the output buffer, but you can save it yourself if you wish.  File: emacs, Node: Submodes of Emerge, Next: State of Difference, Prev: Overview of Emerge, Up: Emerge 32.4.2 Submodes of Emerge ------------------------- You can choose between two modes for giving merge commands: Fast mode and Edit mode. In Fast mode, basic merge commands are single characters, but ordinary Emacs commands are disabled. This is convenient if you use only merge commands. In Edit mode, all merge commands start with the prefix key `C-c C-c', and the normal Emacs commands are also available. This allows editing the merge buffer, but slows down Emerge operations. Use `e' to switch to Edit mode, and `C-c C-c f' to switch to Fast mode. The mode line indicates Edit and Fast modes with `E' and `F'. Emerge has two additional submodes that affect how particular merge commands work: Auto Advance mode and Skip Prefers mode. If Auto Advance mode is in effect, the `a' and `b' commands advance to the next difference. This lets you go through the merge faster as long as you simply choose one of the alternatives from the input. The mode line indicates Auto Advance mode with `A'. If Skip Prefers mode is in effect, the `n' and `p' commands skip over differences in states "prefer-A" and "prefer-B" (*note State of Difference::). Thus you see only differences for which neither version is presumed "correct." The mode line indicates Skip Prefers mode with `S'. This mode is only relevant when there is an ancestor. Use the command `s a' (`emerge-auto-advance-mode') to set or clear Auto Advance mode. Use `s s' (`emerge-skip-prefers-mode') to set or clear Skip Prefers mode. These commands turn on the mode with a positive argument, turn it off with a negative or zero argument, and toggle the mode with no argument.  File: emacs, Node: State of Difference, Next: Merge Commands, Prev: Submodes of Emerge, Up: Emerge 32.4.3 State of a Difference ---------------------------- In the merge buffer, a difference is marked with lines of `v' and `^' characters. Each difference has one of these seven states: A The difference is showing the A version. The `a' command always produces this state; the mode line indicates it with `A'. B The difference is showing the B version. The `b' command always produces this state; the mode line indicates it with `B'. default-A default-B The difference is showing the A or the B state by default, because you haven't made a choice. All differences start in the default-A state (and thus the merge buffer is a copy of the A buffer), except those for which one alternative is "preferred" (see below). When you select a difference, its state changes from default-A or default-B to plain A or B. Thus, the selected difference never has state default-A or default-B, and these states are never displayed in the mode line. The command `d a' chooses default-A as the default state, and `d b' chooses default-B. This chosen default applies to all differences that you have never selected and for which no alternative is preferred. If you are moving through the merge sequentially, the differences you haven't selected are those following the selected one. Thus, while moving sequentially, you can effectively make the A version the default for some sections of the merge buffer and the B version the default for others by using `d a' and `d b' between sections. prefer-A prefer-B The difference is showing the A or B state because it is "preferred". This means that you haven't made an explicit choice, but one alternative seems likely to be right because the other alternative agrees with the common ancestor. Thus, where the A buffer agrees with the common ancestor, the B version is preferred, because chances are it is the one that was actually changed. These two states are displayed in the mode line as `A*' and `B*'. combined The difference is showing a combination of the A and B states, as a result of the `x c' or `x C' commands. Once a difference is in this state, the `a' and `b' commands don't do anything to it unless you give them a numeric argument. The mode line displays this state as `comb'.  File: emacs, Node: Merge Commands, Next: Exiting Emerge, Prev: State of Difference, Up: Emerge 32.4.4 Merge Commands --------------------- Here are the Merge commands for Fast mode; in Edit mode, precede them with `C-c C-c': `p' Select the previous difference. `n' Select the next difference. `a' Choose the A version of this difference. `b' Choose the B version of this difference. `C-u N j' Select difference number N. `.' Select the difference containing point. `q' Quit--finish the merge. `C-]' Abort--exit merging and do not save the output. `f' Go into Fast mode. (In Edit mode, this is actually `C-c C-c f'.) `e' Go into Edit mode. `l' Recenter (like `C-l') all three windows. With an argument, reestablish the default three-window display. `-' Specify part of a prefix numeric argument. `DIGIT' Also specify part of a prefix numeric argument. `d a' Choose the A version as the default from here down in the merge buffer. `d b' Choose the B version as the default from here down in the merge buffer. `c a' Copy the A version of this difference into the kill ring. `c b' Copy the B version of this difference into the kill ring. `i a' Insert the A version of this difference at point. `i b' Insert the B version of this difference at point. `m' Put point and mark around the difference. `^' Scroll all three windows down (like `M-v'). `v' Scroll all three windows up (like `C-v'). `<' Scroll all three windows left (like `C-x <'). `>' Scroll all three windows right (like `C-x >'). `|' Reset horizontal scroll on all three windows. `x 1' Shrink the merge window to one line. (Use `C-u l' to restore it to full size.) `x c' Combine the two versions of this difference (*note Combining in Emerge::). `x f' Show the names of the files/buffers Emerge is operating on, in a Help window. (Use `C-u l' to restore windows.) `x j' Join this difference with the following one. (`C-u x j' joins this difference with the previous one.) `x s' Split this difference into two differences. Before you use this command, position point in each of the three buffers at the place where you want to split the difference. `x t' Trim identical lines off the top and bottom of the difference. Such lines occur when the A and B versions are identical but differ from the ancestor version.  File: emacs, Node: Exiting Emerge, Next: Combining in Emerge, Prev: Merge Commands, Up: Emerge 32.4.5 Exiting Emerge --------------------- The `q' command (`emerge-quit') finishes the merge, storing the results into the output file if you specified one. It restores the A and B buffers to their proper contents, or kills them if they were created by Emerge and you haven't changed them. It also disables the Emerge commands in the merge buffer, since executing them later could damage the contents of the various buffers. `C-]' aborts the merge. This means exiting without writing the output file. If you didn't specify an output file, then there is no real difference between aborting and finishing the merge. If the Emerge command was called from another Lisp program, then its return value is `t' for successful completion, or `nil' if you abort.  File: emacs, Node: Combining in Emerge, Next: Fine Points of Emerge, Prev: Exiting Emerge, Up: Emerge 32.4.6 Combining the Two Versions --------------------------------- Sometimes you want to keep _both_ alternatives for a particular difference. To do this, use `x c', which edits the merge buffer like this: #ifdef NEW VERSION FROM A BUFFER #else /* not NEW */ VERSION FROM B BUFFER #endif /* not NEW */ While this example shows C preprocessor conditionals delimiting the two alternative versions, you can specify the strings to use by setting the variable `emerge-combine-versions-template' to a string of your choice. In the string, `%a' says where to put version A, and `%b' says where to put version B. The default setting, which produces the results shown above, looks like this: "#ifdef NEW\n%a#else /* not NEW */\n%b#endif /* not NEW */\n"  File: emacs, Node: Fine Points of Emerge, Prev: Combining in Emerge, Up: Emerge 32.4.7 Fine Points of Emerge ---------------------------- During the merge, you mustn't try to edit the A and B buffers yourself. Emerge modifies them temporarily, but ultimately puts them back the way they were. You can have any number of merges going at once--just don't use any one buffer as input to more than one merge at once, since the temporary changes made in these buffers would get in each other's way. Starting Emerge can take a long time because it needs to compare the files fully. Emacs can't do anything else until `diff' finishes. Perhaps in the future someone will change Emerge to do the comparison in the background when the input files are large--then you could keep on doing other things with Emacs until Emerge is ready to accept commands. After setting up the merge, Emerge runs the hook `emerge-startup-hook'. *Note Hooks::.  File: emacs, Node: EDE, Next: Emerge, Prev: Tags, Up: Maintaining 32.5 Emacs Development Environment ================================== EDE ("Emacs Development Environment") is a package that simplifies the task of creating, building, and debugging large programs with Emacs. It provides some of the features of an IDE, or "Integrated Development Environment", in Emacs. This section provides a brief description of EDE usage. For full details, see *note EDE: (ede)Top. EDE is implemented as a global minor mode (*note Minor Modes::). To enable it, type `M-x global-ede-mode' or click on the `Project Support (EDE)' item in the `Tools' menu. You can also enable EDE each time you start Emacs, by adding the following line to your initialization file: (global-ede-mode t) Activating EDE adds a menu named `Development' to the menu bar. Many EDE commands, including the ones described below, can be invoked from this menu. EDE organizes files into "projects", which correspond to directory trees. The "project root" is the topmost directory of a project. To define a new project, visit a file in the desired project root and type `M-x ede-new'. This command prompts for a "project type", which refers to the underlying method that EDE will use to manage the project (*note EDE: (ede)Creating a Project.). The most common project types are `Make', which uses Makefiles, and `Automake', which uses GNU Automake (*note Automake: (automake)Top.). In both cases, EDE also creates a file named `Project.ede', which stores information about the project. A project may contain one or more "targets". A target can be an object file, executable program, or some other type of file, which is "built" from one or more of the files in the project. To add a new "target" to a project, type `C-c . t' (`M-x ede-new-target'). This command also asks if you wish to "add" the current file to that target, which means that the target is to be built from that file. After you have defined a target, you can add more files to it by typing `C-c . a' (`ede-add-file'). To build a target, type `C-c . c' (`ede-compile-target'). To build all the targets in the project, type `C-c . C' (`ede-compile-project'). EDE uses the file types to guess how the target should be built.  File: emacs, Node: Abbrevs, Next: Picture Mode, Prev: Maintaining, Up: Top 33 Abbrevs ********** A defined "abbrev" is a word which "expands", if you insert it, into some different text. Abbrevs are defined by the user to expand in specific ways. For example, you might define `foo' as an abbrev expanding to `find outer otter'. Then you could insert `find outer otter ' into the buffer by typing `f o o '. A second kind of abbreviation facility is called "dynamic abbrev expansion". You use dynamic abbrev expansion with an explicit command to expand the letters in the buffer before point by looking for other words in the buffer that start with those letters. *Note Dynamic Abbrevs::. "Hippie" expansion generalizes abbreviation expansion. *Note Hippie Expansion: (autotype)Hippie Expand. * Menu: * Abbrev Concepts:: Fundamentals of defined abbrevs. * Defining Abbrevs:: Defining an abbrev, so it will expand when typed. * Expanding Abbrevs:: Controlling expansion: prefixes, canceling expansion. * Editing Abbrevs:: Viewing or editing the entire list of defined abbrevs. * Saving Abbrevs:: Saving the entire list of abbrevs for another session. * Dynamic Abbrevs:: Abbreviations for words already in the buffer. * Dabbrev Customization:: What is a word, for dynamic abbrevs. Case handling.  File: emacs, Node: Abbrev Concepts, Next: Defining Abbrevs, Up: Abbrevs 33.1 Abbrev Concepts ==================== An "abbrev" is a word which has been defined to "expand" into a specified "expansion". When you insert a word-separator character following the abbrev, that expands the abbrev--replacing the abbrev with its expansion. For example, if `foo' is defined as an abbrev expanding to `find outer otter', then you can insert `find outer otter.' into the buffer by typing `f o o .'. Abbrevs expand only when Abbrev mode (a minor mode) is enabled. Disabling Abbrev mode does not cause abbrev definitions to be forgotten, but they do not expand until Abbrev mode is enabled again. The command `M-x abbrev-mode' toggles Abbrev mode; with a numeric argument, it turns Abbrev mode on if the argument is positive, off otherwise. *Note Minor Modes::. `abbrev-mode' is also a variable; Abbrev mode is on when the variable is non-`nil'. The variable `abbrev-mode' automatically becomes local to the current buffer when it is set. Abbrevs can have "mode-specific" definitions, active only in one major mode. Abbrevs can also have "global" definitions that are active in all major modes. The same abbrev can have a global definition and various mode-specific definitions for different major modes. A mode-specific definition for the current major mode overrides a global definition. You can define abbrevs interactively during the editing session. You can also save lists of abbrev definitions in files for use in later sessions. Some users keep extensive lists of abbrevs that they load in every session.  File: emacs, Node: Defining Abbrevs, Next: Expanding Abbrevs, Prev: Abbrev Concepts, Up: Abbrevs 33.2 Defining Abbrevs ===================== `C-x a g' Define an abbrev, using one or more words before point as its expansion (`add-global-abbrev'). `C-x a l' Similar, but define an abbrev specific to the current major mode (`add-mode-abbrev'). `C-x a i g' Define a word in the buffer as an abbrev (`inverse-add-global-abbrev'). `C-x a i l' Define a word in the buffer as a mode-specific abbrev (`inverse-add-mode-abbrev'). `M-x define-global-abbrev ABBREV EXP ' Define ABBREV as an abbrev expanding into EXP. `M-x define-mode-abbrev ABBREV EXP ' Define ABBREV as a mode-specific abbrev expanding into EXP. `M-x kill-all-abbrevs' Discard all abbrev definitions, leaving a blank slate. The usual way to define an abbrev is to enter the text you want the abbrev to expand to, position point after it, and type `C-x a g' (`add-global-abbrev'). This reads the abbrev itself using the minibuffer, and then defines it as an abbrev for one or more words before point. Use a numeric argument to say how many words before point should be taken as the expansion. For example, to define the abbrev `foo' as mentioned above, insert the text `find outer otter' and then type `C-u 3 C-x a g f o o '. An argument of zero to `C-x a g' means to use the contents of the region as the expansion of the abbrev being defined. The command `C-x a l' (`add-mode-abbrev') is similar, but defines a mode-specific abbrev. Mode-specific abbrevs are active only in a particular major mode. `C-x a l' defines an abbrev for the major mode in effect at the time `C-x a l' is typed. The arguments work the same as for `C-x a g'. If the abbrev text itself is already in the buffer, you can use the commands `C-x a i g' (`inverse-add-global-abbrev') and `C-x a i l' (`inverse-add-mode-abbrev') to define it as an abbrev by specify the expansion in the minibuffer. These commands are called "inverse" because they invert the meaning of the two text strings they use (one from the buffer and one read with the minibuffer). You can define an abbrev without inserting either the abbrev or its expansion in the buffer using the command `define-global-abbrev'. It reads two arguments--the abbrev, and its expansion. The command `define-mode-abbrev' does likewise for a mode-specific abbrev. To change the definition of an abbrev, just define a new definition. When the abbrev has a prior definition, the abbrev definition commands ask for confirmation before replacing it. To remove an abbrev definition, give a negative argument to the abbrev definition command: `C-u - C-x a g' or `C-u - C-x a l'. The former removes a global definition, while the latter removes a mode-specific definition. `M-x kill-all-abbrevs' removes all abbrev definitions, both global and local.  File: emacs, Node: Expanding Abbrevs, Next: Editing Abbrevs, Prev: Defining Abbrevs, Up: Abbrevs 33.3 Controlling Abbrev Expansion ================================= When Abbrev mode is enabled, an abbrev expands whenever it is present in the buffer just before point and you type a self-inserting whitespace or punctuation character (, comma, etc.). More precisely, any character that is not a word constituent expands an abbrev, and any word-constituent character can be part of an abbrev. The most common way to use an abbrev is to insert it and then insert a punctuation or whitespace character to expand it. Abbrev expansion preserves case; thus, `foo' expands into `find outer otter'; `Foo' into `Find outer otter', and `FOO' into `FIND OUTER OTTER' or `Find Outer Otter' according to the variable `abbrev-all-caps' (setting it non-`nil' specifies `FIND OUTER OTTER'). These commands are used to control abbrev expansion: `M-'' Separate a prefix from a following abbrev to be expanded (`abbrev-prefix-mark'). `C-x a e' Expand the abbrev before point (`expand-abbrev'). This is effective even when Abbrev mode is not enabled. `M-x expand-region-abbrevs' Expand some or all abbrevs found in the region. You may wish to expand an abbrev and attach a prefix to the expansion; for example, if `cnst' expands into `construction', you might want to use it to enter `reconstruction'. It does not work to type `recnst', because that is not necessarily a defined abbrev. What you can do is use the command `M-'' (`abbrev-prefix-mark') in between the prefix `re' and the abbrev `cnst'. First, insert `re'. Then type `M-''; this inserts a hyphen in the buffer to indicate that it has done its work. Then insert the abbrev `cnst'; the buffer now contains `re-cnst'. Now insert a non-word character to expand the abbrev `cnst' into `construction'. This expansion step also deletes the hyphen that indicated `M-'' had been used. The result is the desired `reconstruction'. If you actually want the text of the abbrev in the buffer, rather than its expansion, you can accomplish this by inserting the following punctuation with `C-q'. Thus, `foo C-q ,' leaves `foo,' in the buffer, not expanding it. If you expand an abbrev by mistake, you can undo the expansion and bring back the abbrev itself by typing `C-_' to undo (*note Undo::). This also undoes the insertion of the non-word character that expanded the abbrev. If the result you want is the terminating non-word character plus the unexpanded abbrev, you must reinsert the terminating character, quoting it with `C-q'. You can also use the command `M-x unexpand-abbrev' to cancel the last expansion without deleting the terminating character. `M-x expand-region-abbrevs' searches through the region for defined abbrevs, and for each one found offers to replace it with its expansion. This command is useful if you have typed in text using abbrevs but forgot to turn on Abbrev mode first. It may also be useful together with a special set of abbrev definitions for making several global replacements at once. This command is effective even if Abbrev mode is not enabled. Expanding any abbrev runs `abbrev-expand-functions', a special hook. Functions in this special hook can make arbitrary changes to the abbrev expansion. *Note Abbrev Expansion: (elisp)Abbrev Expansion.  File: emacs, Node: Editing Abbrevs, Next: Saving Abbrevs, Prev: Expanding Abbrevs, Up: Abbrevs 33.4 Examining and Editing Abbrevs ================================== `M-x list-abbrevs' Display a list of all abbrev definitions. With a numeric argument, list only local abbrevs. `M-x edit-abbrevs' Edit a list of abbrevs; you can add, alter or remove definitions. The output from `M-x list-abbrevs' looks like this: VARIOUS OTHER TABLES... (lisp-mode-abbrev-table) "dk" 0 "define-key" (global-abbrev-table) "dfn" 0 "definition" (Some blank lines of no semantic significance, and some other abbrev tables, have been omitted.) A line containing a name in parentheses is the header for abbrevs in a particular abbrev table; `global-abbrev-table' contains all the global abbrevs, and the other abbrev tables that are named after major modes contain the mode-specific abbrevs. Within each abbrev table, each nonblank line defines one abbrev. The word at the beginning of the line is the abbrev. The number that follows is the number of times the abbrev has been expanded. Emacs keeps track of this to help you see which abbrevs you actually use, so that you can eliminate those that you don't use often. The string at the end of the line is the expansion. Some abbrevs are marked with `(sys)'. These "system" abbrevs (*note Abbrevs: (elisp)Abbrevs.) are pre-defined by various modes, and are not saved to your abbrev file. To disable a "system" abbrev, define an abbrev of the same name that expands to itself, and save it to your abbrev file. `M-x edit-abbrevs' allows you to add, change or kill abbrev definitions by editing a list of them in an Emacs buffer. The list has the same format described above. The buffer of abbrevs is called `*Abbrevs*', and is in Edit-Abbrevs mode. Type `C-c C-c' in this buffer to install the abbrev definitions as specified in the buffer--and delete any abbrev definitions not listed. The command `edit-abbrevs' is actually the same as `list-abbrevs' except that it selects the buffer `*Abbrevs*' whereas `list-abbrevs' merely displays it in another window.  File: emacs, Node: Saving Abbrevs, Next: Dynamic Abbrevs, Prev: Editing Abbrevs, Up: Abbrevs 33.5 Saving Abbrevs =================== These commands allow you to keep abbrev definitions between editing sessions. `M-x write-abbrev-file FILE ' Write a file FILE describing all defined abbrevs. `M-x read-abbrev-file FILE ' Read the file FILE and define abbrevs as specified therein. `M-x quietly-read-abbrev-file FILE ' Similar but do not display a message about what is going on. `M-x define-abbrevs' Define abbrevs from definitions in current buffer. `M-x insert-abbrevs' Insert all abbrevs and their expansions into current buffer. `M-x write-abbrev-file' reads a file name using the minibuffer and then writes a description of all current abbrev definitions into that file. This is used to save abbrev definitions for use in a later session. The text stored in the file is a series of Lisp expressions that, when executed, define the same abbrevs that you currently have. `M-x read-abbrev-file' reads a file name using the minibuffer and then reads the file, defining abbrevs according to the contents of the file. The function `quietly-read-abbrev-file' is similar except that it does not display a message in the echo area; you cannot invoke it interactively, and it is used primarily in your init file (*note Init File::). If either of these functions is called with `nil' as the argument, it uses the file given by the variable `abbrev-file-name', which is `~/.emacs.d/abbrev_defs' by default. This is your standard abbrev definition file, and Emacs loads abbrevs from it automatically when it starts up. (As an exception, Emacs does not load the abbrev file when it is started in batch mode. *Note Initial Options::, for a description of batch mode.) Emacs will offer to save abbrevs automatically if you have changed any of them, whenever it offers to save all files (for `C-x s' or `C-x C-c'). It saves them in the file specified by `abbrev-file-name'. This feature can be inhibited by setting the variable `save-abbrevs' to `nil'. The commands `M-x insert-abbrevs' and `M-x define-abbrevs' are similar to the previous commands but work on text in an Emacs buffer. `M-x insert-abbrevs' inserts text into the current buffer after point, describing all current abbrev definitions; `M-x define-abbrevs' parses the entire current buffer and defines abbrevs accordingly.  File: emacs, Node: Dynamic Abbrevs, Next: Dabbrev Customization, Prev: Saving Abbrevs, Up: Abbrevs 33.6 Dynamic Abbrev Expansion ============================= The abbrev facility described above operates automatically as you insert text, but all abbrevs must be defined explicitly. By contrast, "dynamic abbrevs" allow the meanings of abbreviations to be determined automatically from the contents of the buffer, but dynamic abbrev expansion happens only when you request it explicitly. `M-/' Expand the word in the buffer before point as a "dynamic abbrev", by searching in the buffer for words starting with that abbreviation (`dabbrev-expand'). `C-M-/' Complete the word before point as a dynamic abbrev (`dabbrev-completion'). For example, if the buffer contains `does this follow ' and you type `f o M-/', the effect is to insert `follow' because that is the last word in the buffer that starts with `fo'. A numeric argument to `M-/' says to take the second, third, etc. distinct expansion found looking backward from point. Repeating `M-/' searches for an alternative expansion by looking farther back. After scanning all the text before point, it searches the text after point. The variable `dabbrev-limit', if non-`nil', specifies how far away in the buffer to search for an expansion. After scanning the current buffer, `M-/' normally searches other buffers, unless you have set `dabbrev-check-all-buffers' to `nil'. For finer control over which buffers to scan, customize the variable `dabbrev-ignored-buffer-regexps'. Its value is a list of regular expressions. If a buffer's name matches any of these regular expressions, dynamic abbrev expansion skips that buffer. A negative argument to `M-/', as in `C-u - M-/', says to search first for expansions after point, then other buffers, and consider expansions before point only as a last resort. If you repeat the `M-/' to look for another expansion, do not specify an argument. Repeating `M-/' cycles through all the expansions after point and then the expansions before point. After you have expanded a dynamic abbrev, you can copy additional words that follow the expansion in its original context. Simply type ` M-/' for each additional word you want to copy. The spacing and punctuation between words is copied along with the words. The command `C-M-/' (`dabbrev-completion') performs completion of a dynamic abbrev. Instead of trying the possible expansions one by one, it finds all of them, then inserts the text that they have in common. If they have nothing in common, `C-M-/' displays a list of completions, from which you can select a choice in the usual manner. *Note Completion::. Dynamic abbrev expansion is completely independent of Abbrev mode; the expansion of a word with `M-/' is completely independent of whether it has a definition as an ordinary abbrev.  File: emacs, Node: Dabbrev Customization, Prev: Dynamic Abbrevs, Up: Abbrevs 33.7 Customizing Dynamic Abbreviation ===================================== Normally, dynamic abbrev expansion ignores case when searching for expansions. That is, the expansion need not agree in case with the word you are expanding. This feature is controlled by the variable `dabbrev-case-fold-search'. If it is `t', case is ignored in this search; if it is `nil', the word and the expansion must match in case. If the value of `dabbrev-case-fold-search' is `case-fold-search', which is true by default, then the variable `case-fold-search' controls whether to ignore case while searching for expansions. Normally, dynamic abbrev expansion preserves the case pattern _of the dynamic abbrev you are expanding_, by converting the expansion to that case pattern. The variable `dabbrev-case-replace' controls whether to preserve the case pattern of the dynamic abbrev. If it is `t', the dynamic abbrev's case pattern is preserved in most cases; if it is `nil', the expansion is always copied verbatim. If the value of `dabbrev-case-replace' is `case-replace', which is true by default, then the variable `case-replace' controls whether to copy the expansion verbatim. However, if the expansion contains a complex mixed case pattern, and the dynamic abbrev matches this pattern as far as it goes, then the expansion is always copied verbatim, regardless of those variables. Thus, for example, if the buffer contains `variableWithSillyCasePattern', and you type `v a M-/', it copies the expansion verbatim including its case pattern. The variable `dabbrev-abbrev-char-regexp', if non-`nil', controls which characters are considered part of a word, for dynamic expansion purposes. The regular expression must match just one character, never two or more. The same regular expression also determines which characters are part of an expansion. The value `nil' has a special meaning: dynamic abbrevs are made of word characters, but expansions are made of word and symbol characters. In shell scripts and makefiles, a variable name is sometimes prefixed with `$' and sometimes not. Major modes for this kind of text can customize dynamic abbrev expansion to handle optional prefixes by setting the variable `dabbrev-abbrev-skip-leading-regexp'. Its value should be a regular expression that matches the optional prefix that dynamic abbrev expression should ignore.  File: emacs, Node: Picture Mode, Next: Sending Mail, Prev: Abbrevs, Up: Top 34 Editing Pictures ******************* To edit a picture made out of text characters (for example, a picture of the division of a register into fields, as a comment in a program), use the command `M-x picture-mode' to enter Picture mode. In Picture mode, editing is based on the "quarter-plane" model of text, according to which the text characters lie studded on an area that stretches infinitely far to the right and downward. The concept of the end of a line does not exist in this model; the most you can say is where the last nonblank character on the line is found. Of course, Emacs really always considers text as a sequence of characters, and lines really do have ends. But Picture mode replaces the most frequently-used commands with variants that simulate the quarter-plane model of text. They do this by inserting spaces or by converting tabs to spaces. Most of the basic editing commands of Emacs are redefined by Picture mode to do essentially the same thing but in a quarter-plane way. In addition, Picture mode defines various keys starting with the `C-c' prefix to run special picture editing commands. One of these keys, `C-c C-c', is particularly important. Often a picture is part of a larger file that is usually edited in some other major mode. Picture mode records the name of the previous major mode so you can use the `C-c C-c' command (`picture-mode-exit') later to go back to that mode. `C-c C-c' also deletes spaces from the ends of lines, unless given a numeric argument. The special commands of Picture mode all work in other modes (provided the `picture' library is loaded), but are not bound to keys except in Picture mode. The descriptions below talk of moving "one column" and so on, but all the picture mode commands handle numeric arguments as their normal equivalents do. Turning on Picture mode runs the hook `picture-mode-hook'. Additional extensions to Picture mode can be found in `artist.el'. * Menu: * Basic Picture:: Basic concepts and simple commands of Picture Mode. * Insert in Picture:: Controlling direction of cursor motion after "self-inserting" characters. * Tabs in Picture:: Various features for tab stops and indentation. * Rectangles in Picture:: Clearing and superimposing rectangles.  File: emacs, Node: Basic Picture, Next: Insert in Picture, Up: Picture Mode 34.1 Basic Editing in Picture Mode ================================== Most keys do the same thing in Picture mode that they usually do, but do it in a quarter-plane style. For example, `C-f' is rebound to run `picture-forward-column', a command which moves point one column to the right, inserting a space if necessary so that the actual end of the line makes no difference. `C-b' is rebound to run `picture-backward-column', which always moves point left one column, converting a tab to multiple spaces if necessary. `C-n' and `C-p' are rebound to run `picture-move-down' and `picture-move-up', which can either insert spaces or convert tabs as necessary to make sure that point stays in exactly the same column. `C-e' runs `picture-end-of-line', which moves to after the last nonblank character on the line. There is no need to change `C-a', as the choice of screen model does not affect beginnings of lines. Insertion of text is adapted to the quarter-plane screen model through the use of Overwrite mode (*note Minor Modes::.) Self-inserting characters replace existing text, column by column, rather than pushing existing text to the right. runs `picture-newline', which just moves to the beginning of the following line so that new text will replace that line. In Picture mode, the commands that normally delete or kill text, instead erase text (replacing it with spaces). (`picture-backward-clear-column') replaces the preceding character with a space rather than removing it; this moves point backwards. `C-d' (`picture-clear-column') replaces the next character or characters with spaces, but does not move point. (If you want to clear characters to spaces and move forward over them, use .) `C-k' (`picture-clear-line') really kills the contents of lines, but does not delete the newlines from the buffer. To do actual insertion, you must use special commands. `C-o' (`picture-open-line') creates a blank line after the current line; it never splits a line. `C-M-o' (`split-line') makes sense in Picture mode, so it is not changed. `C-j' (`picture-duplicate-line') inserts another line with the same contents below the current line. To do actual deletion in Picture mode, use `C-w', `C-c C-d' (which is defined as `delete-char', as `C-d' is in other modes), or one of the picture rectangle commands (*note Rectangles in Picture::).  File: emacs, Node: Insert in Picture, Next: Tabs in Picture, Prev: Basic Picture, Up: Picture Mode 34.2 Controlling Motion after Insert ==================================== Since "self-inserting" characters in Picture mode overwrite and move point, there is no essential restriction on how point should be moved. Normally point moves right, but you can specify any of the eight orthogonal or diagonal directions for motion after a "self-inserting" character. This is useful for drawing lines in the buffer. `C-c <' `C-c ' Move left after insertion (`picture-movement-left'). `C-c >' `C-c ' Move right after insertion (`picture-movement-right'). `C-c ^' `C-c ' Move up after insertion (`picture-movement-up'). `C-c .' `C-c ' Move down after insertion (`picture-movement-down'). `C-c `' `C-c ' Move up and left ("northwest") after insertion (`picture-movement-nw'). `C-c '' `C-c ' Move up and right ("northeast") after insertion (`picture-movement-ne'). `C-c /' `C-c ' Move down and left ("southwest") after insertion (`picture-movement-sw'). `C-c \' `C-c ' Move down and right ("southeast") after insertion (`picture-movement-se'). Two motion commands move based on the current Picture insertion direction. The command `C-c C-f' (`picture-motion') moves in the same direction as motion after "insertion" currently does, while `C-c C-b' (`picture-motion-reverse') moves in the opposite direction.  File: emacs, Node: Tabs in Picture, Next: Rectangles in Picture, Prev: Insert in Picture, Up: Picture Mode 34.3 Picture Mode Tabs ====================== Two kinds of tab-like action are provided in Picture mode. Use `M-' (`picture-tab-search') for context-based tabbing. With no argument, it moves to a point underneath the next "interesting" character that follows whitespace in the previous nonblank line. "Next" here means "appearing at a horizontal position greater than the one point starts out at." With an argument, as in `C-u M-', this command moves to the next such interesting character in the current line. `M-' does not change the text; it only moves point. "Interesting" characters are defined by the variable `picture-tab-chars', which should define a set of characters. The syntax for this variable is like the syntax used inside of `[...]' in a regular expression--but without the `[' and the `]'. Its default value is `"!-~"'. itself runs `picture-tab', which operates based on the current tab stop settings; it is the Picture mode equivalent of `tab-to-tab-stop'. Normally it just moves point, but with a numeric argument it clears the text that it moves over. The context-based and tab-stop-based forms of tabbing are brought together by the command `C-c ' (`picture-set-tab-stops'). This command sets the tab stops to the positions which `M-' would consider significant in the current line. The use of this command, together with , can get the effect of context-based tabbing. But `M-' is more convenient in the cases where it is sufficient. It may be convenient to prevent use of actual tab characters in pictures. For example, this prevents `C-x ' from messing up the picture. You can do this by setting the variable `indent-tabs-mode' to `nil'.  File: emacs, Node: Rectangles in Picture, Prev: Tabs in Picture, Up: Picture Mode 34.4 Picture Mode Rectangle Commands ==================================== Picture mode defines commands for working on rectangular pieces of the text in ways that fit with the quarter-plane model. The standard rectangle commands may also be useful. *Note Rectangles::. `C-c C-k' Clear out the region-rectangle with spaces (`picture-clear-rectangle'). With argument, delete the text. `C-c C-w R' Similar, but save rectangle contents in register R first (`picture-clear-rectangle-to-register'). `C-c C-y' Copy last killed rectangle into the buffer by overwriting, with upper left corner at point (`picture-yank-rectangle'). With argument, insert instead. `C-c C-x R' Similar, but use the rectangle in register R (`picture-yank-rectangle-from-register'). The picture rectangle commands `C-c C-k' (`picture-clear-rectangle') and `C-c C-w' (`picture-clear-rectangle-to-register') differ from the standard rectangle commands in that they normally clear the rectangle instead of deleting it; this is analogous with the way `C-d' is changed in Picture mode. However, deletion of rectangles can be useful in Picture mode, so these commands delete the rectangle if given a numeric argument. `C-c C-k' either with or without a numeric argument saves the rectangle for `C-c C-y'. The Picture mode commands for yanking rectangles differ from the standard ones in that they overwrite instead of inserting. This is the same way that Picture mode insertion of other text differs from other modes. `C-c C-y' (`picture-yank-rectangle') inserts (by overwriting) the rectangle that was most recently killed, while `C-c C-x' (`picture-yank-rectangle-from-register') does likewise for the rectangle found in a specified register.  File: emacs, Node: Sending Mail, Next: Rmail, Prev: Picture Mode, Up: Top 35 Sending Mail *************** To send an "e-mail" message in Emacs, type `C-x m'. This selects and initializes a buffer named `*mail*', where you can edit the text and headers of the message. Finally, type `C-c C-s' or `C-c C-c' to send the message. `C-x m' Begin composing mail (`compose-mail'). `C-x 4 m' Likewise, in another window (`compose-mail-other-window'). `C-x 5 m' Likewise, but in a new frame (`compose-mail-other-frame'). `C-c C-s' In the mail buffer, send the message (`message-send'). `C-c C-c' In the mail buffer, send the message and bury the buffer (`message-send-and-exit'). The command `C-x 4 m' (`compose-mail-other-window') does the same as `C-x m', except it displays the mail buffer in a different window. The command `C-x 5 m' (`compose-mail-other-frame') creates a new frame for the mail buffer. Because the mail buffer is an ordinary Emacs buffer, you can switch to other buffers while in the middle of composing mail, and switch back later (or never). If you type `C-x m' again when you have been composing another message but have not sent it, Emacs asks for confirmation before erasing the old message. If you answer `n', Emacs selects the mail buffer with its old contents, so you can finish the old message and send it. `C-u C-x m' is another way to do this. Sending the message marks the mail buffer "unmodified," which avoids the need for confirmation when `C-x m' is next used. If you want to send another message before finishing the current message, use the command `M-x rename-uniquely' to rename the current mail buffer (*note Misc Buffer::). Then you can use `C-x m' to make a new mail buffer, and work with each mail buffer independently. Before using Emacs to send mail, you may need to customize the variable `send-mail-function' if your system is not set up to deliver mail directly via SMTP (*note Mail Sending::). In addition, you may need to customize `user-mail-address' if the system cannot receive mail via SMTP (*note Mail Headers::). * Menu: * Format: Mail Format. Format of a mail message. * Headers: Mail Headers. Details of some standard mail header fields. * Aliases: Mail Aliases. Abbreviating and grouping mail addresses. * Commands: Mail Commands. Special commands for editing mail being composed. * Signature: Mail Signature. Adding a signature to every message. * Amuse: Mail Amusements. Distracting the NSA; adding fortune messages. * Methods: Mail Methods. Using alternative mail-composition methods.  File: emacs, Node: Mail Format, Next: Mail Headers, Up: Sending Mail 35.1 The Format of the Mail Buffer ================================== An email message must contain certain pieces of information, called "headers", which specify the message's sender, recipient(s), and so on. At the top of the mail buffer is a set of "header fields", where you can enter this information. You can insert and edit header fields using ordinary editing commands. *Note Header Editing::, for commands specific to editing header fields. Some header fields are automatically pre-initialized in the buffer, when appropriate; other headers, such as `Date' and `Message-Id', are normally omitted from the mail buffer and created automatically when the message is sent. The line in the buffer that says --text follows this line-- separates the header fields from the "body" (or "text") of the message. Everything above this line is treated as part of the headers; everything below it is treated as the body. The delimiter line itself does not appear in the message actually sent. The text used for the delimiter line is controlled by the variable `mail-header-separator'. Here is an example of what the headers and text in the mail buffer might look like. To: gnu@example.org CC: lungfish@example.com, byob@example.net Subject: The Emacs Manual --text follows this line-- Please ignore this message.  File: emacs, Node: Mail Headers, Next: Mail Aliases, Prev: Mail Format, Up: Sending Mail 35.2 Mail Header Fields ======================= A header field in the mail buffer starts with a field name at the beginning of a line, terminated by a colon. Upper and lower case are equivalent in field names (and in mailing addresses also). After the colon and optional whitespace comes the contents of the field. You can use any name you like for a header field, but normally people use only standard field names with accepted meanings. Here is a table of commonly-used fields. Emacs pre-initializes some of these, depending on various options you can set. You can delete or alter any header field before you send the message, if you wish. `From' The address of the sender (you). This should be a valid mailing address, as replies will normally go there. Emacs initializes this field using the variables `user-full-name' and `user-mail-address'; see below. `To' The mailing address(es) to which the message is addressed. To list more than one address, use commas (not spaces) to separate them. `Subject' A piece of text saying what the message is about. Most mail-reading programs can display a summary of messages, listing the subject of each message but not its text. `CC' Additional mailing address(es) to send the message to. This is like `To', except that these readers should not regard the message as directed at them. `BCC' Additional mailing address(es) to send the message to, which should not appear in the header of the message actually sent. "BCC" stands for "blind carbon copies". `FCC' The name of one file, to which a copy of the sent message should be appended. Emacs writes the message in mbox format, unless the file is in Babyl format (used by Rmail before Emacs 23), in which case Emacs writes Babyl. If an Rmail buffer is visiting the file, Emacs updates it accordingly. To specify more than one file, use several `FCC' fields, with one file name in each field. `Reply-to' An address to which replies should be sent, instead of `From'. You can use this header if, for some reason, your `From' address is unable to receive replies. `Mail-reply-to' This field takes precedence over `Reply-to'. It is used because some mailing lists set the `Reply-to' field for their own purposes (a somewhat controversial practice). `Mail-followup-to' This field contains one or more addresses. It is typically used when you reply to a message from a mailing list that you are subscribed to. It usually indicates that you want replies to go to the list, and that you do not need an extra copy sent directly to you. `In-reply-to' A piece of text describing the message you are replying to. Some mail systems can use this information to correlate related pieces of mail. Normally, you never need to think about this, because it is filled in automatically when you reply to a message in Rmail (or any other mail program built into Emacs). `References' The Message-Ids of previous related messages (a Message-Id is a unique identifier generated when a message is sent). Like `In-reply-to', this is normally set up automatically for you. The `To', `CC', and `BCC' fields can appear any number of times, and each such header field can contain multiple addresses, separated by commas. This way, you can specify any number of places to send the message. These fields can also have continuation lines: one or more lines starting with whitespace, following the starting line of the field, are considered part of the field. Here's an example of a `To' field with a continuation line: To: foo@example.net, this@example.net, bob@example.com The default contents of the `From' header field are computed from the variables `user-full-name' and `user-mail-address'. On some operating systems, Emacs initializes these two variables using environment variables (*note General Variables::). If this information is unavailable or wrong, you can customize the variables yourself (*note Easy Customization::). The value of the variable `mail-from-style' specifies how to format the address in the `From' field: `nil' Use just the address, as in `king@grassland.com'. `parens' Use both address and full name, as in: `king@grassland.com (Elvis Parsley)'. `angles' Use both address and full name, as in: `Elvis Parsley '. any other value Use `angles' for most addresses. However, if the address must be "quoted" to remain syntactically-valid under the `angles' format but not under the `parens' format, use `parens' instead. This is the default. You can direct Emacs to insert certain default headers into the mail buffer by setting the variable `mail-default-headers' to a string. Then `C-x m' inserts this string into the message headers. For example, here is how to add a `Reply-to' and `FCC' header to each message: (setq mail-default-headers "Reply-to: foo@example.com\nFCC: ~/Mail/sent") If the default header fields are not appropriate for a particular message, edit them as necessary before sending the message.  File: emacs, Node: Mail Aliases, Next: Mail Commands, Prev: Mail Headers, Up: Sending Mail 35.3 Mail Aliases ================= You can define "mail aliases", which are short mnemonic names that stand for mail addresses or groups of mail addresses. By default, mail aliases are defined in the file `~/.mailrc'. You can specify a different file name to use, by setting the variable `mail-personal-alias-file'. To define an alias in `.mailrc', write a line in the following format: alias NICK FULLADDRESSES This means that NICK should expand into FULLADDRESSES, where FULLADDRESSES can be either a single address, or multiple addresses separated with spaces. For instance, to make `maingnu' stand for `gnu@gnu.org' plus a local address of your own, put in this line: alias maingnu gnu@gnu.org local-gnu If an address contains a space, quote the whole address with a pair of double quotes, like this: alias jsmith "John Q. Smith " Note that you need not include double quotes around individual parts of the address, such as the person's full name. Emacs puts them in if they are needed. For instance, it inserts the above address as `"John Q. Smith" '. Emacs also recognizes "include" commands in `.mailrc'. They look like this: source FILENAME The `.mailrc' file is not unique to Emacs; many other mail-reading programs use it for mail aliases, and it can contain various other commands. However, Emacs ignores everything except alias definitions and include commands. Mail aliases expand as abbrevs--that is to say, as soon as you type a word-separator character after an alias (*note Abbrevs::). This expansion takes place only within the `To', `From', `CC', `BCC', and `Reply-to' header fields (plus their `Resent-' variants); it does not take place in other header fields, such as `Subject'. You can also insert an aliased address directly, using the command `M-x mail-abbrev-insert-alias'. This reads an alias name, with completion, and inserts its definition at point.  File: emacs, Node: Mail Commands, Next: Mail Signature, Prev: Mail Aliases, Up: Sending Mail 35.4 Mail Commands ================== The default major mode for the `*mail*' buffer is called Message mode. It behaves like Text mode in many ways, but provides several additional commands on the `C-c' prefix, which make editing a message more convenient. In this section, we will describe some of the most commonly-used commands available in Message mode. Message mode also has its own manual, where its features are described in greater detail. *Note Message: (message)Top. * Menu: * Mail Sending:: Commands to send the message. * Header Editing:: Commands to move to header fields and edit them. * Citing Mail:: Quoting a message you are replying to. * Mail Misc:: Attachments, spell checking, etc.  File: emacs, Node: Mail Sending, Next: Header Editing, Up: Mail Commands 35.4.1 Mail Sending ------------------- There are two commands to send a message you have been editing: `C-c C-c' Send the message, and deselect the mail buffer (`message-send-and-exit'). `C-c C-s' Send the message, and leave the mail buffer selected (`message-send'). If you want to send a message and be done with it, type `C-c C-c' (`mail-send-and-exit'). This sends the message and then either deletes the window or switches to another buffer. It also "buries" the mail buffer, putting it at the lowest priority for reselection. This is the usual command for sending a message. The command `C-c C-s' (`message-send') sends the message and marks the mail buffer unmodified, but leaves the buffer selected. Use this command if you want to modify the message (perhaps with new recipients) and send it again. Sending a message runs the hook `message-send-hook'. In a file-visiting buffer, sending the message does not clear the modified flag, because only saving the file should do that. Also, you don't get a warning if you try to send the same message twice. When you send a message containing non-ASCII characters, they need to be encoded with a coding system (*note Coding Systems::). Usually the coding system is specified automatically by your chosen language environment (*note Language Environments::). You can explicitly specify the coding system for outgoing mail by setting the variable `sendmail-coding-system' (*note Recognize Coding::). If the coding system thus determined does not handle the characters in a particular message, Emacs asks you to select the coding system to use, showing a list of possible coding systems. The variable `send-mail-function' controls how the default mail user agent sends mail. Its value should be a function, which can be one of the following: `sendmail-send-it' Send mail using the system's default `sendmail' (or `sendmail'-compatible) program. This is the default on Unix and GNU, and works provided the system is a valid "mail host" (that is, provided it can deliver mail via SMTP). `mailclient-send-it' Pass the mail buffer on to the system's designated mail client (see `mailclient.el'). This is the default on Mac OS X and MS-Windows. `smtpmail-send-it' Send mail through an external mail host (e.g., your Internet service provider's SMTP server). You will need to tell Emacs how to contact the SMTP server, by customizing the variables `smtpmail-smtp-server' and `smtpmail-auth-credentials'. *Note Emacs SMTP Library: (smtpmail)Top. `feedmail-send-it' This is similar to `sendmail-send-it', but allows you to queue messages for later sending. See the commentary section in the file `feedmail.el' for more information.  File: emacs, Node: Header Editing, Next: Citing Mail, Prev: Mail Sending, Up: Mail Commands 35.4.2 Mail Header Editing -------------------------- Message mode provides the following special commands to move to particular header fields and to complete addresses in headers. `C-c C-f C-t' Move to the `To' header (`message-goto-to'). `C-c C-f C-s' Move to the `Subject' header (`message-goto-subject'). `C-c C-f C-c' Move to the `CC' header (`message-goto-cc'). `C-c C-f C-b' Move to the `BCC' header (`message-goto-bcc'). `C-c C-f C-r' Move to the `Reply-To' header (`message-goto-reply-to'). `C-c C-f C-f' Move to the `Mail-Followup-To' header field (`message-goto-followup-to'). `C-c C-f C-w' Add a new `FCC' header field, with file-name completion (`message-goto-fcc'). `C-c C-b' Move to the start of the message body (`message-goto-body'). `' Complete a mailing address (`message-tab'). The commands to move point to particular header fields are all based on the prefix `C-c C-f' (`C-f' is for "field"). If the field in question does not exist, the command creates one (the exception is `mail-fcc', which creates a new field each time). The command `C-c C-b' (`message-goto-body') moves point to just after the header separator line--that is, to the beginning of the body. While editing a header field that contains addresses, such as `To:', `CC:' and `BCC:', you can complete an address by typing (`message-tab'). This attempts to insert the full name corresponding to the address based on a couple of methods, including EUDC, a library that recognizes a number of directory server protocols (*note EUDC: (eudc)Top.). Failing that, it attempts to expand the address as a mail alias (*note Mail Aliases::). If point is on a header field that does not take addresses, or if it is in the message body, then just inserts a tab character.  File: emacs, Node: Citing Mail, Next: Mail Misc, Prev: Header Editing, Up: Mail Commands 35.4.3 Citing Mail ------------------ `C-c C-y' Yank the selected message from Rmail (`message-yank-original'). `C-c C-q' Fill each paragraph cited from another message (`message-fill-yanked-message'). You can use the command `C-c C-y' (`message-yank-original') to "cite" a message that you are replying to. This inserts the text of that message into the mail buffer. This command is active only when the mail buffer is invoked from a mail program running in Emacs, such as Rmail. By default, Emacs inserts the string `>' in front of each line of the cited text; this prefix string is specified by the variable `message-yank-prefix'. If you call `message-yank-original' with a prefix argument, the citation prefix is not inserted. After using `C-c C-y', you can type `C-c C-q' (`message-fill-yanked-message') to fill the paragraphs of the cited message. One use of `C-c C-q' fills all such paragraphs, each one individually. To fill a single paragraph of the quoted message, use `M-q'. If filling does not automatically handle the type of citation prefix you use, try setting the fill prefix explicitly. *Note Filling::. You can customize mail citation through the hook `mail-citation-hook'. For example, you can use the Supercite package, which provides more flexible citation (*note Introduction: (sc)Introduction.).  File: emacs, Node: Mail Misc, Prev: Citing Mail, Up: Mail Commands 35.4.4 Mail Miscellany ---------------------- You can "attach" a file to an outgoing message by typing `C-c C-a' (`mml-attach-file') in the mail buffer. Attaching is done using the MIME (Multipurpose Internet Mail Extensions) standard. The `mml-attach-file' command prompts for the name of the file, and for the attachment's "content type", "description", and "disposition". The content type is normally detected automatically; just type to accept the default. The description is a single line of text that the recipient will see next to the attachment; you may also choose to leave this empty. The disposition is either `inline' (the default), which means the recipient will see a link to the attachment within the message body, or `attachment', which means the link will be separate from the body. The actual contents of the attached file are not inserted into the mail buffer. Instead, some placeholder text is inserted into the mail buffer, like this: <#part type="text/plain" filename="~/foo.txt" disposition=inline> <#/part> When you type `C-c C-c' or `C-c C-s' to send the message, the attached file will be delivered with it. While composing a message, you can do spelling correction on the message text by typing `M-x ispell-message'. If you have yanked an incoming message into the outgoing draft, this command skips what was yanked, but it checks the text that you yourself inserted (it looks for indentation or `mail-yank-prefix' to distinguish the cited lines from your input). *Note Spelling::. Turning on Message mode (which `C-x m' does automatically) runs the normal hooks `text-mode-hook' and `message-mode-hook'. Initializing a new outgoing message runs the normal hook `message-setup-hook'; you can use this hook if you want to make changes to the appearance of the mail buffer. *Note Hooks::. The main difference between these hooks is just when they are invoked. Whenever you type `C-x m', `message-mode-hook' runs as soon as the mail buffer is created. Then the `message-setup' function inserts the default contents of the buffer. After these default contents are inserted, `message-setup-hook' runs. If you use `C-x m' to continue an existing composition, `message-mode-hook' runs immediately after switching to the mail buffer. If the buffer is unmodified, or if you decide to erase it and start again, `message-setup-hook' runs after the default contents are inserted.  File: emacs, Node: Mail Signature, Next: Mail Amusements, Prev: Mail Commands, Up: Sending Mail 35.5 Mail Signature =================== You can add a standard piece of text--your "mail signature"--to the end of every message. This signature may contain information such as your telephone number or your physical location. The variable `mail-signature' determines how Emacs handles the mail signature. The default value of `mail-signature' is `t'; this means to look for your mail signature in the file `~/.signature'. If this file exists, its contents are automatically inserted into the end of the mail buffer. You can change the signature file via the variable `mail-signature-file'. If you change `mail-signature' to a string, that specifies the text of the signature directly. If you change `mail-signature' to `nil', Emacs will not insert your mail signature automatically. You can insert your mail signature by typing `C-c C-w' (`message-insert-signature') in the mail buffer. Emacs will look for your signature in the signature file. By convention, a mail signature should be marked by a line whose contents are `-- '. If your signature lacks this prefix, it is added for you. The remainder of your signature should be no more than four lines.  File: emacs, Node: Mail Amusements, Next: Mail Methods, Prev: Mail Signature, Up: Sending Mail 35.6 Mail Amusements ==================== `M-x spook' adds a line of randomly chosen keywords to an outgoing mail message. The keywords are chosen from a list of words that suggest you are discussing something subversive. The idea behind this feature is the suspicion that the NSA(1) and other intelligence agencies snoop on all electronic mail messages that contain keywords suggesting they might find them interesting. (The agencies say that they don't, but that's what they _would_ say.) The idea is that if lots of people add suspicious words to their messages, the agencies will get so busy with spurious input that they will have to give up reading it all. Whether or not this is true, it at least amuses some people. You can use the `fortune' program to put a "fortune cookie" message into outgoing mail. To do this, add `fortune-to-signature' to `mail-setup-hook': (add-hook 'mail-setup-hook 'fortune-to-signature) You will probably need to set the variable `fortune-file' before using this. ---------- Footnotes ---------- (1) The US National Security Agency.  File: emacs, Node: Mail Methods, Prev: Mail Amusements, Up: Sending Mail 35.7 Mail-Composition Methods ============================= In this chapter we have described the usual Emacs mode for editing and sending mail--Message mode. This is only one of several available modes. Prior to Emacs 23.2, the default mode was Mail mode, which is similar to Message mode in many respects but lacks features such as MIME support. Another available mode is MH-E (*note MH-E: (mh-e)Top.). You can choose any of these "mail user agents" as your preferred method for editing and sending mail. The commands `C-x m', `C-x 4 m' and `C-x 5 m' use whichever agent you have specified; so do various other parts of Emacs that send mail, such as the bug reporter (*note Bugs::). To specify a mail user agent, customize the variable `mail-user-agent'. Currently, legitimate values include `message-user-agent' (Message mode) `sendmail-user-agent' (Mail mode), `gnus-user-agent', and `mh-e-user-agent'. If you select a different mail-composition method, the information in this chapter about the mail buffer and Message mode does not apply; the other methods use a different format of text in a different buffer, and their commands are different as well. Similarly, to specify your preferred method for reading mail, customize the variable `read-mail-command'. The default is `rmail' (*note Rmail::).  File: emacs, Node: Rmail, Next: Dired, Prev: Sending Mail, Up: Top 36 Reading Mail with Rmail ************************** Rmail is an Emacs subsystem for reading and disposing of mail that you receive. Rmail stores mail messages in files called Rmail files. Reading the messages in an Rmail file is done in a special major mode, Rmail mode, which redefines most letters to run commands for managing mail. * Menu: * Basic: Rmail Basics. Basic concepts of Rmail, and simple use. * Scroll: Rmail Scrolling. Scrolling through a message. * Motion: Rmail Motion. Moving to another message. * Deletion: Rmail Deletion. Deleting and expunging messages. * Inbox: Rmail Inbox. How mail gets into the Rmail file. * Files: Rmail Files. Using multiple Rmail files. * Output: Rmail Output. Copying messages out to files. * Labels: Rmail Labels. Classifying messages by labeling them. * Attrs: Rmail Attributes. Certain standard labels, called attributes. * Reply: Rmail Reply. Sending replies to messages you are viewing. * Summary: Rmail Summary. Summaries show brief info on many messages. * Sort: Rmail Sorting. Sorting messages in Rmail. * Display: Rmail Display. How Rmail displays a message; customization. * Coding: Rmail Coding. How Rmail handles decoding character sets. * Editing: Rmail Editing. Editing message text and headers in Rmail. * Digest: Rmail Digest. Extracting the messages from a digest message. * Rot13: Rmail Rot13. Reading messages encoded in the rot13 code. * Movemail:: More details of fetching new mail. * Remote Mailboxes:: Retrieving mail from remote mailboxes. * Other Mailbox Formats:: Retrieving mail from local mailboxes in various formats.  File: emacs, Node: Rmail Basics, Next: Rmail Scrolling, Up: Rmail 36.1 Basic Concepts of Rmail ============================ Using Rmail in the simplest fashion, you have one Rmail file `~/RMAIL' in which all of your mail is saved. It is called your "primary Rmail file". The command `M-x rmail' reads your primary Rmail file, merges new mail in from your inboxes, displays the first message you haven't read yet, and lets you begin reading. The variable `rmail-file-name' specifies the name of the primary Rmail file. Rmail displays only one message in the Rmail file at a time. The message that is shown is called the "current message". Rmail mode's special commands can do such things as delete the current message, copy it into another file, send a reply, or move to another message. You can also create multiple Rmail files and use Rmail to move messages between them. Within the Rmail file, messages are normally arranged sequentially in order of receipt; you can specify other ways to sort them (*note Rmail Sorting::). Messages are identified by consecutive integers which are their "message numbers". The number of the current message is displayed in Rmail's mode line, followed by the total number of messages in the file. You can move to a message by specifying its message number with the `j' key (*note Rmail Motion::). Following the usual conventions of Emacs, changes in an Rmail file become permanent only when you save the file. You can save it with `s' (`rmail-expunge-and-save'), which also expunges deleted messages from the file first (*note Rmail Deletion::). To save the file without expunging, use `C-x C-s'. Rmail also saves the Rmail file after merging new mail from an inbox file (*note Rmail Inbox::). You can exit Rmail with `q' (`rmail-quit'); this expunges and saves the Rmail file, then buries the Rmail buffer as well as its summary buffer, if present (*note Rmail Summary::). But there is no need to "exit" formally. If you switch from Rmail to editing in other buffers, and never switch back, you have exited. Just make sure to save the Rmail file eventually (like any other file you have changed). `C-x s' is a suitable way to do this (*note Save Commands::). The Rmail command `b', `rmail-bury', buries the Rmail buffer and its summary buffer without expunging and saving the Rmail file.  File: emacs, Node: Rmail Scrolling, Next: Rmail Motion, Prev: Rmail Basics, Up: Rmail 36.2 Scrolling Within a Message =============================== When Rmail displays a message that does not fit on the screen, you must scroll through it to read the rest. You could do this with `C-v', `M-v' and `M-<', but in Rmail scrolling is so frequent that it deserves to be easier. `' Scroll forward (`scroll-up'). `' Scroll backward (`scroll-down'). `.' Scroll to start of message (`rmail-beginning-of-message'). `/' Scroll to end of message (`rmail-end-of-message'). Since the most common thing to do while reading a message is to scroll through it by screenfuls, Rmail makes and synonyms of `C-v' (`scroll-up') and `M-v' (`scroll-down') The command `.' (`rmail-beginning-of-message') scrolls back to the beginning of the selected message. This is not quite the same as `M-<': for one thing, it does not set the mark; for another, it resets the buffer boundaries of the current message if you have changed them. Similarly, the command `/' (`rmail-end-of-message') scrolls forward to the end of the selected message.  File: emacs, Node: Rmail Motion, Next: Rmail Deletion, Prev: Rmail Scrolling, Up: Rmail 36.3 Moving Among Messages ========================== The most basic thing to do with a message is to read it. The way to do this in Rmail is to make the message current. The usual practice is to move sequentially through the file, since this is the order of receipt of messages. When you enter Rmail, you are positioned at the first message that you have not yet made current (that is, the first one that has the `unseen' attribute; *note Rmail Attributes::). Move forward to see the other new messages; move backward to re-examine old messages. `n' Move to the next nondeleted message, skipping any intervening deleted messages (`rmail-next-undeleted-message'). `p' Move to the previous nondeleted message (`rmail-previous-undeleted-message'). `M-n' Move to the next message, including deleted messages (`rmail-next-message'). `M-p' Move to the previous message, including deleted messages (`rmail-previous-message'). `C-c C-n' Move to the next message with the same subject as the current one (`rmail-next-same-subject'). `C-c C-p' Move to the previous message with the same subject as the current one (`rmail-previous-same-subject'). `j' Move to the first message. With argument N, move to message number N (`rmail-show-message'). `>' Move to the last message (`rmail-last-message'). `<' Move to the first message (`rmail-first-message'). `M-s REGEXP ' Move to the next message containing a match for REGEXP (`rmail-search'). `- M-s REGEXP ' Move to the previous message containing a match for REGEXP. `n' and `p' are the usual way of moving among messages in Rmail. They move through the messages sequentially, but skip over deleted messages, which is usually what you want to do. Their command definitions are named `rmail-next-undeleted-message' and `rmail-previous-undeleted-message'. If you do not want to skip deleted messages--for example, if you want to move to a message to undelete it--use the variants `M-n' and `M-p' (`rmail-next-message' and `rmail-previous-message'). A numeric argument to any of these commands serves as a repeat count. In Rmail, you can specify a numeric argument by typing just the digits. You don't need to type `C-u' first. The `M-s' (`rmail-search') command is Rmail's version of search. The usual incremental search command `C-s' works in Rmail, but it searches only within the current message. The purpose of `M-s' is to search for another message. It reads a regular expression (*note Regexps::) nonincrementally, then searches starting at the beginning of the following message for a match. It then selects that message. If REGEXP is empty, `M-s' reuses the regexp used the previous time. To search backward in the file for another message, give `M-s' a negative argument. In Rmail you can do this with `- M-s'. This begins searching from the end of the previous message. It is also possible to search for a message based on labels. *Note Rmail Labels::. The `C-c C-n' (`rmail-next-same-subject') command moves to the next message with the same subject as the current one. A prefix argument serves as a repeat count. With a negative argument, this command moves backward, acting like `C-c C-p' (`rmail-previous-same-subject'). When comparing subjects, these commands ignore the prefixes typically added to the subjects of replies. To move to a message specified by absolute message number, use `j' (`rmail-show-message') with the message number as argument. With no argument, `j' selects the first message. `<' (`rmail-first-message') also selects the first message. `>' (`rmail-last-message') selects the last message.  File: emacs, Node: Rmail Deletion, Next: Rmail Inbox, Prev: Rmail Motion, Up: Rmail 36.4 Deleting Messages ====================== When you no longer need to keep a message, you can "delete" it. This flags it as ignorable, and some Rmail commands pretend it is no longer present; but it still has its place in the Rmail file, and still has its message number. "Expunging" the Rmail file actually removes the deleted messages. The remaining messages are renumbered consecutively. `d' Delete the current message, and move to the next nondeleted message (`rmail-delete-forward'). `C-d' Delete the current message, and move to the previous nondeleted message (`rmail-delete-backward'). `u' Undelete the current message, or move back to the previous deleted message and undelete it (`rmail-undelete-previous-message'). `x' Expunge the Rmail file (`rmail-expunge'). There are two Rmail commands for deleting messages. Both delete the current message and select another message. `d' (`rmail-delete-forward') moves to the following message, skipping messages already deleted, while `C-d' (`rmail-delete-backward') moves to the previous nondeleted message. If there is no nondeleted message to move to in the specified direction, the message that was just deleted remains current. `d' with a prefix argument is equivalent to `C-d'. Note that the Rmail summary versions of these commands behave slightly differently (*note Rmail Summary Edit::). Whenever Rmail deletes a message, it runs the hook `rmail-delete-message-hook'. When the hook functions are invoked, the message has been marked deleted, but it is still the current message in the Rmail buffer. To make all the deleted messages finally vanish from the Rmail file, type `x' (`rmail-expunge'). Until you do this, you can still "undelete" the deleted messages. The undeletion command, `u' (`rmail-undelete-previous-message'), is designed to cancel the effect of a `d' command in most cases. It undeletes the current message if the current message is deleted. Otherwise it moves backward to previous messages until a deleted message is found, and undeletes that message. You can usually undo a `d' with a `u' because the `u' moves back to and undeletes the message that the `d' deleted. But this does not work when the `d' skips a few already-deleted messages that follow the message being deleted; then the `u' command undeletes the last of the messages that were skipped. There is no clean way to avoid this problem. However, by repeating the `u' command, you can eventually get back to the message that you intend to undelete. You can also select a particular deleted message with the `M-p' command, then type `u' to undelete it. A deleted message has the `deleted' attribute, and as a result `deleted' appears in the mode line when the current message is deleted. In fact, deleting or undeleting a message is nothing more than adding or removing this attribute. *Note Rmail Attributes::.  File: emacs, Node: Rmail Inbox, Next: Rmail Files, Prev: Rmail Deletion, Up: Rmail 36.5 Rmail Files and Inboxes ============================ When you receive mail locally, the operating system places incoming mail for you in a file that we call your "inbox". When you start up Rmail, it runs a C program called `movemail' to copy the new messages from your local inbox into your primary Rmail file, which also contains other messages saved from previous Rmail sessions. It is in this file that you actually read the mail with Rmail. This operation is called "getting new mail". You can get new mail at any time in Rmail by typing `g'. The variable `rmail-primary-inbox-list' contains a list of the files which are inboxes for your primary Rmail file. If you don't set this variable explicitly, Rmail uses the `MAIL' environment variable, or, as a last resort, a default inbox based on `rmail-spool-directory'. The default inbox file depends on your operating system; often it is `/var/mail/USERNAME', `/var/spool/mail/USERNAME', or `/usr/spool/mail/USERNAME'. You can specify the inbox file(s) for any Rmail file for the current session with the command `set-rmail-inbox-list'; see *note Rmail Files::. There are two reasons for having separate Rmail files and inboxes. 1. The inbox file format varies between operating systems and according to the other mail software in use. Only one part of Rmail needs to know about the alternatives, and it need only understand how to convert all of them to Rmail's own format. 2. It is very cumbersome to access an inbox file without danger of losing mail, because it is necessary to interlock with mail delivery. Moreover, different operating systems use different interlocking techniques. The strategy of moving mail out of the inbox once and for all into a separate Rmail file avoids the need for interlocking in all the rest of Rmail, since only Rmail operates on the Rmail file. Rmail was originally written to use the Babyl format as its internal format. Since then, we have recognized that the usual inbox format (`mbox') on Unix and GNU systems is adequate for the job, and so since Emacs 23 Rmail uses that as its internal format. The Rmail file is still separate from the inbox file, even though their format is the same. When getting new mail, Rmail first copies the new mail from the inbox file to the Rmail file; then it saves the Rmail file; then it clears out the inbox file. This way, a system crash may cause duplication of mail between the inbox and the Rmail file, but cannot lose mail. If `rmail-preserve-inbox' is non-`nil', then Rmail does not clear out the inbox file when it gets new mail. You may wish to set this, for example, on a portable computer you use to check your mail via POP while traveling, so that your mail will remain on the server and you can save it later on your workstation. In some cases, Rmail copies the new mail from the inbox file indirectly. First it runs the `movemail' program to move the mail from the inbox to an intermediate file called `.newmail-INBOXNAME', in the same directory as the Rmail file. Then Rmail merges the new mail from that file, saves the Rmail file, and only then deletes the intermediate file. If there is a crash at the wrong time, this file continues to exist, and Rmail will use it again the next time it gets new mail from that inbox. If Rmail is unable to convert the data in `.newmail-INBOXNAME' into mbox format, it renames the file to `RMAILOSE.N' (N is an integer chosen to make the name unique) so that Rmail will not have trouble with the data again. You should look at the file, find whatever message confuses Rmail (probably one that includes the control-underscore character, octal code 037), and delete it. Then you can use `1 g' to get new mail from the corrected file.  File: emacs, Node: Rmail Files, Next: Rmail Output, Prev: Rmail Inbox, Up: Rmail 36.6 Multiple Rmail Files ========================= Rmail operates by default on your "primary Rmail file", which is named `~/RMAIL' and receives your incoming mail from your system inbox file. But you can also have other Rmail files and edit them with Rmail. These files can receive mail through their own inboxes, or you can move messages into them with explicit Rmail commands (*note Rmail Output::). `i FILE ' Read FILE into Emacs and run Rmail on it (`rmail-input'). `M-x set-rmail-inbox-list FILES ' Specify inbox file names for current Rmail file to get mail from. `g' Merge new mail from current Rmail file's inboxes (`rmail-get-new-mail'). `C-u g FILE ' Merge new mail from inbox file FILE. To run Rmail on a file other than your primary Rmail file, you can use the `i' (`rmail-input') command in Rmail. This visits the file in Rmail mode. You can use `M-x rmail-input' even when not in Rmail, but it is easier to type `C-u M-x rmail', which does the same thing. The file you read with `i' should normally be a valid mbox file. If it is not, Rmail tries to convert its text to mbox format, and visits the converted text in the buffer. If you save the buffer, that converts the file. If you specify a file name that doesn't exist, `i' initializes a new buffer for creating a new Rmail file. You can also select an Rmail file from a menu. In the Classify menu, choose the Input Rmail File item; then choose the Rmail file you want. The variables `rmail-secondary-file-directory' and `rmail-secondary-file-regexp' specify which files to offer in the menu: the first variable says which directory to find them in; the second says which files in that directory to offer (all those that match the regular expression). If no files match, you cannot select this menu item. These variables also apply to choosing a file for output (*note Rmail Output::). The inbox files to use are specified by the variable `rmail-inbox-list', which is buffer-local in Rmail mode. As a special exception, if you have specified no inbox files for your primary Rmail file, it uses the `MAIL' environment variable, or your standard system inbox. The `g' command (`rmail-get-new-mail') merges mail into the current Rmail file from its inboxes. If the Rmail file has no inboxes, `g' does nothing. The command `M-x rmail' also merges new mail into your primary Rmail file. To merge mail from a file that is not the usual inbox, give the `g' key a numeric argument, as in `C-u g'. Then it reads a file name and merges mail from that file. The inbox file is not deleted or changed in any way when `g' with an argument is used. This is, therefore, a general way of merging one file of messages into another.  File: emacs, Node: Rmail Output, Next: Rmail Labels, Prev: Rmail Files, Up: Rmail 36.7 Copying Messages Out to Files ================================== These commands copy messages from an Rmail file into another file. `o FILE ' Append a full copy of the current message to the file FILE (`rmail-output'). `C-o FILE ' Append a copy of the current message, as displayed, to the file FILE (`rmail-output-as-seen'). `w FILE ' Output just the message body to the file FILE, taking the default file name from the message `Subject' header. The commands `o' and `C-o' copy the current message into a specified file, adding it at the end. The two commands differ mainly in how much to copy: `o' copies the full message headers, even if they are not all visible, while `C-o' copies exactly the headers currently displayed and no more. *Note Rmail Display::. In addition, `o' converts the message to Babyl format (used by Rmail in Emacs version 22 and before) if the file is in Babyl format; `C-o' cannot output to Babyl files at all. If the output file is currently visited in an Emacs buffer, the output commands append the message to that buffer. It is up to you to save the buffer eventually in its file. Sometimes you may receive a message whose body holds the contents of a file. You can save the body to a file (excluding the message header) with the `w' command (`rmail-output-body-to-file'). Often these messages contain the intended file name in the `Subject' field, so the `w' command uses the `Subject' field as the default for the output file name. However, the file name is read using the minibuffer, so you can specify a different name if you wish. You can also output a message to an Rmail file chosen with a menu. In the Classify menu, choose the Output Rmail File menu item; then choose the Rmail file you want. This outputs the current message to that file, like the `o' command. The variables `rmail-secondary-file-directory' and `rmail-secondary-file-regexp' specify which files to offer in the menu: the first variable says which directory to find them in; the second says which files in that directory to offer (all those that match the regular expression). If no files match, you cannot select this menu item. Copying a message with `o' or `C-o' gives the original copy of the message the `filed' attribute, so that `filed' appears in the mode line when such a message is current. If you like to keep just a single copy of every mail message, set the variable `rmail-delete-after-output' to `t'; then the `o', `C-o' and `w' commands delete the original message after copying it. (You can undelete it afterward if you wish.) The variable `rmail-output-file-alist' lets you specify intelligent defaults for the output file, based on the contents of the current message. The value should be a list whose elements have this form: (REGEXP . NAME-EXP) If there's a match for REGEXP in the current message, then the default file name for output is NAME-EXP. If multiple elements match the message, the first matching element decides the default file name. The subexpression NAME-EXP may be a string constant giving the file name to use, or more generally it may be any Lisp expression that returns a file name as a string. `rmail-output-file-alist' applies to both `o' and `C-o'.  File: emacs, Node: Rmail Labels, Next: Rmail Attributes, Prev: Rmail Output, Up: Rmail 36.8 Labels =========== Each message can have various "labels" assigned to it as a means of classification. Each label has a name; different names are different labels. Any given label is either present or absent on a particular message. A few label names have standard meanings and are given to messages automatically by Rmail when appropriate; these special labels are called "attributes". (*Note Rmail Attributes::.) All other labels are assigned only by users. `a LABEL ' Assign the label LABEL to the current message (`rmail-add-label'). `k LABEL ' Remove the label LABEL from the current message (`rmail-kill-label'). `C-M-n LABELS ' Move to the next message that has one of the labels LABELS (`rmail-next-labeled-message'). `C-M-p LABELS ' Move to the previous message that has one of the labels LABELS (`rmail-previous-labeled-message'). `l LABELS ' `C-M-l LABELS ' Make a summary of all messages containing any of the labels LABELS (`rmail-summary-by-labels'). The `a' (`rmail-add-label') and `k' (`rmail-kill-label') commands allow you to assign or remove any label on the current message. If the LABEL argument is empty, it means to assign or remove the same label most recently assigned or removed. Once you have given messages labels to classify them as you wish, there are three ways to use the labels: in moving, in summaries, and in sorting. The command `C-M-n LABELS ' (`rmail-next-labeled-message') moves to the next message that has one of the labels LABELS. The argument LABELS specifies one or more label names, separated by commas. `C-M-p' (`rmail-previous-labeled-message') is similar, but moves backwards to previous messages. A numeric argument to either command serves as a repeat count. The command `C-M-l LABELS ' (`rmail-summary-by-labels') displays a summary containing only the messages that have at least one of a specified set of labels. The argument LABELS is one or more label names, separated by commas. *Note Rmail Summary::, for information on summaries. If the LABELS argument to `C-M-n', `C-M-p' or `C-M-l' is empty, it means to use the last set of labels specified for any of these commands. *Note Rmail Sorting::, for information on sorting messages with labels.  File: emacs, Node: Rmail Attributes, Next: Rmail Reply, Prev: Rmail Labels, Up: Rmail 36.9 Rmail Attributes ===================== Some labels such as `deleted' and `filed' have built-in meanings, and Rmail assigns them to messages automatically at appropriate times; these labels are called "attributes". Here is a list of Rmail attributes: `unseen' Means the message has never been current. Assigned to messages when they come from an inbox file, and removed when a message is made current. When you start Rmail, it initially shows the first message that has this attribute. `deleted' Means the message is deleted. Assigned by deletion commands and removed by undeletion commands (*note Rmail Deletion::). `filed' Means the message has been copied to some other file. Assigned by the `o' and `C-o' file output commands (*note Rmail Output::). `answered' Means you have mailed an answer to the message. Assigned by the `r' command (`rmail-reply'). *Note Rmail Reply::. `forwarded' Means you have forwarded the message. Assigned by the `f' command (`rmail-forward'). *Note Rmail Reply::. `edited' Means you have edited the text of the message within Rmail. *Note Rmail Editing::. `resent' Means you have resent the message. Assigned by the command `M-x rmail-resend'. *Note Rmail Reply::. `retried' Means you have retried a failed outgoing message. Assigned by the command `M-x rmail-retry-failure'. *Note Rmail Reply::. All other labels are assigned or removed only by users, and have no standard meaning.  File: emacs, Node: Rmail Reply, Next: Rmail Summary, Prev: Rmail Attributes, Up: Rmail 36.10 Sending Replies ===================== Rmail has several commands to send outgoing mail. *Note Sending Mail::, for information on using Message mode, including certain features meant to work with Rmail. What this section documents are the special commands of Rmail for entering the mail buffer. Note that the usual keys for sending mail--`C-x m', `C-x 4 m', and `C-x 5 m'--also work normally in Rmail mode. `m' Send a message (`rmail-mail'). `c' Continue editing the already started outgoing message (`rmail-continue'). `r' Send a reply to the current Rmail message (`rmail-reply'). `f' Forward the current message to other users (`rmail-forward'). `C-u f' Resend the current message to other users (`rmail-resend'). `M-m' Try sending a bounced message a second time (`rmail-retry-failure'). The most common reason to send a message while in Rmail is to reply to the message you are reading. To do this, type `r' (`rmail-reply'). This displays the `*mail*' buffer in another window, much like `C-x 4 m', but preinitializes the `Subject', `To', `CC', `In-reply-to' and `References' header fields based on the message you are replying to. The `To' field starts out as the address of the person who sent the message you received, and the `CC' field starts out with all the other recipients of that message. You can exclude certain recipients from being included automatically in replies, using the variable `rmail-dont-reply-to-names'. Its value should be a regular expression; any recipients that match are excluded from the `CC' field. They are also excluded from the `To' field, unless this would leave the field empty. If this variable is nil, then the first time you compose a reply it is initialized to a default value that matches your own address, and any name starting with `info-'. (Those names are excluded because there is a convention of using them for large mailing lists to broadcast announcements.) To omit the `CC' field completely for a particular reply, enter the reply command with a numeric argument: `C-u r' or `1 r'. This means to reply only to the sender of the original message. Once the `*mail*' buffer has been initialized, editing and sending the mail goes as usual (*note Sending Mail::). You can edit the presupplied header fields if they are not what you want. You can also use commands such as `C-c C-y', which yanks in the message that you are replying to (*note Mail Commands::). You can also switch to the Rmail buffer, select a different message there, switch back, and yank the new current message. Sometimes a message does not reach its destination. Mailers usually send the failed message back to you, enclosed in a "failure message". The Rmail command `M-m' (`rmail-retry-failure') prepares to send the same message a second time: it sets up a `*mail*' buffer with the same text and header fields as before. If you type `C-c C-c' right away, you send the message again exactly the same as the first time. Alternatively, you can edit the text or headers and then send it. The variable `rmail-retry-ignored-headers', in the same format as `rmail-ignored-headers' (*note Rmail Display::), controls which headers are stripped from the failed message when retrying it. Another frequent reason to send mail in Rmail is to "forward" the current message to other users. `f' (`rmail-forward') makes this easy by preinitializing the `*mail*' buffer with the current message as the text, and a subject designating a forwarded message. All you have to do is fill in the recipients and send. When you forward a message, recipients get a message which is "from" you, and which has the original message in its contents. Forwarding a message encloses it between two delimiter lines. It also modifies every line that starts with a dash, by inserting `- ' at the start of the line. When you receive a forwarded message, if it contains something besides ordinary text--for example, program source code--you might find it useful to undo that transformation. You can do this by selecting the forwarded message and typing `M-x unforward-rmail-message'. This command extracts the original forwarded message, deleting the inserted `- ' strings, and inserts it into the Rmail file as a separate message immediately following the current one. "Resending" is an alternative similar to forwarding; the difference is that resending sends a message that is "from" the original sender, just as it reached you--with a few added header fields (`Resent-From' and `Resent-To') to indicate that it came via you. To resend a message in Rmail, use `C-u f'. (`f' runs `rmail-forward', which invokes `rmail-resend' if you provide a numeric argument.) Use the `m' (`rmail-mail') command to start editing an outgoing message that is not a reply. It leaves the header fields empty. Its only difference from `C-x 4 m' is that it makes the Rmail buffer accessible for `C-c C-y', just as `r' does. Thus, `m' can be used to reply to or forward a message; it can do anything `r' or `f' can do. The `c' (`rmail-continue') command resumes editing the `*mail*' buffer, to finish editing an outgoing message you were already composing, or to alter a message you have sent. If you set the variable `rmail-mail-new-frame' to a non-`nil' value, then all the Rmail commands to start sending a message create a new frame to edit it in. This frame is deleted when you send the message, or when you use the `Cancel' item in the `Mail' menu. All the Rmail commands to send a message use the mail-composition method that you have chosen (*note Mail Methods::).  File: emacs, Node: Rmail Summary, Next: Rmail Sorting, Prev: Rmail Reply, Up: Rmail 36.11 Summaries =============== A "summary" is a buffer containing one line per message to give you an overview of the mail in an Rmail file. Each line shows the message number and date, the sender, the line count, the labels, and the subject. Moving point in the summary buffer selects messages as you move to their summary lines. Almost all Rmail commands are valid in the summary buffer also; when used there, they apply to the message described by the current line of the summary. A summary buffer applies to a single Rmail file only; if you are editing multiple Rmail files, each one can have its own summary buffer. The summary buffer name is made by appending `-summary' to the Rmail buffer's name. Normally only one summary buffer is displayed at a time. * Menu: * Rmail Make Summary:: Making various sorts of summaries. * Rmail Summary Edit:: Manipulating messages from the summary.  File: emacs, Node: Rmail Make Summary, Next: Rmail Summary Edit, Up: Rmail Summary 36.11.1 Making Summaries ------------------------ Here are the commands to create a summary for the current Rmail buffer. Once the Rmail buffer has a summary, changes in the Rmail buffer (such as deleting or expunging messages, and getting new mail) automatically update the summary. `h' `C-M-h' Summarize all messages (`rmail-summary'). `l LABELS ' `C-M-l LABELS ' Summarize messages that have one or more of the specified labels (`rmail-summary-by-labels'). `C-M-r RCPTS ' Summarize messages that match the specified recipients (`rmail-summary-by-recipients'). `C-M-t TOPIC ' Summarize messages that have a match for the specified regexp TOPIC in their subjects (`rmail-summary-by-topic'). `C-M-s REGEXP ' Summarize messages whose headers match the specified regular expression REGEXP (`rmail-summary-by-regexp'). `C-M-f SENDERS ' Summarize messages that match the specified senders. (`rmail-summary-by-senders'). The `h' or `C-M-h' (`rmail-summary') command fills the summary buffer for the current Rmail buffer with a summary of all the messages in the buffer. It then displays and selects the summary buffer in another window. `C-M-l LABELS ' (`rmail-summary-by-labels') makes a partial summary mentioning only the messages that have one or more of the labels LABELS. LABELS should contain label names separated by commas. `C-M-r RCPTS ' (`rmail-summary-by-recipients') makes a partial summary mentioning only the messages that have one or more recipients matching the regular expression RCPTS. You can use commas to separate multiple regular expressions. These are matched against the `To', `From', and `CC' headers (with a prefix argument, this header is not included). `C-M-t TOPIC ' (`rmail-summary-by-topic') makes a partial summary mentioning only the messages whose subjects have a match for the regular expression TOPIC. You can use commas to separate multiple regular expressions. With a prefix argument, the match is against the whole message, not just the subject. `C-M-s REGEXP ' (`rmail-summary-by-regexp') makes a partial summary that mentions only the messages whose headers (including the date and the subject lines) match the regular expression REGEXP. `C-M-f SENDERS ' (`rmail-summary-by-senders') makes a partial summary that mentions only the messages whose `From' fields match the regular expression SENDERS. You can use commas to separate multiple regular expressions. Note that there is only one summary buffer for any Rmail buffer; making any kind of summary discards any previous summary. The variable `rmail-summary-window-size' says how many lines to use for the summary window. The variable `rmail-summary-line-count-flag' controls whether the summary line for a message should include the line count of the message. Setting this option to nil might speed up the generation of summaries.  File: emacs, Node: Rmail Summary Edit, Prev: Rmail Make Summary, Up: Rmail Summary 36.11.2 Editing in Summaries ---------------------------- You can use the Rmail summary buffer to do almost anything you can do in the Rmail buffer itself. In fact, once you have a summary buffer, there's no need to switch back to the Rmail buffer. You can select and display various messages in the Rmail buffer, from the summary buffer, just by moving point in the summary buffer to different lines. It doesn't matter what Emacs command you use to move point; whichever line point is on at the end of the command, that message is selected in the Rmail buffer. Almost all Rmail commands work in the summary buffer as well as in the Rmail buffer. Thus, `d' in the summary buffer deletes the current message, `u' undeletes, and `x' expunges. (However, in the summary buffer, a numeric argument to `d', `C-d' and `u' serves as a repeat count. A negative argument reverses the meaning of `d' and `C-d'. Also, if there are no more undeleted messages in the relevant direction, the delete commands go to the first or last message, rather than staying on the current message.) `o' and `C-o' output the current message to a FILE; `r' starts a reply to it; etc. You can scroll the current message while remaining in the summary buffer using and . `M-u' (`rmail-summary-undelete-many') undeletes all deleted messages in the summary. A prefix argument means to undelete that many of the previous deleted messages. The Rmail commands to move between messages also work in the summary buffer, but with a twist: they move through the set of messages included in the summary. They also ensure the Rmail buffer appears on the screen (unlike cursor motion commands, which update the contents of the Rmail buffer but don't display it in a window unless it already appears). Here is a list of these commands: `n' Move to next line, skipping lines saying `deleted', and select its message (`rmail-summary-next-msg'). `p' Move to previous line, skipping lines saying `deleted', and select its message (`rmail-summary-previous-msg'). `M-n' Move to next line and select its message (`rmail-summary-next-all'). `M-p' Move to previous line and select its message (`rmail-summary-previous-all'). `>' Move to the last line, and select its message (`rmail-summary-last-message'). `<' Move to the first line, and select its message (`rmail-summary-first-message'). `j' `' Select the message on the current line (ensuring that the Rmail buffer appears on the screen; `rmail-summary-goto-msg'). With argument N, select message number N and move to its line in the summary buffer; this signals an error if the message is not listed in the summary buffer. `M-s PATTERN ' Search through messages for PATTERN starting with the current message; select the message found, and move point in the summary buffer to that message's line (`rmail-summary-search'). A prefix argument acts as a repeat count; a negative argument means search backward (equivalent to `rmail-summary-search-backward'.) `C-M-n LABELS ' Move to the next message with at least one of the specified labels (`rmail-summary-next-labeled-message'). LABELS is a comma-separated list of labels. A prefix argument acts as a repeat count. `C-M-p LABELS ' Move to the previous message with at least one of the specified labels (`rmail-summary-previous-labeled-message'). `C-c C-n ' Move to the next message with the same subject as the current message (`rmail-summary-next-same-subject'). A prefix argument acts as a repeat count. `C-c C-p ' Move to the previous message with the same subject as the current message (`rmail-summary-previous-same-subject'). Deletion, undeletion, and getting new mail, and even selection of a different message all update the summary buffer when you do them in the Rmail buffer. If the variable `rmail-redisplay-summary' is non-`nil', these actions also bring the summary buffer back onto the screen. When you are finished using the summary, type `Q' (`rmail-summary-wipe') to delete the summary buffer's window. You can also exit Rmail while in the summary: `q' (`rmail-summary-quit') deletes the summary window, then exits from Rmail by saving the Rmail file and switching to another buffer. Alternatively, `b' (`rmail-summary-bury') simply buries the Rmail summary and buffer.  File: emacs, Node: Rmail Sorting, Next: Rmail Display, Prev: Rmail Summary, Up: Rmail 36.12 Sorting the Rmail File ============================ `C-c C-s C-d' `M-x rmail-sort-by-date' Sort messages of current Rmail buffer by date. `C-c C-s C-s' `M-x rmail-sort-by-subject' Sort messages of current Rmail buffer by subject. `C-c C-s C-a' `M-x rmail-sort-by-author' Sort messages of current Rmail buffer by author's name. `C-c C-s C-r' `M-x rmail-sort-by-recipient' Sort messages of current Rmail buffer by recipient's names. `C-c C-s C-c' `M-x rmail-sort-by-correspondent' Sort messages of current Rmail buffer by the name of the other correspondent. `C-c C-s C-l' `M-x rmail-sort-by-lines' Sort messages of current Rmail buffer by number of lines. `C-c C-s C-k LABELS ' `M-x rmail-sort-by-labels LABELS ' Sort messages of current Rmail buffer by labels. The argument LABELS should be a comma-separated list of labels. The order of these labels specifies the order of messages; messages with the first label come first, messages with the second label come second, and so on. Messages that have none of these labels come last. The Rmail sort commands perform a _stable sort_: if there is no reason to prefer either one of two messages, their order remains unchanged. You can use this to sort by more than one criterion. For example, if you use `rmail-sort-by-date' and then `rmail-sort-by-author', messages from the same author appear in order by date. With a prefix argument, all these commands reverse the order of comparison. This means they sort messages from newest to oldest, from biggest to smallest, or in reverse alphabetical order. The same keys in the summary buffer run similar functions; for example, `C-c C-s C-l' runs `rmail-summary-sort-by-lines'. Note that these commands always sort the whole Rmail buffer, even if the summary is only showing a subset of messages. Note that you cannot undo a sort, so you may wish to save the Rmail buffer before sorting it.  File: emacs, Node: Rmail Display, Next: Rmail Coding, Prev: Rmail Sorting, Up: Rmail 36.13 Display of Messages ========================= Rmail reformats the header of each message before displaying it for the first time. Reformatting hides uninteresting header fields to reduce clutter. You can use the `t' command to show the entire header or to repeat the header reformatting operation. `t' Toggle display of complete header (`rmail-toggle-header'). Reformatting the header involves deleting most header fields, on the grounds that they are not interesting. The variable `rmail-ignored-headers' holds a regular expression that specifies which header fields to hide in this way--if it matches the beginning of a header field, that whole field is hidden. However, the variable `rmail-nonignored-headers' provides a further override: a header matching that regular expression is shown even if it matches `rmail-ignored-headers' too. As an alternative to the previous two variables, you can set `rmail-displayed-headers' instead. If non-`nil', this should be a regular expression specifying which headers to display. To see the complete, original header, use the `t' command (`rmail-toggle-header'). This discards the reformatted headers of the current message and displays it with the original header. Repeating `t' reformats the message again, which shows only the interesting headers according to the current values of the above variables. Selecting the message again also reformats it if necessary. When the `t' command has a prefix argument, a positive argument means to show the reformatted header, and a zero or negative argument means to show the full header. Rmail highlights certain header fields that are especially interesting--by default, the `From' and `Subject' fields. The variable `rmail-highlighted-headers' holds a regular expression that specifies the header fields to highlight; if it matches the beginning of a header field, that whole field is highlighted. To turn off this feature, set `rmail-highlighted-headers' to `nil'. Customize the face `rmail-highlight' to adjust the style of the highlighting. You can highlight and activate URLs in incoming messages using Goto Address mode: (add-hook 'rmail-show-message-hook (lambda () (goto-address-mode 1))) Then you can browse these URLs by clicking on them with `Mouse-2' (or `Mouse-1' quickly) or by moving to one and typing `C-c '. *Note Activating URLs: Goto Address mode. The `v' (`rmail-mime') command creates a temporary buffer displaying the current MIME message. By default, it displays plain text and multipart messages, and offers buttons to save attachments.  File: emacs, Node: Rmail Coding, Next: Rmail Editing, Prev: Rmail Display, Up: Rmail 36.14 Rmail and Coding Systems ============================== Rmail automatically decodes messages which contain non-ASCII characters, just as Emacs does with files you visit and with subprocess output. Rmail uses the standard `charset=CHARSET' header in the message, if any, to determine how the message was encoded by the sender. It maps CHARSET into the corresponding Emacs coding system (*note Coding Systems::), and uses that coding system to decode message text. If the message header doesn't have the `charset' specification, or if CHARSET is not recognized, Rmail chooses the coding system with the usual Emacs heuristics and defaults (*note Recognize Coding::). Occasionally, a message is decoded incorrectly, either because Emacs guessed the wrong coding system in the absence of the `charset' specification, or because the specification was inaccurate. For example, a misconfigured mailer could send a message with a `charset=iso-8859-1' header when the message is actually encoded in `koi8-r'. When you see the message text garbled, or some of its characters displayed as empty boxes, this may have happened. You can correct the problem by decoding the message again using the right coding system, if you can figure out or guess which one is right. To do this, invoke the `M-x rmail-redecode-body' command. It reads the name of a coding system, and then redecodes the message using the coding system you specified. If you specified the right coding system, the result should be readable.  File: emacs, Node: Rmail Editing, Next: Rmail Digest, Prev: Rmail Coding, Up: Rmail 36.15 Editing Within a Message ============================== Most of the usual Emacs keybindings are available in Rmail mode, though a few, such as `C-M-n' and `C-M-h', are redefined by Rmail for other purposes. However, the Rmail buffer is normally read only, and most of the letters are redefined as Rmail commands. If you want to edit the text of a message, you must use the Rmail command `e'. `e' Edit the current message as ordinary text. The `e' command (`rmail-edit-current-message') switches from Rmail mode into Rmail Edit mode, another major mode which is nearly the same as Text mode. The mode line indicates this change. In Rmail Edit mode, letters insert themselves as usual and the Rmail commands are not available. You can edit the message body and header fields. When you are finished editing the message, type `C-c C-c' to switch back to Rmail mode. Alternatively, you can return to Rmail mode but cancel any editing that you have done, by typing `C-c C-]'. Entering Rmail Edit mode runs the hook `text-mode-hook'; then it runs the hook `rmail-edit-mode-hook' (*note Hooks::). Returning to ordinary Rmail mode adds the attribute `edited' to the message, if you have made any changes in it.  File: emacs, Node: Rmail Digest, Next: Rmail Rot13, Prev: Rmail Editing, Up: Rmail 36.16 Digest Messages ===================== A "digest message" is a message which exists to contain and carry several other messages. Digests are used on some moderated mailing lists; all the messages that arrive for the list during a period of time such as one day are put inside a single digest which is then sent to the subscribers. Transmitting the single digest uses much less computer time than transmitting the individual messages even though the total size is the same, because the per-message overhead in network mail transmission is considerable. When you receive a digest message, the most convenient way to read it is to "undigestify" it: to turn it back into many individual messages. Then you can read and delete the individual messages as it suits you. To do this, select the digest message and type the command `M-x undigestify-rmail-message'. This extracts the submessages as separate Rmail messages, and inserts them following the digest. The digest message itself is flagged as deleted.  File: emacs, Node: Rmail Rot13, Next: Movemail, Prev: Rmail Digest, Up: Rmail 36.17 Reading Rot13 Messages ============================ Mailing list messages that might offend some readers are sometimes encoded in a simple code called "rot13"--so named because it rotates the alphabet by 13 letters. This code is not for secrecy, as it provides none; rather, it enables those who might be offended to avoid seeing the real text of the message. To view a buffer which uses the rot13 code, use the command `M-x rot13-other-window'. This displays the current buffer in another window which applies the code when displaying the text.  File: emacs, Node: Movemail, Next: Remote Mailboxes, Prev: Rmail Rot13, Up: Rmail 36.18 `movemail' program ======================== Rmail uses the `movemail' program to move mail from your inbox to your Rmail file (*note Rmail Inbox::). When loaded for the first time, Rmail attempts to locate the `movemail' program and determine its version. There are two versions of the `movemail' program: the native one, shipped with GNU Emacs (the "emacs version") and the one included in GNU mailutils (the "mailutils version," *note movemail: (mailutils)movemail.). They support the same command line syntax and the same basic subset of options. However, the Mailutils version offers additional features. The Emacs version of `movemail' is able to retrieve mail from the usual UNIX mailbox formats and from remote mailboxes using the POP3 protocol. The Mailutils version is able to handle a wide set of mailbox formats, such as plain UNIX mailboxes, `maildir' and `MH' mailboxes, etc. It is able to access remote mailboxes using the POP3 or IMAP4 protocol, and can retrieve mail from them using a TLS encrypted channel. It also accepts mailbox arguments in URL form. The detailed description of mailbox URLs can be found in *note URL: (mailutils)URL. In short, a URL is: PROTO://[USER[:PASSWORD]@]HOST-OR-FILE-NAME where square brackets denote optional elements. PROTO Specifies the "mailbox protocol", or "format" to use. The exact semantics of the rest of URL elements depends on the actual value of PROTO (see below). USER User name to access the remote mailbox. PASSWORD User password to access the remote mailbox. HOST-OR-FILE-NAME Hostname of the remote server for remote mailboxes or file name of a local mailbox. PROTO can be one of: `mbox' Usual UNIX mailbox format. In this case, neither USER nor PASS are used, and HOST-OR-FILE-NAME denotes the file name of the mailbox file, e.g., `mbox://var/spool/mail/smith'. `mh' A local mailbox in the MH format. USER and PASS are not used. HOST-OR-FILE-NAME denotes the name of MH folder, e.g., `mh://Mail/inbox'. `maildir' A local mailbox in the maildir format. USER and PASS are not used, and HOST-OR-FILE-NAME denotes the name of `maildir' mailbox, e.g., `maildir://mail/inbox'. `file' Any local mailbox format. Its actual format is detected automatically by `movemail'. `pop' A remote mailbox to be accessed via POP3 protocol. USER specifies the remote user name to use, PASS may be used to specify the user password, HOST-OR-FILE-NAME is the name or IP address of the remote mail server to connect to; e.g., `pop://smith:guessme@remote.server.net'. `imap' A remote mailbox to be accessed via IMAP4 protocol. USER specifies the remote user name to use, PASS may be used to specify the user password, HOST-OR-FILE-NAME is the name or IP address of the remote mail server to connect to; e.g., `imap://smith:guessme@remote.server.net'. Alternatively, you can specify the file name of the mailbox to use. This is equivalent to specifying the `file' protocol: /var/spool/mail/USER == file://var/spool/mail/USER The variable `rmail-movemail-program' controls which version of `movemail' to use. If that is a string, it specifies the absolute file name of the `movemail' executable. If it is `nil', Rmail searches for `movemail' in the directories listed in `rmail-movemail-search-path' and `exec-path', then in `exec-directory'.  File: emacs, Node: Remote Mailboxes, Next: Other Mailbox Formats, Prev: Movemail, Up: Rmail 36.19 Retrieving Mail from Remote Mailboxes =========================================== Some sites use a method called POP for accessing users' inbox data instead of storing the data in inbox files. By default, the `Emacs movemail' can work with POP (unless the Emacs `configure' script was run with the option `--without-pop'). Similarly, the Mailutils `movemail' by default supports POP, unless it was configured with the `--disable-pop' option. Both versions of `movemail' only work with POP3, not with older versions of POP. No matter which flavor of `movemail' you use, you can specify a POP inbox by using a POP "URL" (*note Movemail::). A POP URL is a "file name" of the form `pop://USERNAME@HOSTNAME', where HOSTNAME is the host name or IP address of the remote mail server and USERNAME is the user name on that server. Additionally, you may specify the password in the mailbox URL: `pop://USERNAME:PASSWORD@HOSTNAME'. In this case, PASSWORD takes preference over the one set by `rmail-remote-password' (see below). This is especially useful if you have several remote mailboxes with different passwords. For backward compatibility, Rmail also supports an alternative way of specifying remote POP mailboxes. Specifying an inbox name in the form `po:USERNAME:HOSTNAME' is equivalent to `pop://USERNAME@HOSTNAME'. If you omit the :HOSTNAME part, the `MAILHOST' environment variable specifies the machine on which to look for the POP server. Another method for accessing remote mailboxes is IMAP. This method is supported only by the Mailutils `movemail'. To specify an IMAP mailbox in the inbox list, use the following mailbox URL: `imap://USERNAME[:PASSWORD]@HOSTNAME'. The PASSWORD part is optional, as described above. Accessing a remote mailbox may require a password. Rmail uses the following algorithm to retrieve it: 1. If a PASSWORD is present in the mailbox URL (see above), it is used. 2. If the variable `rmail-remote-password-required' is `nil', Rmail assumes no password is required. 3. If the variable `rmail-remote-password' is non-`nil', its value is used. 4. Otherwise, Rmail will ask you for the password to use. If you need to pass additional command-line flags to `movemail', set the variable `rmail-movemail-flags' a list of the flags you wish to use. Do not use this variable to pass the `-p' flag to preserve your inbox contents; use `rmail-preserve-inbox' instead. The `movemail' program installed at your site may support Kerberos authentication (the Emacs `movemail' does so if Emacs was configured with the option `--with-kerberos' or `--with-kerberos5'). If it is supported, it is used by default whenever you attempt to retrieve POP mail when `rmail-remote-password' and `rmail-remote-password-required' are unset. Some POP servers store messages in reverse order. If your server does this, and you would rather read your mail in the order in which it was received, you can tell `movemail' to reverse the order of downloaded messages by adding the `-r' flag to `rmail-movemail-flags'. Mailutils `movemail' supports TLS encryption. If you wish to use it, add the `--tls' flag to `rmail-movemail-flags'.  File: emacs, Node: Other Mailbox Formats, Prev: Remote Mailboxes, Up: Rmail 36.20 Retrieving Mail from Local Mailboxes in Various Formats ============================================================= If your incoming mail is stored on a local machine in a format other than UNIX mailbox, you will need the Mailutils `movemail' to retrieve it. *Note Movemail::, for the detailed description of `movemail' versions. For example, to access mail from a inbox in `maildir' format located in `/var/spool/mail/in', you would include the following in the Rmail inbox list: maildir://var/spool/mail/in  File: emacs, Node: Dired, Next: Calendar/Diary, Prev: Rmail, Up: Top 37 Dired, the Directory Editor ****************************** Dired makes an Emacs buffer containing a listing of a directory, and optionally some of its subdirectories as well. You can use the normal Emacs commands to move around in this buffer, and special Dired commands to operate on the listed files. The Dired buffer is "read-only," and inserting text in it is not allowed. Ordinary printing characters such as `d' and `x' are redefined for special Dired commands. Some Dired commands "mark" or "flag" the "current file" (that is, the file on the current line); other commands operate on the marked files or on the flagged files. You first mark certain files in order to operate on all of them with one command. The Dired-X package provides various extra features for Dired mode. *Note Dired-X: (dired-x)Top. You can also view a list of files in a directory with `C-x C-d' (`list-directory'). Unlike Dired, this command does not allow you to operate on the listed files. *Note Directories::. * Menu: * Enter: Dired Enter. How to invoke Dired. * Navigation: Dired Navigation. Special motion commands in the Dired buffer. * Deletion: Dired Deletion. Deleting files with Dired. * Flagging Many Files:: Flagging files based on their names. * Visit: Dired Visiting. Other file operations through Dired. * Marks vs Flags:: Flagging for deletion vs marking. * Operating on Files:: How to copy, rename, print, compress, etc. either one file or several files. * Shell Commands in Dired:: Running a shell command on the marked files. * Transforming File Names:: Using patterns to rename multiple files. * Comparison in Dired:: Running `diff' by way of Dired. * Subdirectories in Dired:: Adding subdirectories to the Dired buffer. * Subdir Switches:: Subdirectory switches in Dired. * Subdirectory Motion:: Moving across subdirectories, and up and down. * Hiding Subdirectories:: Making subdirectories visible or invisible. * Updating: Dired Updating. Discarding lines for files of no interest. * Find: Dired and Find. Using `find' to choose the files for Dired. * Wdired:: Operating on files by editing the Dired buffer. * Image-Dired:: Viewing image thumbnails in Dired. * Misc: Misc Dired Features. Various other features.  File: emacs, Node: Dired Enter, Next: Dired Navigation, Up: Dired 37.1 Entering Dired =================== To invoke Dired, type `C-x d' (`dired'). This reads a directory name using the minibuffer, and opens a "Dired buffer" listing the files in that directory. You can also supply a wildcard file name pattern as the minibuffer argument, in which case the Dired buffer lists all files matching that pattern. The usual history and completion commands can be used in the minibuffer; in particular, `M-n' puts the name of the visited file (if any) in the minibuffer (*note Minibuffer History::). You can also invoke Dired by giving `C-x C-f' (`find-file') a directory name. The variable `dired-listing-switches' specifies the options to give to `ls' for listing the directory; this string _must_ contain `-l'. If you use a numeric prefix argument with the `dired' command, you can specify the `ls' switches with the minibuffer before you enter the directory specification. No matter how they are specified, the `ls' switches can include short options (that is, single characters) requiring no arguments, and long options (starting with `--') whose arguments are specified with `='. On MS-Windows and MS-DOS systems, Emacs _emulates_ `ls'; see *note ls in Lisp::, for options and peculiarities of that emulation. To display the Dired buffer in another window rather than in the selected window, use `C-x 4 d' (`dired-other-window') instead of `C-x d'. `C-x 5 d' (`dired-other-frame') uses a separate frame to display the Dired buffer.  File: emacs, Node: Dired Navigation, Next: Dired Deletion, Prev: Dired Enter, Up: Dired 37.2 Navigation in the Dired Buffer =================================== All the usual Emacs cursor motion commands are available in Dired buffers. The keys `C-n' and `C-p' are redefined to put the cursor at the beginning of the file name on the line, rather than at the beginning of the line. For extra convenience, and `n' in Dired are equivalent to `C-n'. `p' is equivalent to `C-p'. (Moving by lines is so common in Dired that it deserves to be easy to type.) (move up and unflag) is also often useful simply for moving up (*note Dired Deletion::). `j' (`dired-goto-file') prompts for a file name using the minibuffer, and moves point to the line in the Dired buffer describing that file. `M-s f C-s' (`dired-isearch-filenames') performs a forward incremental search in the Dired buffer, looking for matches only amongst the file names and ignoring the rest of the text in the buffer. `M-s f M-C-s' (`dired-isearch-filenames-regexp') does the same, using a regular expression search. If you change the variable `dired-isearch-filenames' to `t', then the usual search commands also limit themselves to the file names; for instance, `C-s' behaves like `M-s f C-s'. If the value is `dwim', then search commands match the file names only when point was on a file name initially. *Note Search::, for information about incremental search. Some additional navigation commands are available when the Dired buffer includes several directories. *Note Subdirectory Motion::.  File: emacs, Node: Dired Deletion, Next: Flagging Many Files, Prev: Dired Navigation, Up: Dired 37.3 Deleting Files with Dired ============================== One of the most frequent uses of Dired is to first "flag" files for deletion, then delete the files that were flagged. `d' Flag this file for deletion. `u' Remove deletion flag on this line. `' Move point to previous line and remove the deletion flag on that line. `x' Delete the files that are flagged for deletion. You can flag a file for deletion by moving to the line describing the file and typing `d' (`dired-flag-file-deletion'). The deletion flag is visible as a `D' at the beginning of the line. This command moves point to the next line, so that repeated `d' commands flag successive files. A numeric argument serves as a repeat count. The reason for flagging files for deletion, rather than deleting files immediately, is to reduce the danger of deleting a file accidentally. Until you direct Dired to delete the flagged files, you can remove deletion flags using the commands `u' and . `u' (`dired-unmark') works just like `d', but removes flags rather than making flags. (`dired-unmark-backward') moves upward, removing flags; it is like `u' with argument -1. To delete the flagged files, type `x' (`dired-do-flagged-delete'). This command first displays a list of all the file names flagged for deletion, and requests confirmation with `yes'. If you confirm, Dired deletes the flagged files, then deletes their lines from the text of the Dired buffer. The Dired buffer, with somewhat fewer lines, remains selected. If you answer `no' or quit with `C-g' when asked to confirm, you return immediately to Dired, with the deletion flags still present in the buffer, and no files actually deleted. You can delete empty directories just like other files, but normally Dired cannot delete directories that are nonempty. If the variable `dired-recursive-deletes' is non-`nil', then Dired can delete nonempty directories including all their contents. That can be somewhat risky. On some systems, there is a facility called the "Trash" or "Recycle Bin", but Emacs does _not_ use it by default. Thus, when you delete a file in Dired, it is gone forever. However, you can tell Emacs to use the Trash for file deletion, by changing the variable `delete-by-moving-to-trash' to `t'. *Note Misc File Ops::, for more information about the Trash.  File: emacs, Node: Flagging Many Files, Next: Dired Visiting, Prev: Dired Deletion, Up: Dired 37.4 Flagging Many Files at Once ================================ The `#', `~', `.', `% &', and `% d' commands flag many files for deletion, based on their file names: `#' Flag all auto-save files (files whose names start and end with `#') for deletion (*note Auto Save::). `~' Flag all backup files (files whose names end with `~') for deletion (*note Backup::). `. (Period)' Flag excess numeric backup files for deletion. The oldest and newest few backup files of any one file are exempt; the middle ones are flagged. `% &' Flag for deletion all files with certain kinds of names which suggest you could easily create those files again. `% d REGEXP ' Flag for deletion all files whose names match the regular expression REGEXP. `#' (`dired-flag-auto-save-files') flags all files whose names look like auto-save files--that is, files whose names begin and end with `#'. *Note Auto Save::. `~' (`dired-flag-backup-files') flags all files whose names say they are backup files--that is, files whose names end in `~'. *Note Backup::. `.' (period, `dired-clean-directory') flags just some of the backup files for deletion: all but the oldest few and newest few backups of any one file. Normally, the number of newest versions kept for each file is given by the variable `dired-kept-versions' (*not* `kept-new-versions'; that applies only when saving). The number of oldest versions to keep is given by the variable `kept-old-versions'. Period with a positive numeric argument, as in `C-u 3 .', specifies the number of newest versions to keep, overriding `dired-kept-versions'. A negative numeric argument overrides `kept-old-versions', using minus the value of the argument to specify the number of oldest versions of each file to keep. `% &' (`dired-flag-garbage-files') flags files whose names match the regular expression specified by the variable `dired-garbage-files-regexp'. By default, this matches certain files produced by TeX, `.bak' files, and the `.orig' and `.rej' files produced by `patch'. `% d' flags all files whose names match a specified regular expression (`dired-flag-files-regexp'). Only the non-directory part of the file name is used in matching. You can use `^' and `$' to anchor matches. You can exclude certain subdirectories from marking by hiding them while you use `% d'. *Note Hiding Subdirectories::.  File: emacs, Node: Dired Visiting, Next: Marks vs Flags, Prev: Flagging Many Files, Up: Dired 37.5 Visiting Files in Dired ============================ There are several Dired commands for visiting or examining the files listed in the Dired buffer. All of them apply to the current line's file; if that file is really a directory, these commands invoke Dired on that subdirectory (making a separate Dired buffer). `f' Visit the file described on the current line, like typing `C-x C-f' and supplying that file name (`dired-find-file'). *Note Visiting::. `' `e' Equivalent to `f'. `o' Like `f', but uses another window to display the file's buffer (`dired-find-file-other-window'). The Dired buffer remains visible in the first window. This is like using `C-x 4 C-f' to visit the file. *Note Windows::. `C-o' Visit the file described on the current line, and display the buffer in another window, but do not select that window (`dired-display-file'). `Mouse-1' `Mouse-2' Visit the file named by the line you click on (`dired-mouse-find-file-other-window'). This uses another window to display the file, like the `o' command. `v' View the file described on the current line, using `M-x view-file' (`dired-view-file'). Viewing a file with `view-file' is like visiting it, but is slanted toward moving around in the file conveniently and does not allow changing the file. *Note View File: Misc File Ops. `^' Visit the parent directory of the current directory (`dired-up-directory'). This is equivalent to moving to the line for `..' and typing `f' there.  File: emacs, Node: Marks vs Flags, Next: Operating on Files, Prev: Dired Visiting, Up: Dired 37.6 Dired Marks vs. Flags ========================== Instead of flagging a file with `D', you can "mark" the file with some other character (usually `*'). Most Dired commands to operate on files use the files marked with `*'. The only command that operates on flagged files is `x', which deletes them. Here are some commands for marking with `*', for unmarking, and for operating on marks. (*Note Dired Deletion::, for commands to flag and unflag files.) `m' `* m' Mark the current file with `*' (`dired-mark'). With a numeric argument N, mark the next N files starting with the current file. (If N is negative, mark the previous -N files.) `* *' Mark all executable files with `*' (`dired-mark-executables'). With a numeric argument, unmark all those files. `* @' Mark all symbolic links with `*' (`dired-mark-symlinks'). With a numeric argument, unmark all those files. `* /' Mark with `*' all files which are directories, except for `.' and `..' (`dired-mark-directories'). With a numeric argument, unmark all those files. `* s' Mark all the files in the current subdirectory, aside from `.' and `..' (`dired-mark-subdir-files'). `u' `* u' Remove any mark on this line (`dired-unmark'). `' `* ' Move point to previous line and remove any mark on that line (`dired-unmark-backward'). `* !' `U' Remove all marks from all the files in this Dired buffer (`dired-unmark-all-marks'). `* ? MARKCHAR' `M-' Remove all marks that use the character MARKCHAR (`dired-unmark-all-files'). The argument is a single character--do not use to terminate it. See the description of the `* c' command below, which lets you replace one mark character with another. With a numeric argument, this command queries about each marked file, asking whether to remove its mark. You can answer `y' meaning yes, `n' meaning no, or `!' to remove the marks from the remaining files without asking about them. `* C-n' `M-}' Move down to the next marked file (`dired-next-marked-file') A file is "marked" if it has any kind of mark. `* C-p' `M-{' Move up to the previous marked file (`dired-prev-marked-file') `t' `* t' Toggle all marks (`dired-toggle-marks'): files marked with `*' become unmarked, and unmarked files are marked with `*'. Files marked in any other way are not affected. `* c OLD-MARKCHAR NEW-MARKCHAR' Replace all marks that use the character OLD-MARKCHAR with marks that use the character NEW-MARKCHAR (`dired-change-marks'). This command is the primary way to create or use marks other than `*' or `D'. The arguments are single characters--do not use to terminate them. You can use almost any character as a mark character by means of this command, to distinguish various classes of files. If OLD-MARKCHAR is a space (` '), then the command operates on all unmarked files; if NEW-MARKCHAR is a space, then the command unmarks the files it acts on. To illustrate the power of this command, here is how to put `D' flags on all the files that have no marks, while unflagging all those that already have `D' flags: * c D t * c SPC D * c t SPC This assumes that no files were already marked with `t'. `% m REGEXP ' `* % REGEXP ' Mark (with `*') all files whose names match the regular expression REGEXP (`dired-mark-files-regexp'). This command is like `% d', except that it marks files with `*' instead of flagging with `D'. Only the non-directory part of the file name is used in matching. Use `^' and `$' to anchor matches. You can exclude subdirectories by temporarily hiding them (*note Hiding Subdirectories::). `% g REGEXP ' Mark (with `*') all files whose _contents_ contain a match for the regular expression REGEXP (`dired-mark-files-containing-regexp'). This command is like `% m', except that it searches the file contents instead of the file name. `C-x u' `C-_' `C-/' Undo changes in the Dired buffer, such as adding or removing marks (`dired-undo'). _This command does not revert the actual file operations, nor recover lost files!_ It just undoes changes in the buffer itself. In some cases, using this after commands that operate on files can cause trouble. For example, after renaming one or more files, `dired-undo' restores the original names in the Dired buffer, which gets the Dired buffer out of sync with the actual contents of the directory.  File: emacs, Node: Operating on Files, Next: Shell Commands in Dired, Prev: Marks vs Flags, Up: Dired 37.7 Operating on Files ======================= This section describes the basic Dired commands to operate on one file or several files. All of these commands are capital letters; all of them use the minibuffer, either to read an argument or to ask for confirmation, before they act. All of them let you specify the files to manipulate in these ways: * If you give the command a numeric prefix argument N, it operates on the next N files, starting with the current file. (If N is negative, the command operates on the -N files preceding the current line.) * Otherwise, if some files are marked with `*', the command operates on all those files. * Otherwise, the command operates on the current file only. Certain other Dired commands, such as `!' and the `%' commands, use the same conventions to decide which files to work on. Commands which ask for a destination directory, such as those which copy and rename files or create links for them, try to guess the default target directory for the operation. Normally, they suggest the Dired buffer's default directory, but if the variable `dired-dwim-target' is non-`nil', and if there is another Dired buffer displayed in the next window, that other buffer's directory is suggested instead. Here are the file-manipulating Dired commands that operate on files. `C NEW ' Copy the specified files (`dired-do-copy'). The argument NEW is the directory to copy into, or (if copying a single file) the new name. This is like the shell command `cp'. If `dired-copy-preserve-time' is non-`nil', then copying with this command preserves the modification time of the old file in the copy, like `cp -p'. The variable `dired-recursive-copies' controls whether to copy directories recursively (like `cp -r'). The default is `nil', which means that directories cannot be copied. `D' Delete the specified files (`dired-do-delete'). This is like the shell command `rm'. Like the other commands in this section, this command operates on the _marked_ files, or the next N files. By contrast, `x' (`dired-do-flagged-delete') deletes all "flagged" files. `R NEW ' Rename the specified files (`dired-do-rename'). If you rename a single file, the argument NEW is the new name of the file. If you rename several files, the argument NEW is the directory into which to move the files (this is like the shell command `mv'). Dired automatically changes the visited file name of buffers associated with renamed files so that they refer to the new names. `H NEW ' Make hard links to the specified files (`dired-do-hardlink'). This is like the shell command `ln'. The argument NEW is the directory to make the links in, or (if making just one link) the name to give the link. `S NEW ' Make symbolic links to the specified files (`dired-do-symlink'). This is like `ln -s'. The argument NEW is the directory to make the links in, or (if making just one link) the name to give the link. `M MODESPEC ' Change the mode (also called "permission bits") of the specified files (`dired-do-chmod'). This uses the `chmod' program, so MODESPEC can be any argument that `chmod' can handle. `G NEWGROUP ' Change the group of the specified files to NEWGROUP (`dired-do-chgrp'). `O NEWOWNER ' Change the owner of the specified files to NEWOWNER (`dired-do-chown'). (On most systems, only the superuser can do this.) The variable `dired-chown-program' specifies the name of the program to use to do the work (different systems put `chown' in different places). `T TIMESTAMP ' Touch the specified files (`dired-do-touch'). This means updating their modification times to the present time. This is like the shell command `touch'. `P COMMAND ' Print the specified files (`dired-do-print'). You must specify the command to print them with, but the minibuffer starts out with a suitable guess made using the variables `lpr-command' and `lpr-switches' (the same variables that `lpr-buffer' uses; *note Printing::). `Z' Compress the specified files (`dired-do-compress'). If the file appears to be a compressed file already, uncompress it instead. `L' Load the specified Emacs Lisp files (`dired-do-load'). *Note Lisp Libraries::. `B' Byte compile the specified Emacs Lisp files (`dired-do-byte-compile'). *Note Byte Compilation: (elisp)Byte Compilation. `A REGEXP ' Search all the specified files for the regular expression REGEXP (`dired-do-search'). This command is a variant of `tags-search'. The search stops at the first match it finds; use `M-,' to resume the search and find the next match. *Note Tags Search::. `Q REGEXP TO ' Perform `query-replace-regexp' on each of the specified files, replacing matches for REGEXP with the string TO (`dired-do-query-replace-regexp'). This command is a variant of `tags-query-replace'. If you exit the query replace loop, you can use `M-,' to resume the scan and replace more matches. *Note Tags Search::.  File: emacs, Node: Shell Commands in Dired, Next: Transforming File Names, Prev: Operating on Files, Up: Dired 37.8 Shell Commands in Dired ============================ The Dired command `!' (`dired-do-shell-command') reads a shell command string in the minibuffer and runs that shell command on one or more files. The files that the shell command operates on are determined in the usual way for Dired commands (*note Operating on Files::). The command `X' is a synonym for `!'. The command `&' (`dired-do-async-shell-command') does the same, except that it runs the shell command asynchronously. You can also do this with `!', by appending a `&' character to the end of the shell command. For both `!' and `&', the working directory for the shell command is the top-level directory of the Dired buffer. If you tell `!' or `&' to operate on more than one file, the shell command string determines how those files are passed to the shell command: * If you use `*' surrounded by whitespace in the command string, then the command runs just once, with the list of file names substituted for the `*'. The order of file names is the order of appearance in the Dired buffer. Thus, `! tar cf foo.tar * ' runs `tar' on the entire list of file names, putting them into one tar file `foo.tar'. If you want to use `*' as a shell wildcard with whitespace around it, write `*""'. In the shell, this is equivalent to `*'; but since the `*' is not surrounded by whitespace, Dired does not treat it specially. * Otherwise, if the command string contains `?' surrounded by whitespace, Emacs runs the shell command once _for each file_, substituting the current file name for `?' each time. You can use `?' more than once in the command; the same file name replaces each occurrence. * If the command string contains neither `*' nor `?', Emacs runs the shell command once for each file, adding the file name is added at the end. For example, `! uudecode ' runs `uudecode' on each file. To iterate over the file names in a more complicated fashion, use an explicit shell loop. For example, here is how to uuencode each file, making the output file name by appending `.uu' to the input file name: for file in * ; do uuencode "$file" "$file" >"$file".uu; done The `!' and `&' commands do not attempt to update the Dired buffer to show new or modified files, because they don't know what files will be changed. Use the `g' command to update the Dired buffer (*note Dired Updating::). *Note Single Shell::, for information about running shell commands outside Dired.  File: emacs, Node: Transforming File Names, Next: Comparison in Dired, Prev: Shell Commands in Dired, Up: Dired 37.9 Transforming File Names in Dired ===================================== This section describes Dired commands which alter file names in a systematic way. Each command operates on some or all of the marked files, using a new name made by transforming the existing name. Like the basic Dired file-manipulation commands (*note Operating on Files::), the commands described here operate either on the next N files, or on all files marked with `*', or on the current file. (To mark files, use the commands described in *note Marks vs Flags::.) All of the commands described in this section work _interactively_: they ask you to confirm the operation for each candidate file. Thus, you can select more files than you actually need to operate on (e.g., with a regexp that matches many files), and then filter the selected names by typing `y' or `n' when the command prompts for confirmation. `% u' Rename each of the selected files to an upper-case name (`dired-upcase'). If the old file names are `Foo' and `bar', the new names are `FOO' and `BAR'. `% l' Rename each of the selected files to a lower-case name (`dired-downcase'). If the old file names are `Foo' and `bar', the new names are `foo' and `bar'. `% R FROM TO ' `% C FROM TO ' `% H FROM TO ' `% S FROM TO ' These four commands rename, copy, make hard links and make soft links, in each case computing the new name by regular-expression substitution from the name of the old file. The four regular-expression substitution commands effectively perform a search-and-replace on the selected file names. They read two arguments: a regular expression FROM, and a substitution pattern TO; they match each "old" file name against FROM, and then replace the matching part with TO. You can use `\&' and `\DIGIT' in TO to refer to all or part of what the pattern matched in the old file name, as in `replace-regexp' (*note Regexp Replace::). If the regular expression matches more than once in a file name, only the first match is replaced. For example, `% R ^.*$ x-\& ' renames each selected file by prepending `x-' to its name. The inverse of this, removing `x-' from the front of each file name, is also possible: one method is `% R ^x-\(.*\)$ \1 '; another is `% R ^x- '. (Use `^' and `$' to anchor matches that should span the whole file name.) Normally, the replacement process does not consider the files' directory names; it operates on the file name within the directory. If you specify a numeric argument of zero, then replacement affects the entire absolute file name including directory name. (A non-zero argument specifies the number of files to operate on.) You may want to select the set of files to operate on using the same regexp FROM that you will use to operate on them. To do this, mark those files with `% m FROM ', then use the same regular expression in the command to operate on the files. To make this more convenient, the `%' commands to operate on files use the last regular expression specified in any `%' command as a default.  File: emacs, Node: Comparison in Dired, Next: Subdirectories in Dired, Prev: Transforming File Names, Up: Dired 37.10 File Comparison with Dired ================================ Here are two Dired commands that compare specified files using `diff'. They show the output in a buffer using Diff mode (*note Comparing Files::). `=' Compare the current file (the file at point) with another file (the file at the mark) using the `diff' program (`dired-diff'). The file at the mark is the first argument of `diff', and the file at point is the second argument. This refers to the ordinary Emacs mark, not Dired marks; use `C-' (`set-mark-command') to set the mark at the first file's line (*note Setting Mark::). `M-=' Compare the current file with its latest backup file (`dired-backup-diff'). If the current file is itself a backup, compare it with the file it is a backup of; this way, you can compare a file with any one of its backups. The backup file is the first file given to `diff'.