This is ../info/emacs, produced by makeinfo version 4.3 from emacs.texi. This is the Fourteenth edition of the `GNU Emacs Manual', updated for Emacs version 21.3. INFO-DIR-SECTION Emacs START-INFO-DIR-ENTRY * Emacs: (emacs). The extensible self-documenting text editor. END-INFO-DIR-ENTRY Published by the Free Software Foundation 59 Temple Place, Suite 330 Boston, MA 02111-1307 USA Copyright (C) 1985,1986,1987,1993,1994,1995,1996,1997,1998,1999,2000,2001,2002 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.1 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 freedom to copy and modify this GNU Manual, like GNU software. Copies published by the Free Software Foundation raise funds for GNU development."  File: emacs, Node: Auto Save Control, Next: Recover, Prev: Auto Save Files, Up: Auto Save Controlling Auto-Saving ----------------------- Each time you visit a file, auto-saving is turned on for that file's buffer if the variable `auto-save-default' is non-`nil' (but not in batch mode; *note Entering Emacs::). The default for this variable is `t', so auto-saving is the usual practice for file-visiting buffers. Auto-saving can be turned on or off for any existing buffer with the command `M-x auto-save-mode'. Like other minor mode commands, `M-x auto-save-mode' turns auto-saving on with a positive argument, off with a zero or negative argument; with no argument, it toggles. Emacs does auto-saving periodically based on counting how many characters you have typed since the last time auto-saving was done. The variable `auto-save-interval' specifies how many characters there are between auto-saves. By default, it is 300. Auto-saving also takes place when you stop typing for a while. The variable `auto-save-timeout' says how many seconds Emacs should wait before it does an auto save (and perhaps also a garbage collection). (The actual time period is longer if the current buffer is long; this is a heuristic which aims to keep out of your way when you are editing long buffers, in which auto-save takes an appreciable amount of time.) Auto-saving during idle periods accomplishes two things: first, it makes sure all your work is saved if you go away from the terminal for a while; second, it may avoid some auto-saving while you are actually typing. Emacs also does auto-saving whenever it gets a fatal error. This includes killing the Emacs job with a shell command such as `kill %emacs', or disconnecting a phone line or network connection. You can request an auto-save explicitly with the command `M-x do-auto-save'.  File: emacs, Node: Recover, Prev: Auto Save Control, Up: Auto Save Recovering Data from Auto-Saves ------------------------------- You can use the contents of an auto-save file to recover from a loss of data with the command `M-x recover-file FILE '. This visits FILE and then (after your confirmation) restores the contents from its auto-save file `#FILE#'. You can then save with `C-x C-s' to put the recovered text into FILE itself. For example, to recover file `foo.c' from its auto-save file `#foo.c#', do: M-x recover-file foo.c yes C-x C-s Before asking for confirmation, `M-x recover-file' displays a directory listing describing the specified file and the auto-save file, so you can compare their sizes and dates. If the auto-save file is older, `M-x recover-file' does not offer to read it. If Emacs or the computer crashes, you can recover all the files you were editing from their auto save files with the command `M-x recover-session'. This first shows you a list of recorded interrupted sessions. Move point to the one you choose, and type `C-c C-c'. Then `recover-session' asks about each of the files that were being edited during that session, asking whether to recover that file. If you answer `y', it calls `recover-file', which works in its normal fashion. It shows the dates of the original file and its auto-save file, and asks once again whether to recover that file. When `recover-session' is done, the files you've chosen to recover are present in Emacs buffers. You should then save them. Only this--saving them--updates the files themselves. Emacs records interrupted sessions for later recovery in files named `~/.emacs.d/auto-save-list/.saves-PID-HOSTNAME'. The `~/.emacs.d/auto-save-list/.saves-' portion of these names comes from the value of `auto-save-list-file-prefix'. You can record sessions in a different place by customizing that variable. If you set `auto-save-list-file-prefix' to `nil' in your `.emacs' file, sessions are not recorded for recovery.  File: emacs, Node: File Aliases, Next: Version Control, Prev: Auto Save, Up: Files File Name Aliases ================= Symbolic links and hard links both make it possible for several file names to refer to the same file. Hard links are alternate names that refer directly to the file; all the names are equally valid, and no one of them is preferred. By contrast, a symbolic link is a kind of defined alias: when `foo' is a symbolic link to `bar', you can use either name to refer to the file, but `bar' is the real name, while `foo' is just an alias. More complex cases occur when symbolic links point to directories. If you visit two names for the same file, normally Emacs makes two different buffers, but it warns you about the situation. Normally, if you visit a file which Emacs is already visiting under a different name, Emacs displays a message in the echo area and uses the existing buffer visiting that file. This can happen on systems that support symbolic links, or if you use a long file name on a system that truncates long file names. You can suppress the message by setting the variable `find-file-suppress-same-file-warnings' to a non-`nil' value. You can disable this feature entirely by setting the variable `find-file-existing-other-name' to `nil': then if you visit the same file under two different names, you get a separate buffer for each file name. If the variable `find-file-visit-truename' is non-`nil', then the file name recorded for a buffer is the file's "truename" (made by replacing all symbolic links with their target names), rather than the name you specify. Setting `find-file-visit-truename' also implies the effect of `find-file-existing-other-name'.  File: emacs, Node: Version Control, Next: Directories, Prev: File Aliases, Up: Files Version Control =============== "Version control systems" are packages that can record multiple versions of a source file, usually storing the unchanged parts of the file just once. Version control systems also record history 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 three version control systems--RCS, CVS, and SCCS. The GNU project recommends RCS and CVS, which are free software and available from the Free Software Foundation. We also have free software to replace SCCS, known as CSSC; if you are using SCCS and don't want to make the incompatible change to RCS or CVS, you can switch to CSSC. * 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 Versions:: Examining and comparing old versions. * Secondary VC Commands:: The commands used a little less frequently. * Branches:: Multiple lines of development. * Remote Repositories:: Efficient access to remote CVS servers. * Snapshots:: Sets of file versions treated as a unit. * 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 Introduction to Version Control ------------------------------- VC allows you to use a version control system from within Emacs, integrating the version control operations smoothly with editing. VC provides a uniform interface to version control, so that regardless of which version control system is in use, you can use it 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: * Version Systems:: Supported version control back-end systems. * VC Concepts:: Words and concepts related to version control.  File: emacs, Node: Version Systems, Next: VC Concepts, Up: Introduction to VC Supported Version Control Systems ................................. VC currently works with three different version control systems or "back ends": RCS, CVS, and SCCS. RCS is a free version control system that is available from the Free Software Foundation. It is perhaps the most mature of the supported back ends, and the VC commands are conceptually closest to RCS. Almost everything you can do with RCS can be done through VC. CVS is built on top of RCS, and extends the features of RCS, allowing for more sophisticated release management, and concurrent multi-user development. VC supports basic editing operations under CVS, but 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. SCCS is a proprietary but widely used version control system. In terms of capabilities, it is the weakest of the three that VC supports. VC compensates for certain features missing in SCCS (snapshots, for example) by implementing them itself, but some other VC features, such as multiple branches, are not available with SCCS. You should use SCCS only if for some reason you cannot use RCS.  File: emacs, Node: VC Concepts, Prev: Version Systems, Up: Introduction to VC Concepts of Version Control ........................... When a file is under version control, we also say that it is "registered" in the version control system. Each registered file has a corresponding "master file" which represents the file's present state plus its change history--enough to reconstruct the current version or any earlier version. Usually the master file also records a "log entry" for each version, describing in words what was changed in that version. The file that is maintained under version control is sometimes called the "work file" corresponding to its master file. You edit the work file and make changes in it, as you would with an ordinary file. (With SCCS and RCS, you must "lock" the file before you start to edit it.) After you are done with a set of changes, you "check the file in", which records the changes in the master file, along with a log entry for them. With CVS, there are usually multiple work files corresponding to a single master file--often each user has his own copy. It is also possible to use RCS in this way, but this is not the usual way to use RCS. A version control system typically has some mechanism to coordinate between users who want to change the same file. One method is "locking" (analogous to the locking that Emacs uses to detect simultaneous editing of a file, but distinct from it). The other method is to merge your changes with other people's changes when you check them in. With version control locking, work files are normally read-only so that you cannot change them. You ask the version control system to make a work file writable for you by locking it; only one user can do this at any given time. When you check in your changes, that unlocks the file, making the work file read-only again. This allows other users to lock the file to make further changes. SCCS always uses locking, and RCS normally does. The other alternative for RCS is to let each user modify the work file at any time. In this mode, locking is not required, but it is permitted; check-in is still the way to record a new version. CVS normally allows each user to modify his own copy of the work file at any time, but requires merging with changes from other users at check-in time. However, CVS can also be set up to require locking. (*note CVS Options::).  File: emacs, Node: VC Mode Line, Next: Basic VC Editing, Prev: Introduction to VC, Up: Version Control 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 version number 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'.  File: emacs, Node: Basic VC Editing, Next: Old Versions, Prev: VC Mode Line, Up: Version Control Basic Editing under Version Control ----------------------------------- The principal VC command is an all-purpose command that performs either locking or check-in, depending on the situation. `C-x C-q' `C-x v v' Perform the next logical version control operation on this file. Strictly speaking, the command for this job is `vc-next-action', bound to `C-x v v'. However, the normal meaning of `C-x C-q' is to make a read-only buffer writable, or vice versa; we have extended it to do the same job properly for files managed by version control, by performing the appropriate version control operations. When you type `C-x C-q' on a registered file, it acts like `C-x v v'. The precise action of this command depends on the state of the file, and whether the version control system uses locking or not. SCCS and RCS normally use locking; CVS normally does not use locking. * Menu: * VC with Locking:: RCS in its default mode, SCCS, and optionally CVS. * Without Locking:: Without locking: default mode for CVS. * Advanced C-x C-q:: Advanced features available with a prefix argument. * Log Buffer:: Features available in log entry buffers.  File: emacs, Node: VC with Locking, Next: Without Locking, Up: Basic VC Editing Basic Version Control with Locking .................................. If locking is used for the file (as with SCCS, and RCS in its default mode), `C-x C-q' can either lock a file or check it in: * If the file is not locked, `C-x C-q' locks it, and makes it writable so that you can change it. * If the file is locked by you, and contains changes, `C-x C-q' checks in the changes. In order to do this, it first reads the log entry for the new version. *Note Log Buffer::. * If the file is locked by you, but you have not changed it since you locked it, `C-x C-q' releases the lock and makes the file read-only again. * If the file is locked by some other user, `C-x C-q' asks you 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: Without Locking, Next: Advanced C-x C-q, Prev: VC with Locking, Up: Basic VC Editing Basic Version Control without Locking ..................................... When there is no locking--the default for CVS--work files are always writable; you do not need to do anything before you begin to edit 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 in the work file. Here is what `C-x C-q' does when using CVS: * If some other user has checked in changes into the master file, Emacs asks you whether you want to merge those changes into your own work file. You must do this before you can check in your own changes. (To pick up any recent changes from the master file _without_ trying to commit your own changes, type `C-x v m '.) *Note Merging::. * If there are no new changes in the master file, but you have made modifications in your work file, `C-x C-q' checks in your changes. In order to do this, it first reads the log entry for the new version. *Note Log Buffer::. * If the file is not modified, the `C-x C-q' does nothing. These rules also apply when you use RCS in the mode that does not require locking, except that automatic merging of changes from the master file is not implemented. Unfortunately, this means that nothing informs you if another user has checked in changes in the same file since you began editing it, and when this happens, his changes will be effectively removed when you check in your version (though they will remain in the master file, so they will not be entirely lost). You must therefore verify the current version is unchanged, before you check in your changes. We hope to eliminate this risk and provide automatic merging with RCS in a future Emacs version. In addition, locking is possible with RCS even in this mode, although it is not required; `C-x C-q' with an unmodified file locks the file, just as it does with RCS in its normal (locking) mode.  File: emacs, Node: Advanced C-x C-q, Next: Log Buffer, Prev: Without Locking, Up: Basic VC Editing Advanced Control in `C-x C-q' ............................. When you give a prefix argument to `vc-next-action' (`C-u C-x C-q'), 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 version number 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 version to select; this lets you start working from an older version, or on another branch. If you do not enter any version, that takes you to the highest version on the current branch; therefore `C-u C-x C-q ' is a convenient way to get the latest version of a file from the repository. * Instead of the version number, 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 C-q, Up: Basic VC Editing Features of the Log Entry Buffer ................................ When you check in changes, `C-x C-q' first reads a log entry. It pops up a buffer called `*VC-Log*' for you to enter the log entry. When you are finished, type `C-c C-c' in the `*VC-Log*' buffer. That is when check-in really happens. To abort 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. To do this, use the history of previous log entries. 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 file, the log entry buffer is put into VC Log mode, which involves running two hooks: `text-mode-hook' and `vc-log-mode-hook'. *Note Hooks::.  File: emacs, Node: Old Versions, Next: Secondary VC Commands, Prev: Basic VC Editing, Up: Version Control Examining And Comparing Old Versions ------------------------------------ One of the convenient features of version control is the ability to examine any version of a file, or compare two versions. `C-x v ~ VERSION ' Examine version VERSION of the visited file, in a buffer of its own. `C-x v =' Compare the current buffer contents with the latest checked-in version of the file. `C-u C-x v = FILE OLDVERS NEWVERS ' Compare the specified two versions of FILE. `C-x v g' Display the result of the CVS annotate command using colors. To examine an old version in its entirety, visit the file and then type `C-x v ~ VERSION ' (`vc-version-other-window'). This puts the text of version VERSION in a file named `FILENAME.~VERSION~', and visits it in its own buffer in a separate window. (In RCS, you can also select an old version and create a branch from it. *Note Branches::.) It is usually more convenient to compare two versions of the file, with the command `C-x v =' (`vc-diff'). Plain `C-x v =' compares the current buffer contents (saving them in the file if necessary) with the last checked-in version of the file. `C-u C-x v =', with a numeric argument, reads a file name and two version numbers, then compares those versions of the specified file. Both forms display the output in a special buffer in another window. You can specify a checked-in version by its number; an empty input specifies the current contents of the work file (which may be different from all the checked-in versions). You can also specify a snapshot name (*note Snapshots::) instead of one or both version numbers. If you supply a directory name instead of the name of a registered file, this command compares the two specified versions of all registered files in that 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. When you invoke `diff' this way, in addition to the options specified by `diff-switches' (*note Comparing Files::), it receives those specified by `vc-diff-switches', plus those specified for the specific back end by `vc-BACKEND-diff-switches'. For instance, when the version control back end is RCS, `diff' uses the options in `vc-rcs-diff-switches'. The `vc...diff-switches' variables are `nil' by default. Unlike the `M-x diff' command, `C-x v =' does not try to locate the changes in the old and new versions. This is because normally one or both versions do not exist as files when you compare them; they exist only in the records of the master file. *Note Comparing Files::, for more information about `M-x diff'. For CVS-controlled files, you can display the result of the CVS annotate command, using colors to enhance the visual appearance. Use the command `M-x vc-annotate' to do this. It creates a new buffer to display file's text, colored to show how old each part is. Text colored red is new, blue means old, and intermediate colors indicate intermediate ages. By default, the time scale is 360 days, so that everything more than one year old is shown in blue. When you give a prefix argument to this command, it uses the minibuffer to read two arguments: which version number to display and annotate (instead of the current file contents), and a stretch factor for the time scale. A stretch factor of 0.1 means that the color range from red to blue spans the past 36 days instead of 360 days. A stretch factor greater than 1 means the color range spans more than a year.  File: emacs, Node: Secondary VC Commands, Next: Branches, Prev: Old Versions, Up: Version Control The Secondary Commands of VC ---------------------------- This section explains the secondary commands of VC; those that you might use once a day. * Menu: * Registering:: Putting a file under version control. * VC Status:: Viewing the VC status of files. * VC Undo:: Cancelling changes before or after check-in. * VC Dired Mode:: Listing files managed by version control. * VC Dired Commands:: Commands to use in a VC Dired buffer.  File: emacs, Node: Registering, Next: VC Status, Up: Secondary VC Commands 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 if there are any files under RCS control, CVS if there are any files under CVS, SCCS if any files are under SCCS, or RCS as the ultimate default. If locking is in use, `C-x v i' leaves the file unlocked and read-only. Type `C-x C-q' if you wish to start editing it. After registering a file with CVS, you must subsequently commit the initial version by typing `C-x C-q'. The initial version number for a newly registered file is 1.1, by default. You can specify a different default by setting the variable `vc-default-init-version', or you can give `C-x v i' a numeric argument; then it reads the initial version number 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 Status, Next: VC Undo, Prev: Registering, Up: Secondary VC Commands VC Status Commands .................. `C-x v l' Display version control state and change history. To view the detailed version control status and history of a file, type `C-x v l' (`vc-print-log'). It displays the history of changes to the current file, including the text of the log entries. The output appears in a separate window.  File: emacs, Node: VC Undo, Next: VC Dired Mode, Prev: VC Status, Up: Secondary VC Commands Undoing Version Control Actions ............................... `C-x v u' Revert the buffer and the file to the last checked-in version. `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 last version checked in, use `C-x v u' (`vc-revert-buffer'). This leaves the file unlocked; if locking is in use, you must first lock the file again before you change it again. `C-x v u' requires confirmation, unless it sees that you haven't made any changes since the last checked-in version. `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-cancel-version'). This command discards all record of the most recent checked-in version. `C-x v c' also offers to revert your work file and buffer to the previous version (the one that precedes the version that is deleted). If you answer `no', VC keeps your changes in the buffer, and locks the file. The no-revert option is useful when you have checked in a change and then discover a trivial error in it; you can cancel the erroneous check-in, fix the error, and check the file in again. When `C-x v c' does not revert the buffer, it unexpands all version control headers in the buffer instead (*note Version Headers::). This is because the buffer no longer corresponds to any existing version. If you check it in again, the check-in process will expand the headers properly for the new version number. However, it is impossible to unexpand the RCS `$Log$' header automatically. If you use that header feature, you have to unexpand it by hand--by deleting the entry for the version that you just canceled. Be careful when invoking `C-x v c', as it is easy to lose a lot of work with it. To help you be careful, this command always requires confirmation with `yes'. Note also that this command is disabled under CVS, because canceling versions is very dangerous and discouraged with CVS.  File: emacs, Node: VC Dired Mode, Next: VC Dired Commands, Prev: VC Undo, Up: Secondary VC Commands Dired under VC .............. The VC Dired Mode described here works with all the version control systems that VC supports. Another more powerful facility, designed specifically for CVS, is called PCL-CVS. *Note About PCL-CVS: (pcl-cvs)Top. 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-directory') to make a directory listing that includes only files relevant for version control. `C-x v d' creates a buffer which uses VC Dired Mode. This looks much like an ordinary Dired buffer (*note Dired::); however, normally it shows only the noteworthy files (those locked or not up-to-date). This is called "terse display". If you set the variable `vc-dired-terse-display' to `nil', then VC Dired shows all relevant files--those managed under version control, plus all subdirectories ("full display"). The command `v t' in a VC Dired buffer toggles between terse display and full display (*note VC Dired Commands::). By default, VC Dired produces a recursive listing of noteworthy or relevant files at or below the given directory. You can change this by setting the variable `vc-dired-recurse' to `nil'; then VC Dired shows only the files in the given directory. The line for an individual file shows the version control state in the place of the hard link count, owner, group, and size of the file. If the file is unmodified, in sync with the master file, the version control state shown is blank. Otherwise it consists of text in parentheses. 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 RCS: /home/jim/project: -rw-r--r-- (jim) Apr 2 23:39 file1 -r--r--r-- Apr 5 20:21 file2 The files `file1' and `file2' are under version control, `file1' is locked by user jim, and `file2' is unlocked. Here is an example using CVS: /home/joe/develop: -rw-r--r-- (modified) Aug 2 1997 file1.c -rw-r--r-- Apr 4 20:09 file2.c -rw-r--r-- (merge) Sep 13 1996 file3.c Here `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. When VC Dired displays subdirectories (in the "full" display mode), 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'. You can fine-tune VC Dired's format by typing `C-u C-x v d'--as in ordinary Dired, that allows you to specify additional switches for the `ls' command.  File: emacs, Node: VC Dired Commands, Prev: VC Dired Mode, Up: Secondary VC Commands VC Dired Commands ................. All the usual Dired commands work normally in VC Dired mode, except for `v', which is redefined as the version control prefix. You can invoke VC commands such as `vc-diff' and `vc-print-log' by typing `v =', or `v l', and so on. Most of these commands apply to the file name on the current line. The command `v v' (`vc-next-action') operates on all the marked files, so that you can lock or check in several files at once. If it operates on more than one file, it handles each file according to its current state; thus, it might lock one file, but check in another file. This could be confusing; it is up to you to avoid confusing behavior by marking a set of files that are in a similar state. If any files call for check-in, `v v' reads a single log entry, then uses it for all the files being checked in. This is convenient for registering or checking in several files at once, as part of the same change. You can toggle between terse display (only locked files, or files not up-to-date) and full display at any time by typing `v t' (`vc-dired-toggle-terse-mode'). There is also a special command `* l' (`vc-dired-mark-locked'), which marks all files currently locked (or, with CVS, all files not up-to-date). Thus, typing `* l t k' is another way to delete from the buffer all files except those currently locked.  File: emacs, Node: Branches, Next: Remote Repositories, Prev: Secondary VC Commands, Up: Version Control Multiple Branches of a File --------------------------- One use of version control is to maintain multiple "current" versions of a file. For example, you might have different versions 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 only supported for RCS at the moment. A file's main line of development is usually called the "trunk". The versions on the trunk are normally numbered 1.1, 1.2, 1.3, etc. At any such version, you can start an independent branch. A branch starting at version 1.2 would have version number 1.2.1.1, and consecutive versions on this branch would have numbers 1.2.1.2, 1.2.1.3, 1.2.1.4, and so on. If there is a second branch also starting at version 1.2, it would consist of versions 1.2.2.1, 1.2.2.2, 1.2.2.3, etc. If you omit the final component of a version number, that is called a "branch number". It refers to the highest existing version on that branch--the "head version" of that branch. The branches in the example above have branch numbers 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 Switching between Branches .......................... To switch between branches, type `C-u C-x C-q' and specify the version number you want to select. 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. You can omit the minor version number, thus giving only the branch number; 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 Creating New Branches ..................... To create a new branch from a head version (one that is the latest in the branch that contains it), first select that version if necessary, lock it with `C-x C-q', and make whatever changes you want. Then, when you check in the changes, use `C-u C-x C-q'. This lets you specify the version number for the new version. You should specify a suitable branch number for a branch starting at the current version. For example, if the current version is 2.5, the branch number 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 version (one that is no longer the head of a branch), first select that version (*note Switching Branches::), then lock it with `C-x C-q'. You'll be asked to confirm, when you lock the old version, that you really mean to create a new branch--if you say no, you'll be offered a chance to lock the latest version instead. Then make your changes and type `C-x C-q' again to check in a new version. This automatically creates a new branch starting from the selected version. You need not specially request a new branch, because that's the only way to add a new version 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 versions on that branch. To leave the branch, you must explicitly select a different version with `C-u C-x C-q'. 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 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 number or a pair of version numbers in the minibuffer. Then `C-x v m' finds the changes from that branch, or the differences between the two versions you specified, and merges them into the current version 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 version 1.5. To merge the changes from the branch to the trunk, first go to the head version of the trunk, by typing `C-u C-x C-q '. Version 1.5 is now current. If locking is used for the file, type `C-x C-q' to lock version 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 version 1.3, where the branch started, up to the last version on the branch) and merges it into the current version of the work file. You can now check in the changed file, thus creating version 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 version, 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 version 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 Multi-User Branching .................... It is often useful for multiple developers to work simultaneously on different branches of a file. CVS allows 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 versions, 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 version number 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 C-q' and specify the correct branch number. This ensures that Emacs knows which branch it is using during this particular editing session.  File: emacs, Node: Remote Repositories, Next: Snapshots, Prev: Branches, Up: Version Control Remote Repositories ------------------- A common way of using CVS is to set up a central CVS 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 CVS server. One difficulty is that access to the CVS server is often slow, and that developers might need to work off-line as well. VC is designed to reduce the amount of network interaction necessary. * 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 Version Backups ............... When VC sees that the CVS 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 CVS 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 Versions::), 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 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, using `C-u C-x v v cvs '.