Mercurial > emacs
changeset 99292:673c91ec655c
(Version Control): Moved to maintaining.texi. Subnodes moved as well.
(Document Files): Moved to misc.texi.
| author | Chong Yidong <cyd@stupidchicken.com> |
|---|---|
| date | Fri, 31 Oct 2008 22:00:48 +0000 |
| parents | a3986c03d1ed |
| children | b3ec60dce173 |
| files | doc/emacs/files.texi |
| diffstat | 1 files changed, 0 insertions(+), 1501 deletions(-) [+] |
line wrap: on
line diff
--- a/doc/emacs/files.texi Fri Oct 31 22:00:16 2008 +0000 +++ b/doc/emacs/files.texi Fri Oct 31 22:00:48 2008 +0000 @@ -30,14 +30,12 @@ @end ifnottex * Auto Save:: Auto Save periodically protects against loss of data. * File Aliases:: Handling multiple names for one file. -* Version Control:: Version control systems (RCS, CVS and SCCS). * Directories:: Creating, deleting, and listing file directories. * Comparing Files:: Finding where two files differ. * Diff Mode:: Mode for editing file differences. * Misc File Ops:: Other things you can do on files. * Compressed Files:: Accessing compressed files. * File Archives:: Operating on tar, zip, jar etc. archive files. -* Document Files:: Viewing PDF, PS and DVI files. * Remote Files:: Accessing files on other sites. * Quoted File Names:: Quoting special characters in file names. * File Name Cache:: Completion against a list of files you often use. @@ -1164,1351 +1162,6 @@ than the name you specify. Setting @code{find-file-visit-truename} also implies the effect of @code{find-file-existing-other-name}. -@node Version Control -@section Version Control -@cindex version control - - A @dfn{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 @code{vc-handled-backends} to @code{nil} -@iftex -(@pxref{Customizing VC,,,emacs-xtra, Specialized Emacs Features}). -@end iftex -@ifnottex -(@pxref{Customizing VC}). -@end ifnottex - - -@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. -@ifnottex -* 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. -@end ifnottex -@end menu - -@node Introduction to VC -@subsection 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. -@end menu - -@node Why Version Control? -@subsubsection Understanding the problems it addresses - - Version control systems provide you with three important -capabilities: - -@itemize @bullet -@item -@dfn{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. - -@item -@dfn{Concurrency}: the ability to have many people modifying the same -collection of files knowing that conflicting modifications can be -detected and resolved. - -@item -@dfn{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. -@end itemize - -@node Version Control Systems -@subsubsection Supported Version Control Systems - -@cindex back end (version control) - VC currently works with many different version control systems or -@dfn{back ends}: - -@itemize @bullet - -@cindex SCCS -@item -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. - -@cindex CSSC -@item -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. - -@cindex RCS -@item -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. - -@cindex CVS -@item -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. - -@cindex SVN -@cindex Subversion -@item -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. - -@cindex GNU Arch -@cindex Arch -@item -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. - -@cindex git -@item -Git is a distributed version control system invented by Linus Torvalds to support -Linux kernel development. 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. - -@cindex hg -@cindex Mercurial -@item -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. - -@cindex bzr -@cindex Bazaar -@item -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. -@end itemize - - 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. - -@node VCS Concepts -@subsubsection Concepts of Version Control - -@cindex repository -@cindex registered file - When a file is under version control, we say that it is -@dfn{registered} in the version control system. The system has a -@dfn{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 @dfn{log entries} that describe the changes made to each file. - -@cindex work file -@cindex checking out files - A file @dfn{checked out} of a repository is called the @dfn{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 -@dfn{check in} or @dfn{commit} the file; this records the changes in -the repository, along with a log entry for those changes. - -@cindex revision -@cindex revision ID - A copy of a file stored in a repository is called a @dfn{revision}. -The history of a file is a sequence of revisions. Each revisions is -named by a @dfn{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 -ways in which version control systems can differ from each other. -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 choices, but they lead to differing behaviors which -you will need to understand as you use it. - -@cindex locking versus merging - 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 -@dfn{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 @dfn{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 @dfn{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 -(@pxref{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 @dfn{lock conflicts}; a user may try to check a file out and be -unable to because it is locked. In merging systems, @dfn{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. - - 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. 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. Sometimes, however, newer version control systems may have -locks retrofitted onto them for reasons having nothing to do with -technology@footnote{Usually the control-freak instincts of managers.}. - - VC mode supports both locking and merging version control and tries -to hide the differences between them as much as possible. - -@cindex files versus changesets. - On SCCS, RCS, CVS, and other early version control systems, version -control operations are @dfn{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 -@dfn{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. But it took some years for designers to figure that out, -and while file-based systems are passing out of use, there are lots of -legacy repositories still to be dealt with as of this writing (2008). - - Prior to Emacs 23, VC supported only file-based systems, leading to -unhappy results when it was used to drive changeset-based -systems---the Subversion support, for example, used to break up -changesets into multiple per-file commits. This has been fixed, but -it has left a mark in VC's terminology. The terms ``checkin'' and -``checkout'' are associated with file-based and locking-based systems -and a bit archaic; nowadays those operations are usually called -``commit'' and ``update''. - -@cindex centralized vs. decentralized version control - Early version control systems were designed around a -@dfn{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 problem with this approach is that a single -repository is a single point of failure---if the repository server is -down, all work stops. - - Newer version control systems like GNU Arch, git, Mercurial, and -Bazaar are @dfn{decentralized}. 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. - -@node Types of Log File -@subsubsection Types of Log File -@cindex types of log file -@cindex log File, types of -@cindex version control log - - 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 @dfn{log entry} for -the change (@pxref{Log Buffer}). This is called the @dfn{version -control log}. - - The other kind of log is the file @file{ChangeLog} (@pxref{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 @file{ChangeLog} file; a large program -may have a @file{ChangeLog} file in each major directory. -@xref{Change Log}. - - Actually, the fact that both kinds of log exist is partly a legacy -from file-based version control. Changelogs are a GNU convention, -later more widely adopted, that help developers to get a -changeset-based view of a project even when its version control system -has that information split up in multiple file-based logs. - - Changeset-based version systems, on the other hand, often maintain a -changeset-based modification log for the entire system that makes -ChangeLogs somewhat redundant. One advantage that ChangeLogs 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 @file{ChangeLog}, then copy it to the log buffer with -@kbd{C-c C-a} when checking in the change (@pxref{Log Buffer}). Or -you can write the entry in the log buffer while checking in the -change, and later use the @kbd{C-x v a} command to copy it to -@file{ChangeLog} -@iftex -(@pxref{Change Logs and VC,,,emacs-xtra, Specialized Emacs Features}). -@end iftex -@ifnottex -(@pxref{Change Logs and VC}). -@end ifnottex - -@node VC Mode Line -@subsection 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, @samp{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. @samp{-} means that -the work file is not locked (if locking is in use), or not modified (if -locking is not in use). @samp{:} indicates that the file is locked, or -that it is modified. If the file is locked by some other user (for -instance, @samp{jim}), that is displayed as @samp{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 @kbd{Mouse-1} -over the indicator pops up a menu of VC commands. This menu is -identical to the @samp{Version Control} menu item, which can be found -in the @samp{Tools} menu on the menu bar. - -@vindex auto-revert-check-vc-info - When Auto Revert mode (@pxref{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 -@code{auto-revert-check-vc-info} to @code{t}, Auto Revert mode updates -the version control status information every -@code{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. - -@node Basic VC Editing -@subsection Basic Editing under Version Control - -@cindex filesets - Most VC commands operate on @dfn{VC filesets}. A VC fileset is a -group of one or more files that are treated as a unit, for the -purposes of version control. - - If you are visiting a version-controlled file in the current -buffer, the VC fileset is simply that one file. If you are visiting a -VC directory buffer, and some files in it are marked, the VC fileset -consists of the marked files (@pxref{VC Directory Mode}). - - The principal VC command is an all-purpose command, @kbd{C-x v v} -(@code{vc-next-action}), that performs either locking, merging or a -check-in on the current VC fileset, depending on the situation. You -can call @kbd{C-x v v} from a version-controlled file, or from the VC -Directory buffer. - -@table @kbd -@itemx C-x v v -Perform the next logical version control operation on the VC fileset. -@end table - -@findex vc-next-action -@kindex C-x v v - The precise action of @kbd{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 @command{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. - - If you are accustomed to previous versions of VC, most of the -changes to VC in Emacs 23 are found in VC directory mode (@pxref{VC -Directory Mode}). When multiple files are marked in the VC directory -buffer, they are treated as a VC fileset; typing @kbd{C-x v v} in the -VC directory buffer passes them to the version control backends as a -single unit. Other commands in VC directory mode now act on the VC -fileset, rather than the file on the current line. These changes -allow VC to interoperate correctly with changeset-based version -control systems. - - VC filesets are distinct from the ``named filesets'' used for -viewing and visiting files in functional groups (@pxref{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. -@end menu - -@node VC With A Merging VCS -@subsubsection 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 @samp{-} if the file is -unmodified; it flips to @samp{:} as soon as you save any changes -(@pxref{VC Mode Line}). - - Here is what @kbd{C-x v v} does when using a merging-based system: - -@itemize @bullet -@item -If the work file is the same as in the repository, it does nothing. - -@item -If you have not changed the work file, but some other user has checked -in changes to the repository, @kbd{C-x v v} merges those changes into -the work file. - -@item -If you have made modifications to the work file, @kbd{C-x v v} -attempts to check in your changes. To do this, Emacs first reads the -log entry for the new revision (@pxref{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 @kbd{C-x v v} again to -merge those changes into your own work file; this puts the work file -into a ``conflicted'' state. Type @kbd{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 @emph{without} -trying to commit your own changes, type @kbd{C-x v m @key{RET}}. -@xref{Merging}. -@end itemize - - These rules also apply when you use RCS in its ``non-locking'' mode, -except that changes will not be 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: -@kbd{C-x v v} with an unmodified file locks the file, just as it does -with RCS in its normal locking mode (@pxref{VC With A Locking VCS}). - -@node VC With A Locking VCS -@subsubsection Basic Version Control with Locking - - Under a locking-based version control system (such as SCCS, and RCS -in its default mode), @kbd{C-x v v} does the following: - - @itemize @bullet -@item -If the file is not locked, @kbd{C-x v v} locks it, and makes it -writable so that you can change it. - -@item -If the file is locked by you, and contains changes, @kbd{C-x v v} -checks in the changes. In order to do this, it first reads the log -entry for the new revision. @xref{Log Buffer}. - -@item -If the file is locked by you, but you have not changed it since you -locked it, @kbd{C-x v v} releases the lock and makes the file -read-only again. - -@item -If the file is locked by some other user, @kbd{C-x v v} 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. -@end itemize - - These rules also apply when you use CVS in locking mode, except -that there is no such thing as stealing a lock. - -@node Advanced C-x v v -@subsubsection Advanced Control in @kbd{C-x v v} - -@cindex revision ID to check in/out - When you give a prefix argument to @code{vc-next-action} (@kbd{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. - -@itemize @bullet -@item -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 (@pxref{Branches}). - -@item -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 @kbd{C-u C-x v v @key{RET}} is a convenient way to -get the latest version of a file from the repository. - -@item -@cindex specific version control system -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 -@iftex -(@pxref{Local Version Control,,,emacs-xtra, Specialized Emacs -Features}). -@end iftex -@ifnottex -(@pxref{Local Version Control}). -@end ifnottex - -@end itemize - -@node Log Buffer -@subsubsection Features of the Log Entry Buffer - - When you check in changes, Emacs pops up a buffer called -@samp{*VC-Log*} for you to enter a log entry. - - After you have finished editing the log message, type @kbd{C-c C-c} -to exit the buffer and commit the change. - -@findex log-edit-show-files -@findex log-edit-show-diff - In the @samp{*VC-Log*} buffer, typing @kbd{C-c C-f} -(@code{log-edit-show-files}) displays a list of files in the VC -fileset you are committing. If you called @kbd{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 @kbd{C-x v v} from a VC -directory buffer, the VC fileset may consist of multiple files -(@pxref{VC Directory Mode}). - -@findex log-edit-insert-changelog - Type @kbd{C-c C-d} (@code{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. -@xref{Comparing Files}. - - If you have written an entry in the @file{ChangeLog} (@pxref{Change -Log}), type @kbd{C-c C-a} (@code{log-edit-insert-changelog}) to pull -it into the @samp{*VC-Log*} buffer. If the topmost item in the -@file{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. -@iftex -@xref{Change Logs and VC,,,emacs-xtra, Specialized Emacs Features}, -@end iftex -@ifnottex -@xref{Change Logs and VC}, -@end ifnottex -for the opposite way of working---generating ChangeLog entries from -the revision control log. - - To abort a check-in, just @strong{don't} type @kbd{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 @samp{*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 @kbd{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 @kbd{M-n}, @kbd{M-p}, @kbd{M-s} and @kbd{M-r} for doing this -work just like the minibuffer history commands (except that these -versions are used outside the minibuffer). - -@vindex vc-log-mode-hook - Each time you check in a change, the log entry buffer is put into VC -Log Edit mode, which involves running two hooks: @code{text-mode-hook} -and @code{vc-log-mode-hook}. @xref{Hooks}. - -@node Old Revisions -@subsection 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. - -@table @kbd -@item C-x v ~ @var{revision} @key{RET} -Examine revision @var{revision} of the visited file, in a buffer of its -own. - -@item C-x v = -Compare the buffer contents associated with the current -fileset with the working revision(s) from which you started editing. - -@item C-u C-x v = @key{RET} @var{oldvers} @key{RET} @var{newvers} @key{RET} -Compare the specified two repository revisions of the current fileset. - -@item C-x v g -Display an annotated version of the file: for each line, show the -latest revision in which it was modified. -@end table - -@findex vc-revision-other-window -@kindex C-x v ~ - To examine an old revision, visit the work file and type @kbd{C-x v -~ @var{revision} @key{RET}} (@code{vc-revision-other-window}). Here, -@var{revision} is either the desired revision ID (@pxref{VCS -Concepts}), or the name of a tag or branch -@iftex -(@pxref{Tags,,,emacs-xtra, Specialized Emacs Features}). -@end iftex -@ifnottex -(@pxref{Tags}). -@end ifnottex -This command puts the text of the old revision in a file named -@file{@var{filename}.~@var{revision}~}, and visits it in its own -buffer in a separate window. - -@findex vc-diff -@kindex C-x v = - @kbd{C-x v =} (@code{vc-diff}) compares the current buffer contents -of each file in the current VC fileset (saving them if necessary) with -the repository revision 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. @xref{Comparing -Files}. - -@findex vc-diff -@kindex C-u C-x v = - To compare two arbitrary revisions of the current VC fileset, call -@code{vc-diff} with a prefix argument: @kbd{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 -@iftex -(@pxref{Tags,,,emacs-xtra, Specialized Emacs Features}). -@end iftex -@ifnottex -(@pxref{Tags}). -@end ifnottex -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. - - If you invoke @kbd{C-x v =} or @kbd{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. - -@vindex vc-diff-switches -@vindex vc-rcs-diff-switches - @kbd{C-x v =} works by running a variant of the @code{diff} utility -designed to work with the version control system in use. When you -invoke @code{diff} this way, in addition to the options specified by -@code{diff-switches} (@pxref{Comparing Files}), it receives those -specified by @code{vc-diff-switches}, plus those specified for the -specific back end by @code{vc-@var{backend}-diff-switches}. For -instance, when the version control back end is CVS, @code{diff} uses -the options in @code{vc-cvs-diff-switches}. The -@samp{vc@dots{}diff-switches} variables are @code{nil} by default. - - The buffer produced by @kbd{C-x v =} supports the commands of -Compilation mode (@pxref{Compilation Mode}), such as @kbd{C-x `} and -@kbd{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.) - -@findex vc-annotate -@kindex C-x v g - For some back ends, you can display the file @dfn{annotated} with -per-line revision information, by typing @kbd{C-x v g} -(@code{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 @samp{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: - -@table @kbd -@item 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 @kbd{C-u 10 p} would take you back 10 revisions. - -@item n -Annotate the next revision---the one after the revision currently -annotated. A numeric prefix argument is a repeat count. - -@item j -Annotate the revision indicated by the current line. - -@item 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. - -@item f -Show in a buffer the file revision indicated by the current line. - -@item 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. - -@item 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. - -@item 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. - -@item w -Annotate the working revision--the one you are editing. If you used -@kbd{p} and @kbd{n} to browse to other revisions, use this key to -return to your working revision. - -@item v -Toggle the annotation visibility. This is useful for looking just at -the file contents without distraction from the annotations. -@end table - -@node Secondary VC Commands -@subsection The Secondary Commands of VC - - This section explains the secondary commands of VC. - -@menu -* Registering:: Putting a file under version control. -* VC Status:: Viewing the VC status of files. -* VC Undo:: Canceling changes before or after check-in. -@end menu - -@node Registering -@subsubsection Registering a File for Version Control - -@kindex C-x v i -@findex vc-register - You can put any file under version control by simply visiting it, and -then typing @w{@kbd{C-x v i}} (@code{vc-register}). - -@table @kbd -@item C-x v i -Register the visited file for version control. -@end table - - 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 @code{vc-handled-backends} -@iftex -(@pxref{Customizing VC,,,emacs-xtra, Specialized Emacs Features}). -@end iftex -@ifnottex -(@pxref{Customizing VC}). -@end ifnottex -On the other hand, if there are no files already registered, Emacs uses -the first system from @code{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 @code{vc-handled-backends}, this means that Emacs uses RCS in this -situation. - - If locking is in use, @kbd{C-x v i} leaves the file unlocked and -read-only. Type @kbd{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 @kbd{C-x v v}. Until you do that, the revision ID -appears as @samp{@@@@} in the mode line. - -@vindex vc-default-init-revision -@cindex initial revision ID to register - 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 -@code{vc-default-init-revision}, or you can give @kbd{C-x v i} a -numeric argument; then it reads the initial revision ID for this -particular file using the minibuffer. - -@vindex vc-initial-comment - If @code{vc-initial-comment} is non-@code{nil}, @kbd{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 (@pxref{Log Buffer}). - -@node VC Status -@subsubsection VC Status Commands - -@table @kbd -@item C-x v l -Display revision control state and change history. -@end table - -@kindex C-x v l -@findex vc-print-log - To view the detailed revision control status and history of a file, -type @kbd{C-x v l} (@code{vc-print-log}). This pops up a special -buffer named @samp{*vc-change-log*}, in a new window, that displays -the history of changes to the current file, including the text of the -log entries. The point is centered at the revision of the file that -is currently being visited. - - In the @samp{*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: - -@table @kbd -@item 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. - -@item 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. - -@item P -Move to the log of the previous file, when the logs of multiple files -are in the log buffer (@pxref{VC Directory Mode}). Otherwise, just -move to the beginning of the log. A numeric prefix argument is a -repeat count, so @kbd{C-u 10 P} would move backward 10 files. - -@item N -Move to the log of the next file, when the logs of multiple files are -in the log buffer (@pxref{VC Directory Mode}). It also takes a -numeric prefix argument as a repeat count. - -@item a -Annotate the revision indicated by the current line. - -@item e -Modify the change comment displayed at point. Note that not all VC -systems support modifying change comments. - -@item f -Visit the revision indicated at the current line, like typing @kbd{C-x -v ~} and specifying this revision's ID (@pxref{Old Revisions}). - -@item d -Display the diff (@pxref{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. - -@item D -Display the changeset diff (@pxref{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. -@end table - -@node VC Undo -@subsubsection Undoing Version Control Actions - -@table @kbd -@item C-x v u -Revert the buffer and the file to the working revision from which you started -editing the file. - -@item C-x v c -Remove the last-entered change from the master for the visited file. -This undoes your last check-in. -@end table - -@kindex C-x v u -@findex vc-revert-buffer - If you want to discard your current set of changes and revert to the -working revision from which you started editing the file, use @kbd{C-x -v u} (@code{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. @kbd{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. - - @kbd{C-x v u} is also the command to unlock a file if you lock it and -then decide not to change it. - -@kindex C-x v c -@findex vc-rollback - To cancel a change that you already checked in, use @kbd{C-x v c} -(@code{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 @kbd{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. - -@node VC Directory Mode -@subsection VC Directory Mode - -@kindex C-x v d -@findex vc-dir - 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 @kbd{C-x v d} (@code{vc-dir}) to make a directory -listing that includes only files relevant for version control. This -creates a @dfn{VC Directory buffer} and displays it in a separate -window. - -@cindex PCL-CVS -@pindex cvs -@cindex CVS directory mode - The VC Directory buffer described here works with all the version -control systems that VC supports. Another more powerful facility, -designed specifically for CVS, is called PCL-CVS. @xref{Top, , About -PCL-CVS, pcl-cvs, PCL-CVS --- The Emacs Front-End to CVS}. - - 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 -omitted; if all files in a directory are up-to-date, the directory is -omitted as well. (However, the directory in which @code{vc-dir} was -run will always be shown as @file{./}.) 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 @code{vc-dir} command by invoking -@code{vc-dir} with a prefix argument: @kbd{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 @samp{cvs status} -output is used. Here is an example using CVS: - -@smallexample -@group - ./ - modified file1.c - needs-update file2.c - needs-merge file3.c -@end group -@end smallexample - -@noindent -In this example, @samp{file1.c} is modified with respect to the -repository, and @samp{file2.c} is not. @samp{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. - -@vindex vc-stay-local -@vindex vc-cvs-stay-local - In the above, if the repository were on a remote machine, VC only -contacts it when the variable @code{vc-stay-local} (or -@code{vc-cvs-stay-local}) is nil (@pxref{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 @samp{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 -@kbd{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. - -@vindex vc-directory-exclusion-list - 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 @samp{RCS} and -@samp{CVS}; you can customize this by setting the variable -@code{vc-directory-exclusion-list}. - -@menu -* VC Directory Commands:: Commands to use in a VC directory buffer. -@end menu - -@node VC Directory Commands -@subsubsection 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 @kbd{mouse-2} button. - - Up- and down-arrow keys move in the buffer; @kbd{n} and @kbd{p} also -move vertically as in other list-browsing modes. @key{SPC} and -@key{TAB} behave like down-arrow, and @key{BackTab} behaves like -up-arrow. - - Both @kbd{C-m} and @kbd{f} visit the file on the current -line. @kbd{o} visits that file in another window. @kbd{q} dismisses -the directory buffer. - - @kbd{x} toggles hiding of up-to-date files. - - @kbd{m} marks the file or directory on the current line. If the -region is active, @kbd{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. - - @kbd{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. - - @kbd{u} unmarks the file or directory on the current line. If the -region is active, it unmarks all the files in the region. - - @kbd{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. - - @kbd{S} searches the marked files. - - @kbd{Q} does a query replace on the marked files. - - @kbd{M-s a C-s} does an incremental search on the marked files. - - @kbd{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. - - Normal VC commands with the @kbd{C-x v} prefix work in VC directory -buffers. Some single-key shortcuts are available as well; @kbd{=}, -@kbd{+}, @kbd{l}, @kbd{i}, and @kbd{v} behave as through prefixed with -@kbd{C-x v}. - - The command @kbd{C-x v v} (@code{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, @kbd{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 @kbd{C-x v v} (@code{vc-next-action}) operates on a set of files, -it requires that all of those files must be either in the same state or -in compatible states; otherwise it will throw an error (added, -modified and removed states are considered compatible). Note that this -differs from the behavior of older versions of VC, which did not have -fileset operations and simply did @code{vc-next-action} on each file -individually. - - If any files are in a state that calls for commit, @kbd{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. - -@node Branches -@subsection Multiple Branches of a File -@cindex branch (version control) -@cindex trunk (version control) - - 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 -@dfn{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 @dfn{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. - -@cindex head revision - If you omit the final component of a dot-pair revision ID, that is called a -@dfn{branch ID}. It refers to the highest existing revision on that -branch---the @dfn{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. -@end menu - -@node Switching Branches -@subsubsection Switching between Branches - - To switch between branches, type @kbd{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 @emph{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 @key{RET}, 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. - -@node Creating Branches -@subsubsection 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 @kbd{C-x v v}, and make whatever changes you want. Then, -when you check in the changes, use @kbd{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 (@pxref{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 -@kbd{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 @kbd{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 @kbd{C-u C-x -v v}. To transfer changes from one branch to another, use the merge -command, described in the next section. - -@node Merging -@subsubsection Merging Branches - -@cindex merging changes - 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 @dfn{merge} the -changes into a file that has already been changed otherwise. VC allows -you to do this (and other things) with the @code{vc-merge} command. - -@table @kbd -@item C-x v m (vc-merge) -Merge changes into the work file. -@end table - -@kindex C-x v m -@findex vc-merge - @kbd{C-x v m} (@code{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 -@key{RET}, Emacs merges any changes that were made on the same branch -since you checked the file out (we call this @dfn{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 @kbd{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 @kbd{C-u C-x v v -@key{RET}}. Revision 1.5 is now current. If locking is used for the file, -type @kbd{C-x v v} to lock revision 1.5 so that you can change it. Next, -type @kbd{C-x v m 1.3.1 @key{RET}}. 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. - -@cindex conflicts -@cindex resolving conflicts - When you merge changes into a file that has itself been modified, the -changes might overlap. We call this situation a @dfn{conflict}, and -reconciling the conflicting changes is called @dfn{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 (@pxref{Top, -Ediff, Ediff, ediff, The Ediff Manual}). - - If you say no, the conflicting changes are both inserted into the -file, surrounded by @dfn{conflict markers}. The example below shows how -a conflict region looks; the file is called @samp{name} and the current -master file revision with user B's changes in it is 1.11. - -@c @w here is so CVS won't think this is a conflict. -@smallexample -@group -@w{<}<<<<<< name - @var{User A's version} -======= - @var{User B's version} -@w{>}>>>>>> 1.11 -@end group -@end smallexample - -@cindex vc-resolve-conflicts - Then you can resolve the conflicts by editing the file manually. Or -you can type @code{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. - -@node Multi-User Branching -@subsubsection 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 -@file{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 -@iftex -(@pxref{Version Headers,,,emacs-xtra, Specialized Emacs Features}). -@end iftex -@ifnottex -(@pxref{Version Headers}). -@end ifnottex -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 @kbd{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. - -@ifnottex -@include vc1-xtra.texi -@end ifnottex - @node Directories @section File Directories @@ -2989,160 +1642,6 @@ need these programs to look at the archive table of contents, only to extract or manipulate the subfiles in the archive. - -@node Document Files -@section Document Files -@cindex mode, pdf, ps, dvi -@cindex DocView mode -@cindex mode, DocView -@cindex document files -@findex doc-view-mode - -DocView mode is a document viewer for Emacs (@code{doc-view-mode}). -It's capable of displaying PDF, PS and DVI files inside an Emacs buffer -and provides some convenience features like slicing, zooming and -searching inside the document. - -@vindex doc-view-cache-directory -This is done by using @command{gs} (GhostScript) to convert the document -to a set of PNG images which are then displayed. In order to omit -double conversions of documents those images are cached in -@code{doc-view-cache-directory}. - -@findex doc-view-minor-mode -@findex doc-view-toggle-display -By default Emacs opens all pdf and dvi files using DocView mode. You'll -be greeted with a welcome screen and as soon as the first page's -conversion finished, it'll be displayed. PostScript files are opened -with @code{ps-mode} by default, but additionally -@code{doc-view-minor-mode} is enabled, which adds the binding @kbd{C-c -C-c} (@code{doc-view-toggle-display}) and toggles between the editing -mode (@code{ps-mode} in case of PS files, @code{fundamental-mode} in -case of PDF or DVI files) and DocView mode. - -@findex doc-view-enlarge -@findex doc-view-shrink -You can enlarge or shrink the document with @kbd{+} -(@code{doc-view-enlarge}) and @kbd{-} (@code{doc-view-shrink}). - -The DocView buffer can be buried with @kbd{q} and killed with @kbd{k}. - -@menu -* Navigation:: Navigation inside DocView buffers. -* Searching:: Searching inside documents. -* Slicing:: Specifing which part of pages should be displayed. -* Conversion:: Influencing and triggering converison. -@end menu - -@node Navigation -@subsection Navigation - -Inside DocView mode you can scroll the current page using the usual -Emacs movement keys, that is the arrow keys or @kbd{C-p}, @kbd{C-n}, -@kbd{C-b} and @kbd{C-f}. - -@findex doc-view-next-page -@findex doc-view-previous-page -To go to the next page use @kbd{n}, @kbd{@key{next}} or @kbd{C-x ]} -(@code{doc-view-next-page}), to go to the previous page use @kbd{p}, -@kbd{@key{prior}} or @kbd{C-x [} (@code{doc-view-previous-page}). - -@findex doc-view-scroll-up-or-next-page -@findex doc-view-scroll-down-or-previous-page -While reading a document it's convenient to scroll the current page and -switch to the next one if it's already scrolled to the bottom. This -functionality is bound to @kbd{@key{SPC}} -(@code{doc-view-scroll-up-or-next-page}). @kbd{@key{DEL}} will do the -same in the other direction -(@code{doc-view-scroll-down-or-previous-page}). - -@findex doc-view-first-page -@findex doc-view-last-page -To go to the first page use @kbd{M-<} (@code{doc-view-first-page}), to -go to the last one use @kbd{M->} (@code{doc-view-last-page}). - -@findex doc-view-goto-page -To jump to a page by its number use @kbd{M-g M-g} or @kbd{M-g g} -(@code{doc-view-goto-page}). - -@node Searching -@subsection Searching - -It's possible to search for a regular expression (@pxref{Regexps}) -inside documents. In order to do that, the document file will be -converted to text and the search will be performed in the text file. -The interface to searching is inspired by @code{isearch} -(@pxref{Incremental Search}). - -@findex doc-view-search -@findex doc-view-search-backward -To initiate a search use @kbd{C-s} (@code{doc-view-search}) or @kbd{C-r} -(@code{doc-view-search-backward}). You'll be queried for a regular -expression and after hitting @kbd{@key{RET}} the number of matches will -be echoed. Navigation between the matches is done by pressing @kbd{C-s} -and @kbd{C-r} again. - -@findex doc-view-show-tooltip -Since there's no possibility to show the match inside the image itself, -a tooltip will be shown at the mouse position which lists all matching -lines of the current page. You can force the tooltip to be shown with -@kbd{C-t} (@code{doc-view-show-tooltip}). - -To initiate a new search call @code{doc-view-search} with a prefix -argument, i.e. @kbd{C-u C-s} or @kbd{C-u C-r} for a backward search. - -@node Slicing -@subsection Slicing - -Quite often documents have huge margins for printing. These are -annoying when reading the document on a computer, because they use up -screen space and thus can force inconvenient scrolling. - -@findex doc-view-set-slice -@findex doc-view-set-slice-using-mouse -To prevent you from that DocView lets you select the slice of the pages -you're interested in. To do that hit @kbd{s s} -(@code{doc-view-set-slice}) to enter the top left pixel position and the -slice's width and height. A more convenient method is provided by -@kbd{s m} (@code{doc-view-set-slice-using-mouse}), where you use the -mouse to select the slice. - -@findex doc-view-reset-slice -To reset the selected slice use @kbd{s r} (@code{doc-view-reset-slice}). - -@node Conversion -@subsection Conversion - -As said before DocView mode will automatically convert the document -files when visiting them unless @code{doc-view-cache-directory} already -contains the converted PNG images. In that case it'll use the cached -files. - -@findex doc-view-clear-cache -You can clean up the cache directory with @code{M-x -doc-view-clear-cache}. - -If a document has changed, it'll be converted anew when visiting it. -DocView recognizes documents by the md5 sum of their contents. - -@findex doc-view-kill-proc -@findex doc-view-kill-proc-and-buffer -To force a reconversion of the currently viewed document hit @kbd{r} or -@kbd{g} (@code{revert-buffer}). Killing the converter process -associated with the current buffer can be done with @kbd{K} -(@code{doc-view-kill-proc}). The key @kbd{k} will do the same and -additionally kill the DocView buffer -(@code{doc-view-kill-proc-and-buffer}). - -The zoom commands @kbd{+} (@code{doc-view-enlarge}) and @kbd{-} -(@code{doc-view-shrink}) will also reconvert the current document using -another resolution. The current page will be converted first. - -@vindex doc-view-resolution -The default resolution for conversion can be customized via the variable -@code{doc-view-resolution}. - - @node Remote Files @section Remote Files