\input texinfo @c -*-texinfo-*-@c "@(#)$Name: $:$Id: pcl-cvs.texi,v 1.16 2002/08/16 06:29:40 eggert Exp $"@c %**start of header@setfilename ../info/pcl-cvs@settitle PCL-CVS --- Emacs Front-End to CVS@syncodeindex vr fn@c %**end of header@copyingCopyright @copyright{} 1991, 1992, 1993, 1994, 1995, 1996, 1997, 1998,1999, 2000, 2002 Free Software Foundation, Inc.@quotationPermission is granted to copy, distribute and/or modify this documentunder the terms of the GNU Free Documentation License, Version 1.1 orany later version published by the Free Software Foundation; with theInvariant Sections being ``The GNU Manifesto'', ``Distribution'' and``GNU GENERAL PUBLIC LICENSE'', with the Front-Cover texts being ``A GNUManual'', and with the Back-Cover Texts as in (a) below. A copy of thelicense is included in the section entitled ``GNU Free DocumentationLicense'' in the Emacs manual.This document is part of a collection distributed under the GNU FreeDocumentation License. If you want to distribute this documentseparately from the collection, you can do so by adding a copy of thelicense to the document, as described in section 6 of the license.(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modifythis GNU Manual, like GNU software. Copies published by the FreeSoftware Foundation raise funds for GNU development.''@end quotation@end copying@dircategory Emacs@direntry* PCL-CVS: (pcl-cvs). Emacs front-end to CVS.@end direntry@c The titlepage section does not appear in the Info file.@titlepage@sp 4@c The title is printed in a large font.@center @titlefont{User's Guide}@sp@center @titlefont{to}@sp@center @titlefont{PCL-CVS --- The Emacs Front-End to CVS}@ignore@sp 2@center release 2.9@c -release-@end ignore@sp 3@center Per Cederqvist@center Stefan Monnier@c -date-@c The following two commands start the copyright page@c for the printed manual. This will not appear in the Info file.@page@vskip 0pt plus 1filll@insertcopying@end titlepage@c ================================================================@c The real text starts here@c ================================================================@node Top, About PCL-CVS, (dir), (dir)@ifnottex@top PCL-CVSThis manual describes PCL-CVS, the GNU Emacs front-end to CVS. Itis nowhere near complete, so you are advised to use @kbd{M-xcustomize-group RET pcl-cvs @key{RET}} and to look at the documentation stringsof the various commands and major modes for further information.@c This manual is updated to release 2.5 of PCL-CVS.@end ifnottex@menu* About PCL-CVS:: Installation, credits, history, @dots{}* Getting started:: An introduction with a walk-through example.* Buffer contents:: An explanation of the buffer contents.* Selected files:: To which files are commands applied.* Commands:: All commands, grouped by type.* Log Edit Mode:: Major mode to edit log messages.* Log View Mode:: Major mode to browse log changes.@c * CVS Status Mode:: Major mode to view CVS' status output.* Customization:: How you can tailor PCL-CVS to suit your needs.* Bugs:: Bugs (known and unknown).* Function and Variable Index:: List of functions and variables.* Concept Index:: List of concepts.* Key Index:: List of keystrokes.@detailmenu --- The Detailed Node Listing ---About PCL-CVS* Contributors:: Contributors to PCL-CVS.* Installation:: Commands* Entering PCL-CVS:: Commands to invoke PCL-CVS* Setting flags:: Setting flags for CVS commands* Updating the buffer:: * Movement commands:: How to move up and down in the buffer* Marking files:: How to mark files that other commands will later operate on.* Committing changes:: Checking in your modifications to the CVS repository. * Editing files:: Loading files into Emacs.* Getting info about files:: Display the log and status of files.* Adding and removing files:: Adding and removing files* Undoing changes:: Undoing changes* Removing handled entries:: Uninteresting lines can easily be removed.* Ignoring files:: Telling CVS to ignore generated files.* Viewing differences:: Commands to @samp{diff} different versions.* Invoking Ediff:: Running @samp{ediff} from @samp{*cvs*} buffer.* Updating files:: Updating files that Need-update.* Tagging files:: Tagging files.* Miscellaneous commands:: Miscellaneous commands.Customization* Customizing Faces:: @end detailmenu@end menu@node About PCL-CVS, Getting started, Top, Top@chapter About PCL-CVS@cindex About PCL-CVSPCL-CVS is a front-end to CVS versions 1.9 and later.It concisely shows the present status of a checked out module in anEmacs buffer and provides single-key access to the most frequently used CVScommands.For Emacs users accustomed to VC, PCL-CVS can be thought of as a replacementfor VC-dired (@pxref{VC Dired Mode, , Dired under VC, emacs, The GNUEmacs Manual}) specifically designed for CVS.PCL-CVS was originally written many years ago by Per Cederqvist whoproudly maintained it until January 1996, at which point he released thebeta version 2.0b2 and passed on the maintainership to Greg A Woods.Development stayed mostly dormant for a few years during whichversion 2.0 never seemed to be able to leave the ``beta'' stage while aseparate XEmacs version was slowly splitting away. In late 1998,Stefan Monnier picked up development again, adding some major newfunctionality and taking over the maintenance.As of Emacs 21, PCL-CVS is part of the standard Emacs distribution.@menu* Contributors:: Contributors to PCL-CVS.* Installation:: @end menu@node Contributors, Installation, About PCL-CVS, About PCL-CVS@section Contributors to PCL-CVS@cindex Contributors@cindex AuthorsContributions to the package are welcome. I have limited time to workon this project, but I will gladly add any code that you contribute tome to this package (@pxref{Bugs}).The following persons have made contributions to PCL-CVS.@itemize @bullet@itemBrian Berliner wrote CVS, together with some other contributors.Without his work on CVS this package would be useless@dots{}@itemPer Cederqvist wrote most of the otherwise unattributed functions inPCL-CVS as well as all the documentation.@item@email{inge@@lysator.liu.se, Inge Wallin} wrote the skeleton of@file{pcl-cvs.texi}, and gave useful comments on it. He also wrotethe files @file{elib-node.el} and @file{compile-all.el}. The file@file{cookie.el} was inspired by Inge.@refill@item@email{linus@@lysator.liu.se, Linus Tolke} contributed useful commentson both the functionality and the documentation.@refill@item@email{jwz@@jwz.com, Jamie Zawinski} contributed@file{pcl-cvs-lucid.el}, which was later renamed to@file{pcl-cvs-xemacs.el}.@refill@itemLeif Lonnblad contributed RCVS support (since superseded by the newremote CVS support).@item@email{jimb@@cyclic.com, Jim Blandy} contributed hooks to automaticallyguess CVS log entries from @file{ChangeLog} contents, and initial support ofthe new Cygnus / Cyclic remote CVS, as well as various sundry bug fixesand cleanups.@item@email{kingdon@@cyclic.com, Jim Kingdon} contributed lots of fixes tothe build and installation procedure.@item@email{woods@@weird.com, Greg A.@: Woods} contributed code to implementthe use of per-file diff buffers, and vendor join diffs with emerge andediff, as well as various and sundry bug fixes and cleanups.@item@email{greg.klanderman@@alum.mit.edu, Greg Klanderman} implementedtoggling of marked files, setting of CVS command flags via prefixarguments, updated the XEmacs support, updated the manual, and fixednumerous bugs.@item@email{monnier@@cs.yale.edu, Stefan Monnier} added a slew of otherfeatures and introduced even more new bugs. If there's any bug left,you can be sure it's his.@item@c wordy to avoid an underfull hbox@email{masata-y@@is.aist-nara.ac.jp, Masatake YAMATO} made a graciouscontribution of his cvstree code to display a tree of tags which was latersuperseded by the new @code{cvs-status-mode}.@end itemizeApart from these, a lot of people have sent us suggestions, ideas,requests, bug reports and encouragement. Thanks a lot! Without youthere would be no new releases of PCL-CVS.@node Installation, , Contributors, About PCL-CVS@section Installation@cindex InstallationAs mentioned above, PCL-CVS comes bundled with Emacs version 21.1 andlater. If you're using Emacs 20, you can download an older version ofPCL-CVS from @uref{ftp://flint.cs.yale.edu/pub/monnier/pcl-cvs}. Thatversion also works on XEmacs.If you are running XEmacs 21.0 or later, PCL-CVS is available inpre-compiled package form. Please refer to the XEmacs manual forinstructions regarding package selection and installation. Currently,that PCL-CVS package also requires you to have installed the@file{xemacs-base}, @file{elib}, and @file{dired} packages. If you have @TeX{} installed at your site, you can make a typeset manualfrom @file{pcl-cvs.texi}.@enumerate@itemIf PCL-CVS came with the Emacs distribution, type @kbd{make pcl-cvs.dvi}in the @file{man} subdirectory of the Emacs source tree.@itemAlternatively, run @TeX{} by typing @kbd{texi2dvi pcl-cvs.texi}.@itemConvert the resulting device independent file @file{pcl-cvs.dvi} to aform which your printer can output and print it. If you have aPostScript printer, there is a program, @code{dvi2ps}, which does. Thereis also a program which comes together with @TeX{}, @code{dvips}, whichyou can use.@end enumerate@node Getting started, Buffer contents, About PCL-CVS, Top@chapter Getting started@cindex Introduction@cindex Example run@cindex Sample sessionThis document assumes that you know what CVS is, and that you at leastknow the fundamental concepts of CVS. If that is not the case, youshould read the CVS documentation. Type @kbd{info -f cvs} or @kbd{mancvs}.PCL-CVS is only useful once you have checked out a module. So beforeyou invoke it, you must have a copy of a module somewhere in the filesystem.You can invoke PCL-CVS by typing @kbd{M-x cvs-examine @key{RET}}.You can also invoke it via the menu bar, under @samp{Tools}.Or, if you prefer, you can also invoke PCL-CVS by simply visiting theCVS administrative subdirectory of your module, with a prefix argument.For example, to invoke PCL-CVS in a separate frame, type @kbd{C-u C-x 5f ~/my/project/CVS @key{RET}}.The function @code{cvs-examine} will ask for a directory. The command@samp{cvs -n update} will be run in that directory. (It should containfiles that have been checked out from a CVS archive.) The output from@code{cvs} will be parsed and presented in a table in a buffer called@samp{*cvs*}. It might look something like this:@exampleRepository : /usr/CVSrootModule : testWorking dir: /users/ceder/FOO/testIn directory .: Need-Update bar Need-Update file.txt Modified namechange Need-Update newerIn directory sub: Modified ChangeLog--------------------- End ----------------------- last cmd: cvs -f -z6 -n update -d -P --@end exampleIn this example, your repository is in @file{/usr/CVSroot} and CVS hasbeen run in the directory @file{/users/ceder/FOO/test}. The three files(@file{bar}, @file{file.txt} and @file{newer}) that are marked with @samp{Need-Update} have been changedby someone else in the CVS repository. Two files (@file{namechange}and @file{sub/ChangeLog}) have been modified locally, and need to bechecked in.You can move the cursor up and down in the buffer with @kbd{C-n} and@kbd{C-p} or @kbd{n} and @kbd{p}. If you press @kbd{c} on one of the@samp{Modified} files, that file will be checked in to the CVSrepository. @xref{Committing changes}. You can also press @kbd{O} toupdate any of the files that are marked @samp{Need-Update}. You canalso run @kbd{M-x cvs-update @key{RET}} (bound to @kbd{M-u} in the@samp{*cvs*} buffer) to update all the files.@refillYou can then press @kbd{=} to easily get a @samp{diff} between yourmodified file and the base version that you started from, or you canpress @kbd{l} to get the output from @samp{cvs log}. Many more suchcommands are available simply by pressing a key (@pxref{Getting infoabout files}).@node Buffer contents, Selected files, Getting started, Top@chapter Buffer contents@cindex Buffer contents@cindex @code{*cvs*} buffer contentsThe display contains several columns, some of which are optional.These columns are, from left to right:@itemize @bullet@itemOptionally, the head revision of the file. This is the latest versionfound in the repository. It might also contain (instead of the headrevision) a sub status which typically gives further information abouthow we got to the current state, for example @samp{patched},@samp{merged}, @dots{}@itemAn asterisk when the file is @dfn{marked} (@pxref{Selectedfiles}).@refill@itemThe actual status of the file wrt the repository. See below.@itemOptionally, the base revision of the file. This is the versionwhich the copy in your working directory is based upon.@itemThe file name.@end itemizeThe @samp{file status} field can have the following values:@table @samp@item ModifiedThe file is modified in your working directory, and there was nomodification to the same file in the repository. This status can havethe following substatus:@table @samp@item mergedThe file was modified in your working directory, and there weremodifications in the repository as well, but they were mergedsuccessfully, without conflict, in your working directory.@refill@end table@item ConflictA conflict was detected while trying to merge your changes to @var{file}with changes from the repository. @var{file} (the copy in yourworking directory) is now the output of the @code{rcsmerge} command onthe two versions; an unmodified copy of your file is also in yourworking directory, with the name @file{.#@var{file}.@var{version}},where @var{version} is the RCS revision that your modified file startedfrom. @xref{Viewing differences}, for more details.@refillA conflict can also come from a disagreement on the existence of the filerather than on its content. This case is indicated by the followingpossible substatus:@table @samp@item removedThe file is locally removed but a new revision has been committed tothe repository by someone else.@item addedThe file is locally added and has also been added to the repositoryby someone else.@item modifiedThe file is locally modified but someone else has removed it from therepository.@end table@item AddedThe file has been added by you, but it still needs to be checked in tothe repository.@refill@item RemovedThe file has been removed by you, but it still needs to be checked in tothe repository. You can resurrect it by typing @kbd{a} (@pxref{Addingand removing files}).@refill@item UnknownA file that was detected in your directory, but that neither appears inthe repository, nor is present on the list of files that CVS shouldignore.@refill@item Up-to-dateThe file is up to date with respect to the version in the repository.This status can have a substatus of:@table @samp@item addedYou have just added the file to the repository.@refill@item updatedThe file was brought up to date with respect to the repository. This isdone for any file that exists in the repository but not in your source,and for files that you haven't changed but are not the most recentversions available in the repository.@refill@item patchedThe file was brought up to date with respect to the remote repository byway of fetching and applying a patch to the file in your source. Thisis equivalent to @samp{updated} except that CVS decided to use a hopefullymore efficient method.@refill@item committedYou just committed the file.@refill@end table@item Need-UpdateEither a newer version than the one in your source is available in therepository and you have not modified your checked out version, or thefile exists in the repository but not in your source. Use@samp{cvs-mode-update} bound to @kbd{O} to update the file.@refill@item Need-MergeYou have modified the checked out version of the file, and a newerversion is available in the repository. A merge will take place whenyou run a @samp{cvs-update}.@item MissingThe file has been unexpectedly removed from your working directoryalthough it has not been @samp{cvs remove}d.@end table@node Selected files, Commands, Buffer contents, Top@chapter Selected files@cindex Selected files@cindex Marked files@cindex File selection@cindex Active files@cindex ApplicableMany of the commands work on the current set of @dfn{selected} fileswhich can be either the set of marked files (if any file is marked andmarks are no ignored) or whichever file or directory the cursor is on.If a directory is selected but the command cannot be applied to adirectory, then it will be applied to the set of files under thisdirectory which are in the @samp{*cvs*} buffer.@findex cvs-mode-force-command@findex cvs-allow-dir-commitFurthermore, each command only operates on a subset of the selectedfiles, depending on whether or not the command is @dfn{applicable} toeach file (based on the file's status). For example,@code{cvs-mode-commit} is not applicable to a file whose status is@samp{Need-Update}. If it should happen that PCL-CVS guesses theapplicability wrong, you can override it with the special prefix@code{cvs-mode-force-command} normally bound to @kbd{M-f} (and file abug report). The applicability rule can be slightly changed with@code{cvs-allow-dir-commit} and @code{cvs-force-dir-tag}.By default, marks are always in effect (you may change this, however, bysetting the variable @code{cvs-default-ignore-marks}) except for thecommands that @samp{tag} or @samp{diff} a file (which can be changedwith the variable @code{cvs-invert-ignore-marks}).In addition, you may use the special prefix @code{cvs-mode-toggle-marks}normally bound to @key{T} to toggle the use of marks for the followingcommand.This scheme might seem a little complicated, but once one gets used toit, it is quite powerful.For commands to mark and unmark files, see @ref{Marking files}.@node Commands, Log Edit Mode, Selected files, Top@chapter Commands@iftexThis chapter describes all the commands that you can use in PCL-CVS.@end iftex@ifnottexThe nodes in this menu contains explanations about all the commands thatyou can use in PCL-CVS. They are grouped together by type.@end ifnottex@menu* Entering PCL-CVS:: Commands to invoke PCL-CVS* Setting flags:: Setting flags for CVS commands* Updating the buffer:: * Movement commands:: How to move up and down in the buffer* Marking files:: How to mark files that other commands will later operate on.* Committing changes:: Checking in your modifications to the CVS repository. * Editing files:: Loading files into Emacs.* Getting info about files:: Display the log and status of files.* Adding and removing files:: Adding and removing files* Undoing changes:: Undoing changes* Removing handled entries:: Uninteresting lines can easily be removed.* Ignoring files:: Telling CVS to ignore generated files.* Viewing differences:: Commands to @samp{diff} different versions.* Invoking Ediff:: Running @samp{ediff} from @samp{*cvs*} buffer.* Updating files:: Updating files that Need-update.* Tagging files:: Tagging files.* Miscellaneous commands:: Miscellaneous commands.@end menu@node Entering PCL-CVS, Setting flags, Commands, Commands@section Entering PCL-CVS@findex cvs-update@findex cvs-examine@findex cvs-status@findex cvs-checkout@findex cvs-quickdir@cindex Creating the *cvs* bufferMost commands in PCL-CVS require that you have a @samp{*cvs*}buffer. The commands that you use to get one are listed below.For each, a @samp{cvs} process will be run, the output will be parsed by PCL-CVS, and the result will be printed in the @samp{*cvs*} buffer (see@ref{Buffer contents}, for a description of the buffer's contents).@table @kbd@item M-x cvs-updateRun a @samp{cvs update} command. You will be asked for the directory in which the @samp{cvs update} will be run.@item M-x cvs-examineRun a @samp{cvs -n update} command. This is identical to the previouscommand, except that it will only check what needs to be done but willnot change anything. You will be asked for the directory inwhich the @samp{cvs -n update} will be run.@item M-x cvs-statusRun a @samp{cvs status} command. You will be asked for the directory in which the @samp{cvs status} will be run.@item M-x cvs-checkoutRun a @samp{cvs checkout} command. You will be asked for the directoryin which the @samp{cvs update} will be run and the module to be checkedout.@item M-x cvs-quickdirPopulate the @samp{*cvs*} buffer by just looking at the @file{CVS/Entries}files. This is very much like @code{cvs-examine} except that it doesnot access the CVS repository, which is a major advantage when therepository is far away. But of course, it will not be able to detectwhen a file needs to be updated or merged.@end table@findex cvs-dired-action@findex cvs-dired-use-hookThe first four ofthose commands are also reachable from the menu barunder @samp{Tools->PCL-CVS}. Finally, an alternative way is to visitthe CVS administrative subdirectory in your work area with a simpleprefix argument. For example @kbd{C-u C-x C-f ~/my/work/CVS @key{RET}}. Thisby default runs @code{cvs-quickdir} but the specific behavior can bechanged with @code{cvs-dired-action} and @code{cvs-dired-use-hook}.By default, the commands above will descend recursively intosubdirectories. You can avoid that behavior by including @samp{-l} inthe flags for the command. These flags can be set by giving a prefixargument to the command (e.g., by typing@kbd{C-u M-x cvs-update @key{RET} -l @key{RET}}).@node Setting flags, Updating the buffer, Entering PCL-CVS, Commands@section Setting flags for CVS commands@cindex Optional switches to CVS@cindex Command-line options to CVSThis section describes the convention used by nearly all PCL-CVScommands for setting optional flags sent to CVS. A single @kbd{C-u}prefix argument is used to cause the command to prompt for flags to beused for the current invocation of the command only. Two @kbd{C-u} prefixarguments are used to prompt for flags which will be set permanently, for thecurrent invocation and all that follow, until the flags are changed, orunless temporary flags are set which override them.Perhaps an example or two is in order. Say you are about to add abinary file to the repository, and want to specify the flags @samp{-kb}to @samp{cvs add}. You can type @kbd{C-u a -kb @key{RET}},and the file will be added. Subsequent @samp{cvs add}commands will use the previously prevailing flags.As a second example, say you are about to perform a diff and want to seethe result in unified diff format, i.e. you'd like to pass the flag@samp{-u} to both @samp{cvs diff} and @samp{diff}. You'd also like allsubsequent diffs to use this flag. You can type @kbd{C-u C-u = -u @key{RET}}and the diff will be performed, and the default flags will be set to@code{("-u")}. You can of course override this flag for a single diffby using a single @kbd{C-u} prefix argument.@cindex Special prefixIn addition to this, some commands can take @dfn{special prefix} arguments.These work as follows: When called with a @kbd{C-u} prefix, the user isprompted for a new value of the special prefix and the special prefix isactivated for the next command. When called without the @kbd{C-u}prefix, the special prefix is re-activated (with the same value as lasttime) for the next command. Calling the prefix command again when it'salready activated deactivates it. Calling it with the @kbd{C-u C-u}prefix activates it for all subsequent commands until you deactivate itexplicitly. The special prefixes are:@table @kbd@item TToggles whether or not marks will be active in the next command.@refill@item bProvide the next command with a branch (can be any versionspecifier) to work on.@refill@item BSecondary branch argument. Only meaningful if @kbd{b} is also used.It can be used to provide a second branch argument to@code{cvs-mode-diff} or to @code{cvs-mode-update}.@item M-fForces the next command to apply to every selected file rather than onlyto the ones PCL-CVS thinks are relevant.@end table@node Updating the buffer, Movement commands, Setting flags, Commands@section Updating the @samp{*cvs*} buffer@findex cvs-update@findex cvs-examine@findex cvs-status@findex cvs-mode-update@findex cvs-mode-examine@findex cvs-mode-statusThe following commands can be used from within the @samp{*cvs*} bufferto update the display:@table @kbd@item M-uRuns the command @samp{cvs-update}.@refill@item M-eRuns the command @samp{cvs-examine}.@refill@item M-sRuns the command @samp{cvs-status}.@refill@end tableIn addition to the above commands which operate on the whole module,you can run the equivalent CVS command on just a subset of thefiles/directories with these keys:@table @kbd@item ORuns @code{cvs-mode-update} on the selected files. When run on thetop-level directory, this is equivalent to @kbd{M-u}.@refill@item eRuns @code{cvs-mode-examine} on the selected files. When run on thetop-level directory, this is equivalent to @kbd{M-e}.@refill@findex cvs-status-mode@item sRuns @code{cvs-mode-status} on the selected files. When run on thetop-level directory, this is equivalent to @kbd{M-s}, except thatCVS output will be shown in a @samp{*cvs-info*} buffer that will beput in @samp{cvs-status-mode}.@refill@end table@node Movement commands, Marking files, Updating the buffer, Commands@section Movement Commands@cindex Movement Commands@findex cvs-mode-next-line@findex cvs-mode-previous-line@kindex SPC@r{--Move down one file}@kindex n@r{--Move down one file}@kindex p@r{--Move up one file}You can use most normal Emacs commands to move forward and backward inthe buffer. Some keys are rebound to functions that take advantage ofthe fact that the buffer is a PCL-CVS buffer:@table @kbd@item @key{SPC}@itemx nThese keys move the cursor one file forward, towards the end of thebuffer (@code{cvs-mode-next-line}).@refill@itemx pThis key moves one file backward, towards the beginning of the buffer(@code{cvs-mode-previous-line}).@end table@node Marking files, Committing changes, Movement commands, Commands@section Marking files@cindex Selecting files (commands to mark files)@cindex Marking files@kindex m@r{--marking a file}@kindex M@r{--marking all files}@kindex u@r{--unmark a file}@kindex ESC DEL@r{--unmark all files}@kindex DEL@r{--unmark previous file}@kindex %@r{--mark files matching regexp}@kindex S@r{--mark files in a particular state}@kindex T@r{--toggle marks}@findex cvs-mode-mark@findex cvs-mode-unmark@findex cvs-mode-mark-all-files@findex cvs-mode-unmark-all-files@findex cvs-mode-unmark-up@findex cvs-mode-mark-matching-files@findex cvs-mode-mark-on-state@findex cvs-mode-toggle-marksPCL-CVS works on a set of @dfn{selected files} (@pxref{Selected files}).You can mark and unmark files with these commands:@table @kbd@item mThis marks the file that the cursor is positioned on. If the cursor ispositioned on a directory all files in that directory are marked.(@code{cvs-mode-mark}).@refill@item uUnmark the file that the cursor is positioned on. If the cursor is on adirectory, all files in that directory are unmarked.(@code{cvs-mode-unmark}).@refill@item MMark @emph{all} files in the buffer (@code{cvs-mode-mark-all-files}).@item M-@key{DEL}Unmark @emph{all} files (@code{cvs-mode-unmark-all-files}).@item @key{DEL}Unmark the file on the previous line, and move point to that line(@code{cvs-mode-unmark-up}).@item %Mark all files matching a regular expression(@code{cvs-mode-mark-matching-files}).@item SMark all files in a particular state, such as ``Modified'' or``Removed''. (@code{cvs-mode-mark-on-state}).@item TToggle use of marks for the next command (@code{cvs-mode-toggle-marks}).@end table@node Committing changes, Editing files, Marking files, Commands@section Committing changes@cindex Committing changes@findex cvs-mode-commit@findex cvs-mode-commit-setup@kindex c@r{--commit files}@kindex C@r{--commit files with @file{ChangeLog} message}@vindex cvs-auto-revert@r{ (variable)}@cindex Commit buffer@cindex Edit buffer@cindex Erasing commit message@cindex Reverting buffers after commitCommitting changes basically works as follows:@enumerate@itemAfter having selected the files you want to commit, you type either@kbd{c} or @kbd{C} which brings up a special buffer@samp{*cvs-commit*}.@refill@itemYou type in the log message describing the changes you're about tocommit (@pxref{Log Edit Mode}).@itemWhen you're happy with it, you type @kbd{C-c C-c} to do the actualcommit.@refill@end enumerateThere's no hidden state, so you can abort the process or pick it upagain at any time.@vindex log-edit-confirm@r{ (variable)}The set of files actually committed is really decided only during thevery last step, which is a mixed blessing. It allows you to go back andchange your mind about which files to commit, but it also means that youmight inadvertently change the set of selected files. To reduce therisk of error, @kbd{C-c C-c} will ask for confirmation if the set ofselected files has changed between the first step and the last. You canchange this last detail with @code{log-edit-confirm}.As for the difference between @kbd{c} (i.e. @code{cvs-mode-commit}) and@kbd{C} (i.e. @code{cvs-mode-commit-setup}) is that the first gets youstraight to @samp{*cvs-commit*} without erasing it or changing anythingto its content, while the second first erases @samp{*cvs-commit*}and tries to initialize it with a sane default (it does that by eitherusing a template provided by the CVS administrator or by extracting arelevant log message from a @file{ChangeLog} file).If you are editing the files in your Emacs, an automatic@samp{revert-buffer} will be performed. (If the file contains@samp{$@asis{Id}$} keywords, @samp{cvs commit} will write a new file withthe new values substituted. The auto-revert makes sure that you getthem into your buffer). The revert will not occur if you have modifiedyour buffer, or if @samp{cvs-auto-revert} is set to@samp{nil}.@node Editing files, Getting info about files, Committing changes, Commands@section Editing files@cindex Editing files@cindex Finding files@cindex Loading files@cindex Dired@cindex Invoking dired@findex cvs-mode-find-file@findex cvs-mode-find-file-other-window@findex cvs-mode-add-change-log-entry-other-window@kindex f@r{--find file or directory}@kindex o@r{--find file in other window}@kindex A@r{--add @file{ChangeLog} entry}There are currently three commands that can be used to find a file (thatis, load it into a buffer and start editing it there). These commandswork on the line that the cursor is situated at. They always ignore any markedfiles.@table @kbd@item fFind the file that the cursor points to (@code{cvs-mode-find-file}). Ifthe cursor points to a directory, run @code{dired} on that directory;@inforef{Dired, , emacs}.@item oLike @kbd{f}, but use another window(@code{cvs-mode-find-file-other-window}).@refill@item AInvoke @samp{add-change-log-entry-other-window} to edit a@file{ChangeLog} file. The @file{ChangeLog} file will be found in thedirectory of the file the cursor points to, or in a parent of thatdirectory. (@code{cvs-mode-add-change-log-entry-other-window}).@refill@end table@node Getting info about files, Adding and removing files, Editing files, Commands@section Getting info about files@cindex Status (cvs command)@cindex Log (RCS/cvs command)@cindex Getting status@kindex l@r{--run @samp{cvs log}}@kindex s@r{--run @samp{cvs status}}@findex cvs-mode-log@findex cvs-mode-status@table @kbd@item lCall the command @code{cvs-mode-log} which runs @samp{cvs log} on allselected files, and show the result in a temporary buffer@samp{*cvs-info*} (@pxref{Log View Mode}).@item sCall the command @code{cvs-mode-status} which runs @samp{cvs status} onall selected files, and show the result in a temporary buffer@samp{*cvs-info*}.@c Fixme: reinstate when node is written:@c (@pxref{CVS Status Mode}).@end table@node Adding and removing files, Undoing changes, Getting info about files, Commands@section Adding and removing files@cindex Adding files@cindex Removing files@cindex Resurrecting files@cindex Deleting files@cindex Putting files under CVS control@kindex a@r{--add a file}@kindex r@r{--remove a file}@findex cvs-mode-add@findex cvs-mode-remove-fileThe following commands are available to make it easy to add fuiles toand remove them from the CVS repository.@table @kbd@item aAdd all selected files. This command can be used on @samp{Unknown}files (@pxref{Buffer contents}). The status of the file will change to@samp{Added}, and you will have to use @kbd{c} (@samp{cvs-mode-commit}@pxref{Committing changes}), to really add the file to therepository.@refillThis command can also be used on @samp{Removed} files (before you committhem) to resurrect them.The command that is run is @code{cvs-mode-add}.@item rThis command removes the selected files (after prompting forconfirmation). The files are deleted from your directory and(unless the status was @samp{Unknown}; @pxref{Buffer contents}) they willalso be @samp{cvs remove}d. If the files' status was @samp{Unknown}they will disappear from the buffer. Otherwise their status will change to@samp{Removed}, and you must use @kbd{c} (@samp{cvs-mode-commit},@pxref{Committing changes}) to commit the removal.@refillThe command that is run is @code{cvs-mode-remove-file}.@end table@node Undoing changes, Removing handled entries, Adding and removing files, Commands@section Undoing changes@cindex Undo changes@cindex Flush changes@kindex U@r{--undo changes}@findex cvs-mode-undo-local-changes@table @kbd@item UIf you have modified a file, and for some reason decide that you don'twant to keep the changes, you can undo them with this command. It worksby removing your working copy of the file and then getting the latestversion from the repository (@code{cvs-mode-undo-local-changes}.@end table@node Removing handled entries, Ignoring files, Undoing changes, Commands@section Removing handled entries@cindex Expunging uninteresting entries@cindex Uninteresting entries, getting rid of them@cindex Getting rid of uninteresting lines@cindex Removing uninteresting (processed) lines@cindex Handled lines, removing them@kindex x@r{--remove processed entries}@kindex C-k@r{--remove selected entries}@findex cvs-mode-remove-handled@findex cvs-mode-acknowledge@findex cvs-mode-ignore@table @kbd@item xThis command allows you to remove all entries that you have processed.More specifically, the lines for @samp{Up-to-date} files (@pxref{Buffercontents}) are removed from the buffer. If a directory becomes emptythe heading for that directory is also removed. This makes it easier toget an overview of what needs to be done.@vindex cvs-mode-remove-handled@r{ (variable)}@kbd{x} invokes @code{cvs-mode-remove-handled}. If@samp{cvs-auto-remove-handled} is set to non-@code{nil}, this willautomatically be performed after every commit.@refill@item C-kThis command can be used for lines that @samp{cvs-mode-remove-handled} wouldnot delete, but that you want to delete (@code{cvs-mode-acknowledge}).@end table@node Ignoring files, Viewing differences, Removing handled entries, Commands@section Ignoring files@cindex Ignoring files@kindex i@r{--ignoring files}@findex cvs-mode-ignore@table @kbd@item iArrange so that CVS will ignore the selected files. The file names areadded to the @file{.cvsignore} file in the corresponding directory. Ifthe @file{.cvsignore} file doesn't exist, it will be created.The @file{.cvsignore} file should normally be added to the repository,but you could ignore it as well, if you like it better that way.This runs @code{cvs-mode-ignore}.@end table@node Viewing differences, Invoking Ediff, Ignoring files, Commands@section Viewing differences@cindex Diff@cindex Invoking @code{diff}@cindex Conflicts, how to resolve them@cindex Viewing differences@kindex d=@r{--run @samp{cvs diff}}@kindex =@r{--run @samp{cvs diff}}@kindex db@r{--diff against base version}@kindex dh@r{--diff against head of repository}@kindex dv@r{--diff against vendor branch}@findex cvs-mode-diff@findex cvs-mode-diff-backup@findex cvs-mode-diff-head@findex cvs-mode-diff-vendor@vindex cvs-invert-ignore-marks@r{ (variable)}@table @kbd@item =@itemx d =Display a @samp{cvs diff} between the selected files and the versionthat they are based on. (@code{cvs-mode-diff}).@refill@item d bIf CVS finds a conflict while merging two versions of a file (during a@samp{cvs update}, @pxref{Updating the buffer}) it will save theoriginal file in a file called @file{.#@var{file}.@var{version}} where@var{file} is the name of the file, and @var{version} is the revisionnumber that @var{file} was based on.@refillWith the @kbd{d b} command you can run a @samp{diff} on the files@file{.#@var{file}.@var{version}} and @file{@var{file}}.@refill@item d hDisplay a @samp{cvs diff} between the selected files and the headrevision in the repository (the most recent version on the currentbranch) (@code{cvs-mode-diff-head}).@refill@item d vDisplay a @samp{cvs diff} between the selected files and the headrevision of the vendor branch in the repository.(@code{cvs-mode-diff-vendor}).@refill@end tableBy default, @samp{diff} commands ignore the marks. This can be changedwith @code{cvs-invert-ignore-marks}.@node Invoking Ediff, Updating files, Viewing differences, Commands@section Running ediff@cindex Ediff@cindex Invoking ediff@cindex Viewing differences@cindex Conflicts, how to resolve them@cindex Resolving conflicts@kindex e@r{--invoke @samp{ediff}}@findex cvs-mode-idiff@findex cvs-mode-imerge@table @kbd@vindex cvs-idiff-imerge-handlers@r{ (variable)}@item d eThis uses @code{ediff} (or @code{emerge}, depending on@samp{cvs-idiff-imerge-handlers}) to allow you to view diffs.If a prefix argument is given, PCL-CVS will prompt for a revision againstwhich the diff should be made, else the default will be to use the BASErevision.@cindex Merging with @code{ediff} and @code{emerge}@item d EThis command use @code{ediff} (or @code{emerge}, see above) to allow youto do an interactive 3-way merge.@strong{Note:} When the file status is @samp{Conflict},CVS has already performed a merge. The resulting file is not used inany way if you use this command. If you use the @kbd{q} command inside@samp{ediff} (to successfully terminate a merge) the file that CVScreated will be overwritten.@refill@end table@node Updating files, Tagging files, Invoking Ediff, Commands@section Updating files@findex cvs-mode-update@cindex Updating files@kindex O@r{--update files}@table @kbd@item OUpdate all selected files with status @samp{Need-update} by running@samp{cvs update} on them. (@code{cvs-mode-update}).@end table@node Tagging files, Miscellaneous commands, Updating files, Commands@section Tagging files@findex cvs-mode-tag@findex cvs-mode-untag@findex cvs-rtag@cindex Tagging files@kindex M-t@r{--repository tag files}@kindex t@r{--tag files}@vindex cvs-invert-ignore-marks@r{ (variable)}@vindex cvs-force-dir-tag@r{ (variable)}@table @kbd@item tTag all selected files by running @samp{cvs tag} onthem (@code{cvs-mode-tag}). It's usually preferable to tag a directoryat a time. Rather than selecting all files (which too often doesn'tselect all files but only the few that are displayed), clear theselection with @kbd{M-DEL} (@code{cvs-mode-unmark-all-files}), positionthe cursor on the directory you want to tag and hit @kbd{t}.@end tableBy default, @samp{tag} commands ignore the marks. This can be changedwith @code{cvs-invert-ignore-marks}. Also, by default @samp{tag} canonly be applied to directories, see @code{cvs-force-dir-tag} if you wantto change this behavior.@node Miscellaneous commands, , Tagging files, Commands@section Miscellaneous commands@findex cvs-mode-byte-compile-files@cindex Recompiling elisp files@cindex Byte compilation@findex cvs-mode-delete-lock@cindex Getting rid of lock files@cindex Lock files@kindex q@r{--quit PCL-CVS}@findex cvs-mode-quit@cindex Quitting@kindex h@r{--help}@kindex ?@r{--help}@findex cvs-help@cindex Help@table @kbd@item M-x cvs-mode-byte-compile-filesByte compile all selected files that end in @file{.el}.@item M-x cvs-mode-delete-lockThis command deletes the lock files thatthe @samp{*cvs*} buffer informs you about. You should normally never have touse this command, since CVS tries very carefully to always remove thelock files itself.You can only use this command when a message in the @samp{*cvs*} buffer tellsyou so. You should wait a while before using this command in casesomeone else is running a @code{cvs} command.Also note that this only works if the repository is local.@item ?@itemx hShow a summary of common command key bindings in the echoarea (@code{cvs-help}).@item qQuit PCL-CVS, killing the @samp{*cvs*} buffer (@code{cvs-mode-quit}).@end table@node Log Edit Mode, Log View Mode, Commands, Top@chapter Editing a Log Message@cindex Log Edit mode@cindex mode, Log EditBuffers for entering/editing log messages for changes which are aboutto be committed are put into Log Edit mode.Sometimes the log buffer contains default text when you enter it,typically the last log message entered. If it does, mark and pointare set around the entire contents of the buffer so that it is easy tokill the contents of the buffer with @kbd{C-w}.@findex log-edit-insert-changelogIf you work by writing entries in the @file{ChangeLog}(@pxref{(emacs)Change Log}) and then commit the change under revisioncontrol, you can generate the Log Edit text from the ChangeLog using@kbd{C-a C-a} (@kbd{log-edit-insert-changelog}). This looks forentries for the file(s) concerned in the top entry in the ChangeLogand uses those paragraphs as the log text. This text is only insertedif the top entry was made under your user name on the current date.@xref{(emacs)Change Logs and VC}, for the opposite way ofworking---generating ChangeLog entries from the revision control log.In the Log Edit buffer, @kbd{C-c C-f} (@kbd{M-x log-edit-show-files})shows the list of files to be committed in case you need to checkthat.When you have finished editing the log message, type @kbd{C-c C-c} toexit the buffer and commit the change.@c Fixme: customization variables@node Log View Mode, Customization, Log Edit Mode, Top@chapter Browsing a Log of Changes@cindex Log View mode@cindex mode, Log View@cindex output, logs@findex cvs-mode-log@findex vc-print-logLog View mode provides a few useful commands for navigating revisioncontrol log output. It is used for the output buffers of both@code{cvs-mode-log} and @code{vc-print-log}.In this mode, @kbd{n} goes to the next message and @kbd{p} goes to theprevious message and @kbd{N} and @kbd{P} go to the next and previousfiles, respectively, in multi-file output. With a numeric prefixargument, these commands move that many messages of files.@c @node CVS Status Mode@c @chapter Viewing CVS' Status output@node Customization, Bugs, Log View Mode, Top@chapter Customization@vindex log-edit-changelog-full-paragraphs@r{ (variable)}@vindex cvs-auto-remove-handled@r{ (variable)}@vindex cvs-auto-remove-directories@r{ (variable)}@vindex cvs-update-prog-output-skip-regexp@r{ (variable)}@vindex cvs-cvsroot@r{ (variable)}@vindex cvs-auto-revert@r{ (variable)}@vindex log-edit-require-final-newline@r{ (variable)}@vindex cvs-sort-ignore-file@r{ (variable)}@cindex Customization@cindex Variables, list of all@cindex Erasing input buffer@cindex Context diff, how to get@cindex Unidiff, how to get@cindex Automatically remove handled files@cindex @samp{-u} option in modules file@cindex Modules file (@samp{-u} option)@cindex Update program (@samp{-u} option in modules file)@cindex Reverting buffers after commit@cindex Require final newline@cindex Automatically inserting newline@cindex Commit message, inserting newline@cindex Sorting @file{.cvsignore} file@cindex @file{.cvsignore} file, sorting@cindex Automatically sorting @file{.cvsignore}@cindex @samp{CVSROOT}, overridingIf you have an idea about any customization that would be handy butisn't present in this list, please tell me!For info on how to reach me, see @ref{Bugs}.@refill@table @samp@item cvs-auto-remove-handledIf this variable is set to any non-@code{nil} value,@samp{cvs-mode-remove-handled} will be called every time you check infiles, after the check-in is ready. @xref{Removing handledentries}.@refill@item cvs-auto-remove-directoriesIf this variable is set to any non-@code{nil} value, directories that donot contain any files to be checked in will not be listed in the@samp{*cvs*} buffer.@refill@item cvs-auto-revertIf this variable is set to any non-@samp{nil} value any buffers you havethat visit a file that is committed will be automatically reverted.This variable defaults to @samp{t}. @xref{Committing changes}.@refill@item cvs-update-prog-output-skip-regexpThe @samp{-u} flag in the @file{modules} file can be used to run a commandwhenever a @samp{cvs update} is performed (see @code{cvs(5)}). This regexpis used to search for the last line in that output. It is normally setto @samp{$}. That setting is only correct if the command outputsnothing. Note that PCL-CVS will get very confused if the commandoutputs @emph{anything} to @code{stderr}.@item cvs-cvsrootThis variable can be set to override @samp{CVSROOT}. It should be astring. If it is set, then every time a @code{cvs} command is run, itwill be called as @samp{cvs -d @var{cvs-cvsroot}@dots{}}. This can beuseful if your site has several repositories.@item log-edit-require-final-newline@c wordy to avoid unhderfull hboxWhen you enter a log message by typing into the@samp{*cvs-commit-message*} buffer, PCL-CVS normally automaticallyinserts a trailing newline, unless there already is one. This behaviorcan be controlled via @samp{cvs-commit-buffer-require-final-newline}.If it is @samp{t} (the default behavior), a newline will always beappended. If it is @samp{nil}, newlines will never be appended. Anyother value causes PCL-CVS to ask the user whenever there is no trailingnewline in the commit message buffer.@findex cvs-mode-changelog-commit@item log-edit-changelog-full-paragraphsIf this variable is non-@code{nil}, include full @file{ChangeLog}paragraphs in the CVS log created by @samp{cvs-mode-changelog-commit}. This may be set in the local variables section of a @file{ChangeLog}file, to indicate the policy for that @file{ChangeLog}.@cindex @file{ChangeLog} paragraphsA @dfn{@file{ChangeLog} paragraph} is a bunch of log text containing noblank lines; a paragraph usually describes a set of changes with asingle purpose, but perhaps spanning several functions in several files.Changes in different paragraphs are unrelated.You could argue that the CVS log entry for a file should contain thefull @file{ChangeLog} paragraph mentioning the change to the file, even thoughit may mention other files, because that gives you the full context youneed to understand the change. This is the behavior you get when thisvariable is set to @code{t}, the default.On the other hand, you could argue that the CVS log entry for a changeshould contain only the text for the changes which occurred in thatfile, because the CVS log is per-file. This is the behavior you getwhen this variable is set to @code{nil}.@findex cvs-mode-ignore@r{, and @file{.cvsignore} sorting}@item cvs-sort-ignore-fileIf this variable is set to any non-@samp{nil} value, the@file{.cvsignore} file will always be sorted whenever you use@samp{cvs-mode-ignore} to add a file to it. This option is on bydefault.@end table@menu* Customizing Faces:: @end menu@node Customizing Faces, , Customization, Customization@section Customizing Faces@vindex cvs-header-face (face)@vindex cvs-filename-face (face)@vindex cvs-unknown-face (face)@vindex cvs-handled-face (face)@vindex cvs-need-action-face (face)@vindex cvs-marked-face (face)PCL-CVS adds a few extra features, including menus, mouse bindings, andfontification the @samp{*cvs*} buffer. The faces defined forfontification are listed below:@table @samp@item cvs-header-faceused to highlight directory changes.@item cvs-filename-faceused to highlight file names.@item cvs-unknown-faceused to highlight the status of files which are @samp{Unknown}.@item cvs-handled-faceused to highlight the status of files which are handled and need no further action.@item cvs-need-action-faceused to highlight the status of files which still need action.@item cvs-marked-faceused to highlight the marked file indicator (@samp{*}).@end table@node Bugs, Function and Variable Index, Customization, Top@chapter Bugs (known and unknown)@cindex Reporting bugs and ideas@cindex Bugs, how to report them@cindex Author, how to reach@cindex Email to the author@cindex Known bugs@cindex Bugs, known@cindex FAQ@cindex Problems, list of commonIf you find a bug or misfeature, don't hesitate to tell us! Send emailto @email{bug-gnu-emacs@@gnu.org} which is gatewayed to the newsgroup@samp{gnu.emacs.bugs}. Feature requests should also be sent there. Weprefer discussing one thing at a time. If you find several unrelatedbugs, please report them separately. If you are running PCL-CVS underXEmacs, you should also send a copy of bug reports to@email{xemacs-beta@@xemacs.org}.If you have problems using PCL-CVS or other questions, send them to@email{help-gnu-emacs@@gnu.org}, which is gatewayed to the@samp{gnu.emacs.help} newsgroup. This is a good place to get help, asis @email{cvs-info@@gnu.org}, gatewayed to @samp{gnu.cvs.help}.If you have ideas for improvements, or if you have written someextensions to this package, we would like to hear from you. We hope thatyou find this package useful!Below is a partial list of currently known problems with PCL-CVS.@table @asis@item Unexpected output from CVSUnexpected output from CVS may confuse PCL-CVS. It will createwarning messages in the @samp{*cvs*} buffer alerting you to any parse errors.If you get these messages, please send a bug report to the emailaddresses listed above. Include the contents of the @samp{*cvs*} buffer, theoutput of the CVS process (which should be found in the @samp{ *cvs-tmp*}buffer), and the versions of Emacs, PCL-CVS and CVS you are using.@end table@node Function and Variable Index, Concept Index, Bugs, Top@unnumbered Function and Variable IndexThis is an index of all the functions and variables documented in thismanual.@printindex fn@node Concept Index, Key Index, Function and Variable Index, Top@unnumbered Concept IndexThis is an index of concepts discussed in this manual.@printindex cp@node Key Index, , Concept Index, Top@unnumbered Key IndexThis index includes an entry for each PCL-CVS key sequence documented inthis manual.@printindex ky@setchapternewpage odd@summarycontents@contents@bye