1 \input texinfo @c -*-texinfo-*-
3 @setfilename ../../info/pcl-cvs
4 @settitle PCL-CVS --- Emacs Front-End to CVS
9 Copyright @copyright{} 1991, 1992, 1993, 1994, 1995, 1996, 1997, 1998,
10 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008
11 Free Software Foundation, Inc.
14 Permission is granted to copy, distribute and/or modify this document
15 under the terms of the GNU Free Documentation License, Version 1.2 or
16 any later version published by the Free Software Foundation; with no
17 Invariant Sections, with the Front-Cover texts being ``A GNU Manual'',
18 and with the Back-Cover Texts as in (a) below. A copy of the license
19 is included in the section entitled ``GNU Free Documentation License''.
21 (a) The FSF's Back-Cover Text is: ``You have the freedom to copy and
22 modify this GNU manual. Buying copies from the FSF supports it in
23 developing GNU and promoting software freedom.''
29 * PCL-CVS: (pcl-cvs). Emacs front-end to CVS.
32 @c The titlepage section does not appear in the Info file.
35 @c The title is printed in a large font.
36 @center @titlefont{User's Guide}
38 @center @titlefont{to}
40 @center @titlefont{PCL-CVS --- The Emacs Front-End to CVS}
47 @center Per Cederqvist
48 @center Stefan Monnier
51 @c The following two commands start the copyright page
52 @c for the printed manual. This will not appear in the Info file.
54 @vskip 0pt plus 1filll
58 @c ================================================================
59 @c The real text starts here
60 @c ================================================================
62 @node Top, About PCL-CVS, (dir), (dir)
66 This manual describes PCL-CVS, the GNU Emacs front-end to CVS. It
67 is nowhere near complete, so you are advised to use @kbd{M-x
68 customize-group RET pcl-cvs @key{RET}} and to look at the documentation strings
69 of the various commands and major modes for further information.
70 @c This manual is updated to release 2.5 of PCL-CVS.
74 * About PCL-CVS:: Credits, history, @dots{}
76 * Getting started:: An introduction with a walk-through example.
77 * Buffer contents:: An explanation of the buffer contents.
78 * Selected files:: To which files are commands applied.
79 * Commands:: All commands, grouped by type.
81 * Log Edit Mode:: Major mode to edit log messages.
82 * Log View Mode:: Major mode to browse log changes.
83 @c * CVS Status Mode:: Major mode to view CVS' status output.
84 * Customization:: How you can tailor PCL-CVS to suit your needs.
85 * Bugs:: Bugs (known and unknown).
87 * GNU Free Documentation License:: The license for this documentation.
88 * Function and Variable Index:: List of functions and variables.
89 * Concept Index:: List of concepts.
90 * Key Index:: List of keystrokes.
93 --- The Detailed Node Listing ---
97 * Contributors:: Contributors to PCL-CVS.
101 * Entering PCL-CVS:: Commands to invoke PCL-CVS
102 * Setting flags:: Setting flags for CVS commands
103 * Updating the buffer::
104 * Movement commands:: How to move up and down in the buffer
105 * Marking files:: How to mark files that other commands
106 will later operate on.
107 * Committing changes:: Checking in your modifications to the
109 * Editing files:: Loading files into Emacs.
110 * Getting info about files:: Display the log and status of files.
111 * Adding and removing files:: Adding and removing files
112 * Undoing changes:: Undoing changes
113 * Removing handled entries:: Uninteresting lines can easily be removed.
114 * Ignoring files:: Telling CVS to ignore generated files.
115 * Viewing differences:: Commands to @samp{diff} different versions.
116 * Invoking Ediff:: Running @samp{ediff} from @samp{*cvs*} buffer.
117 * Updating files:: Updating files that Need-update.
118 * Tagging files:: Tagging files.
119 * Miscellaneous commands:: Miscellaneous commands.
123 * Customizing Faces::
128 @node About PCL-CVS, Getting started, Top, Top
129 @chapter About PCL-CVS
130 @cindex About PCL-CVS
132 PCL-CVS is a front-end to CVS versions 1.9 and later.
133 It concisely shows the present status of a checked out module in an
134 Emacs buffer and provides single-key access to the most frequently used CVS
136 For Emacs users accustomed to VC, PCL-CVS can be thought of as a replacement
137 for VC-dired (@pxref{VC Dired Mode, , Dired under VC, emacs, The GNU
138 Emacs Manual}) specifically designed for CVS.
140 PCL-CVS was originally written many years ago by Per Cederqvist who
141 proudly maintained it until January 1996, at which point he released the
142 beta version 2.0b2 and passed on the maintainership to Greg A Woods.
143 Development stayed mostly dormant for a few years during which
144 version 2.0 never seemed to be able to leave the ``beta'' stage while a
145 separate XEmacs version was slowly splitting away. In late 1998,
146 Stefan Monnier picked up development again, adding some major new
147 functionality and taking over the maintenance.
150 * Contributors:: Contributors to PCL-CVS.
153 @node Contributors,, About PCL-CVS, About PCL-CVS
154 @section Contributors to PCL-CVS
158 Contributions to the package are welcome. I have limited time to work
159 on this project, but I will gladly add any code that you contribute to
160 me to this package (@pxref{Bugs}).
162 The following persons have made contributions to PCL-CVS.
166 Brian Berliner wrote CVS, together with some other contributors.
167 Without his work on CVS this package would be useless@dots{}
170 Per Cederqvist wrote most of the otherwise unattributed functions in
171 PCL-CVS as well as all the documentation.
174 @email{inge@@lysator.liu.se, Inge Wallin} wrote the skeleton of
175 @file{pcl-cvs.texi}, and gave useful comments on it. He also wrote
176 the files @file{elib-node.el} and @file{compile-all.el}. The file
177 @file{cookie.el} was inspired by Inge.@refill
180 @email{linus@@lysator.liu.se, Linus Tolke} contributed useful comments
181 on both the functionality and the documentation.@refill
184 @email{jwz@@jwz.com, Jamie Zawinski} contributed
185 @file{pcl-cvs-lucid.el}, which was later renamed to
186 @file{pcl-cvs-xemacs.el}.@refill
189 Leif Lonnblad contributed RCVS support (since superseded by the new
193 @email{jimb@@cyclic.com, Jim Blandy} contributed hooks to automatically
194 guess CVS log entries from @file{ChangeLog} contents, and initial support of
195 the new Cygnus / Cyclic remote CVS, as well as various sundry bug fixes
199 @email{kingdon@@cyclic.com, Jim Kingdon} contributed lots of fixes to
200 the build and installation procedure.
203 @email{woods@@weird.com, Greg A.@: Woods} contributed code to implement
204 the use of per-file diff buffers, and vendor join diffs with emerge and
205 ediff, as well as various and sundry bug fixes and cleanups.
208 @email{greg.klanderman@@alum.mit.edu, Greg Klanderman} implemented
209 toggling of marked files, setting of CVS command flags via prefix
210 arguments, updated the XEmacs support, updated the manual, and fixed
214 @email{monnier@@gnu.org, Stefan Monnier} added a slew of other
215 features and introduced even more new bugs. If there's any bug left,
216 you can be sure it's his.
219 @c wordy to avoid an underfull hbox
220 @email{masata-y@@is.aist-nara.ac.jp, Masatake YAMATO} made a gracious
221 contribution of his cvstree code to display a tree of tags which was later
222 superseded by the new @code{cvs-status-mode}.
225 Apart from these, a lot of people have sent us suggestions, ideas,
226 requests, bug reports and encouragement. Thanks a lot! Without you
227 there would be no new releases of PCL-CVS.
230 @node Getting started, Buffer contents, About PCL-CVS, Top
231 @chapter Getting started
234 @cindex Sample session
236 This document assumes that you know what CVS is, and that you at least
237 know the fundamental concepts of CVS. If that is not the case, you
238 should read the CVS documentation. Type @kbd{info -f cvs} or @kbd{man
241 PCL-CVS is only useful once you have checked out a module. So before
242 you invoke it, you must have a copy of a module somewhere in the file
245 You can invoke PCL-CVS by typing @kbd{M-x cvs-examine @key{RET}}.
246 You can also invoke it via the menu bar, under @samp{Tools}.
247 Or, if you prefer, you can also invoke PCL-CVS by simply visiting the
248 CVS administrative subdirectory of your module, with a prefix argument.
249 For example, to invoke PCL-CVS in a separate frame, type @kbd{C-u C-x 5
250 f ~/my/project/CVS @key{RET}}.
252 The function @code{cvs-examine} will ask for a directory. The command
253 @samp{cvs -n update} will be run in that directory. (It should contain
254 files that have been checked out from a CVS archive.) The output from
255 @code{cvs} will be parsed and presented in a table in a buffer called
256 @samp{*cvs*}. It might look something like this:
259 Repository : /usr/CVSroot
261 Working dir: /users/ceder/FOO/test
272 --------------------- End ---------------------
273 -- last cmd: cvs -f -z6 -n update -d -P --
276 In this example, your repository is in @file{/usr/CVSroot} and CVS has
277 been run in the directory @file{/users/ceder/FOO/test}. The three files
278 (@file{bar}, @file{file.txt} and
279 @file{newer}) that are marked with @samp{Need-Update} have been changed
280 by someone else in the CVS repository. Two files (@file{namechange}
281 and @file{sub/ChangeLog}) have been modified locally, and need to be
284 You can move the cursor up and down in the buffer with @kbd{C-n} and
285 @kbd{C-p} or @kbd{n} and @kbd{p}. If you press @kbd{c} on one of the
286 @samp{Modified} files, that file will be checked in to the CVS
287 repository. @xref{Committing changes}. You can also press @kbd{O} to
288 update any of the files that are marked @samp{Need-Update}. You can
289 also run @kbd{M-x cvs-update @key{RET}} (bound to @kbd{M-u} in the
290 @samp{*cvs*} buffer) to update all the files.@refill
292 You can then press @kbd{=} to easily get a @samp{diff} between your
293 modified file and the base version that you started from, or you can
294 press @kbd{l} to get the output from @samp{cvs log}. Many more such
295 commands are available simply by pressing a key (@pxref{Getting info
298 @node Buffer contents, Selected files, Getting started, Top
299 @chapter Buffer contents
300 @cindex Buffer contents
301 @cindex @code{*cvs*} buffer contents
303 The display contains several columns, some of which are optional.
304 These columns are, from left to right:
309 Optionally, the head revision of the file. This is the latest version
310 found in the repository. It might also contain (instead of the head
311 revision) a sub status which typically gives further information about
312 how we got to the current state, for example @samp{patched},
313 @samp{merged}, @dots{}
316 An asterisk when the file is @dfn{marked} (@pxref{Selected
320 The actual status of the file wrt the repository. See below.
323 Optionally, the base revision of the file. This is the version
324 which the copy in your working directory is based upon.
331 The @samp{file status} field can have the following values:
335 The file is modified in your working directory, and there was no
336 modification to the same file in the repository. This status can have
337 the following substatus:
341 The file was modified in your working directory, and there were
342 modifications in the repository as well, but they were merged
343 successfully, without conflict, in your working directory.@refill
347 A conflict was detected while trying to merge your changes to @var{file}
348 with changes from the repository. @var{file} (the copy in your
349 working directory) is now the output of the @code{rcsmerge} command on
350 the two versions; an unmodified copy of your file is also in your
351 working directory, with the name @file{.#@var{file}.@var{version}},
352 where @var{version} is the RCS revision that your modified file started
353 from. @xref{Viewing differences}, for more details.@refill
355 A conflict can also come from a disagreement on the existence of the file
356 rather than on its content. This case is indicated by the following
361 The file is locally removed but a new revision has been committed to
362 the repository by someone else.
365 The file is locally added and has also been added to the repository
369 The file is locally modified but someone else has removed it from the
374 The file has been added by you, but it still needs to be checked in to
375 the repository.@refill
378 The file has been removed by you, but it still needs to be checked in to
379 the repository. You can resurrect it by typing @kbd{a} (@pxref{Adding
380 and removing files}).@refill
383 A file that was detected in your directory, but that neither appears in
384 the repository, nor is present on the list of files that CVS should
388 The file is up to date with respect to the version in the repository.
389 This status can have a substatus of:
393 You have just added the file to the repository.@refill
396 The file was brought up to date with respect to the repository. This is
397 done for any file that exists in the repository but not in your source,
398 and for files that you haven't changed but are not the most recent
399 versions available in the repository.@refill
402 The file was brought up to date with respect to the remote repository by
403 way of fetching and applying a patch to the file in your source. This
404 is equivalent to @samp{updated} except that CVS decided to use a hopefully
405 more efficient method.@refill
408 You just committed the file.@refill
412 Either a newer version than the one in your source is available in the
413 repository and you have not modified your checked out version, or the
414 file exists in the repository but not in your source. Use
415 @samp{cvs-mode-update} bound to @kbd{O} to update the file.@refill
418 You have modified the checked out version of the file, and a newer
419 version is available in the repository. A merge will take place when
420 you run a @samp{cvs-update}.
423 The file has been unexpectedly removed from your working directory
424 although it has not been @samp{cvs remove}d.
427 @node Selected files, Commands, Buffer contents, Top
428 @chapter Selected files
429 @cindex Selected files
431 @cindex File selection
435 Many of the commands work on the current set of @dfn{selected} files
436 which can be either the set of marked files (if any file is marked and
437 marks are not ignored) or whichever file or directory the cursor is on.
439 If a directory is selected but the command cannot be applied to a
440 directory, then it will be applied to the set of files under this
441 directory which are in the @samp{*cvs*} buffer.
443 @findex cvs-mode-force-command
444 @findex cvs-allow-dir-commit
445 Furthermore, each command only operates on a subset of the selected
446 files, depending on whether or not the command is @dfn{applicable} to
447 each file (based on the file's status). For example,
448 @code{cvs-mode-commit} is not applicable to a file whose status is
449 @samp{Need-Update}. If it should happen that PCL-CVS guesses the
450 applicability wrong, you can override it with the special prefix
451 @code{cvs-mode-force-command} normally bound to @kbd{M-f} (and file a
452 bug report). The applicability rule can be slightly changed with
453 @code{cvs-allow-dir-commit} and @code{cvs-force-dir-tag}.
455 By default, marks are always in effect (you may change this, however, by
456 setting the variable @code{cvs-default-ignore-marks}) except for the
457 commands that @samp{tag} or @samp{diff} a file (which can be changed
458 with the variable @code{cvs-invert-ignore-marks}).
460 In addition, you may use the special prefix @code{cvs-mode-toggle-marks}
461 normally bound to @key{T} to toggle the use of marks for the following
464 This scheme might seem a little complicated, but once one gets used to
465 it, it is quite powerful.
467 For commands to mark and unmark files, see @ref{Marking files}.
469 @node Commands, Log Edit Mode, Selected files, Top
473 This chapter describes all the commands that you can use in PCL-CVS.
476 The nodes in this menu contains explanations about all the commands that
477 you can use in PCL-CVS. They are grouped together by type.
481 * Entering PCL-CVS:: Commands to invoke PCL-CVS
482 * Setting flags:: Setting flags for CVS commands
483 * Updating the buffer::
484 * Movement commands:: How to move up and down in the buffer
485 * Marking files:: How to mark files that other commands
486 will later operate on.
487 * Committing changes:: Checking in your modifications to the
489 * Editing files:: Loading files into Emacs.
490 * Getting info about files:: Display the log and status of files.
491 * Adding and removing files:: Adding and removing files
492 * Undoing changes:: Undoing changes
493 * Removing handled entries:: Uninteresting lines can easily be removed.
494 * Ignoring files:: Telling CVS to ignore generated files.
495 * Viewing differences:: Commands to @samp{diff} different versions.
496 * Invoking Ediff:: Running @samp{ediff} from @samp{*cvs*} buffer.
497 * Updating files:: Updating files that Need-update.
498 * Tagging files:: Tagging files.
499 * Miscellaneous commands:: Miscellaneous commands.
503 @node Entering PCL-CVS, Setting flags, Commands, Commands
504 @section Entering PCL-CVS
510 @cindex Creating the *cvs* buffer
512 Most commands in PCL-CVS require that you have a @samp{*cvs*}
513 buffer. The commands that you use to get one are listed below.
514 For each, a @samp{cvs} process will be run, the output will be parsed by
515 PCL-CVS, and the result will be printed in the @samp{*cvs*} buffer (see
516 @ref{Buffer contents}, for a description of the buffer's contents).
520 Run a @samp{cvs update} command. You will be asked for the directory
521 in which the @samp{cvs update} will be run.
523 @item M-x cvs-examine
524 Run a @samp{cvs -n update} command. This is identical to the previous
525 command, except that it will only check what needs to be done but will
526 not change anything. You will be asked for the directory in
527 which the @samp{cvs -n update} will be run.
530 Run a @samp{cvs status} command. You will be asked for the directory
531 in which the @samp{cvs status} will be run.
533 @item M-x cvs-checkout
534 Run a @samp{cvs checkout} command. You will be asked for the directory
535 in which the @samp{cvs update} will be run and the module to be checked
538 @item M-x cvs-quickdir
539 Populate the @samp{*cvs*} buffer by just looking at the @file{CVS/Entries}
540 files. This is very much like @code{cvs-examine} except that it does
541 not access the CVS repository, which is a major advantage when the
542 repository is far away. But of course, it will not be able to detect
543 when a file needs to be updated or merged.
546 @findex cvs-dired-action
547 @findex cvs-dired-use-hook
549 those commands are also reachable from the menu bar
550 under @samp{Tools->PCL-CVS}. Finally, an alternative way is to visit
551 the CVS administrative subdirectory in your work area with a simple
552 prefix argument. For example @kbd{C-u C-x C-f ~/my/work/CVS @key{RET}}. This
553 by default runs @code{cvs-quickdir} but the specific behavior can be
554 changed with @code{cvs-dired-action} and @code{cvs-dired-use-hook}.
556 By default, the commands above will descend recursively into
557 subdirectories. You can avoid that behavior by including @samp{-l} in
558 the flags for the command. These flags can be set by giving a prefix
559 argument to the command (e.g., by typing
560 @kbd{C-u M-x cvs-update @key{RET} -l @key{RET}}).
563 @node Setting flags, Updating the buffer, Entering PCL-CVS, Commands
564 @section Setting flags for CVS commands
565 @cindex Optional switches to CVS
566 @cindex Command-line options to CVS
568 This section describes the convention used by nearly all PCL-CVS
569 commands for setting optional flags sent to CVS. A single @kbd{C-u}
570 prefix argument is used to cause the command to prompt for flags to be
571 used for the current invocation of the command only. Two @kbd{C-u} prefix
572 arguments are used to prompt for flags which will be set permanently, for the
573 current invocation and all that follow, until the flags are changed, or
574 unless temporary flags are set which override them.
576 Perhaps an example or two is in order. Say you are about to add a
577 binary file to the repository, and want to specify the flags @samp{-kb}
578 to @samp{cvs add}. You can type @kbd{C-u a -kb @key{RET}},
579 and the file will be added. Subsequent @samp{cvs add}
580 commands will use the previously prevailing flags.
582 As a second example, say you are about to perform a diff and want to see
583 the result in unified diff format, i.e. you'd like to pass the flag
584 @samp{-u} to both @samp{cvs diff} and @samp{diff}. You'd also like all
585 subsequent diffs to use this flag. You can type @kbd{C-u C-u = -u @key{RET}}
586 and the diff will be performed, and the default flags will be set to
587 @code{("-u")}. You can of course override this flag for a single diff
588 by using a single @kbd{C-u} prefix argument.
590 @cindex Special prefix
591 In addition to this, some commands can take @dfn{special prefix} arguments.
592 These work as follows: When called with a @kbd{C-u} prefix, the user is
593 prompted for a new value of the special prefix and the special prefix is
594 activated for the next command. When called without the @kbd{C-u}
595 prefix, the special prefix is re-activated (with the same value as last
596 time) for the next command. Calling the prefix command again when it's
597 already activated deactivates it. Calling it with the @kbd{C-u C-u}
598 prefix activates it for all subsequent commands until you deactivate it
599 explicitly. The special prefixes are:
603 Toggles whether or not marks will be active in the next command.@refill
606 Provide the next command with a branch (can be any version
607 specifier) to work on.@refill
610 Secondary branch argument. Only meaningful if @kbd{b} is also used.
611 It can be used to provide a second branch argument to
612 @code{cvs-mode-diff} or to @code{cvs-mode-update}.
615 Forces the next command to apply to every selected file rather than only
616 to the ones PCL-CVS thinks are relevant.
619 @node Updating the buffer, Movement commands, Setting flags, Commands
620 @section Updating the @samp{*cvs*} buffer
624 @findex cvs-mode-update
625 @findex cvs-mode-examine
626 @findex cvs-mode-status
628 The following commands can be used from within the @samp{*cvs*} buffer
629 to update the display:
633 Runs the command @samp{cvs-update}.@refill
636 Runs the command @samp{cvs-examine}.@refill
639 Runs the command @samp{cvs-status}.@refill
642 In addition to the above commands which operate on the whole module,
643 you can run the equivalent CVS command on just a subset of the
644 files/directories with these keys:
648 Runs @code{cvs-mode-update} on the selected files. When run on the
649 top-level directory, this is equivalent to @kbd{M-u}.@refill
652 Runs @code{cvs-mode-examine} on the selected files. When run on the
653 top-level directory, this is equivalent to @kbd{M-e}.@refill
655 @findex cvs-status-mode
657 Runs @code{cvs-mode-status} on the selected files. When run on the
658 top-level directory, this is equivalent to @kbd{M-s}, except that
659 CVS output will be shown in a @samp{*cvs-info*} buffer that will be
660 put in @samp{cvs-status-mode}.@refill
664 @node Movement commands, Marking files, Updating the buffer, Commands
665 @section Movement Commands
666 @cindex Movement Commands
667 @findex cvs-mode-next-line
668 @findex cvs-mode-previous-line
669 @kindex SPC@r{--Move down one file}
670 @kindex n@r{--Move down one file}
671 @kindex p@r{--Move up one file}
673 You can use most normal Emacs commands to move forward and backward in
674 the buffer. Some keys are rebound to functions that take advantage of
675 the fact that the buffer is a PCL-CVS buffer:
681 These keys move the cursor one file forward, towards the end of the
682 buffer (@code{cvs-mode-next-line}).@refill
685 This key moves one file backward, towards the beginning of the buffer
686 (@code{cvs-mode-previous-line}).
690 @node Marking files, Committing changes, Movement commands, Commands
691 @section Marking files
692 @cindex Selecting files (commands to mark files)
693 @cindex Marking files
694 @kindex m@r{--marking a file}
695 @kindex M@r{--marking all files}
696 @kindex u@r{--unmark a file}
697 @kindex ESC DEL@r{--unmark all files}
698 @kindex DEL@r{--unmark previous file}
699 @kindex %@r{--mark files matching regexp}
700 @kindex S@r{--mark files in a particular state}
701 @kindex T@r{--toggle marks}
702 @findex cvs-mode-mark
703 @findex cvs-mode-unmark
704 @findex cvs-mode-mark-all-files
705 @findex cvs-mode-unmark-all-files
706 @findex cvs-mode-unmark-up
707 @findex cvs-mode-mark-matching-files
708 @findex cvs-mode-mark-on-state
709 @findex cvs-mode-toggle-marks
711 PCL-CVS works on a set of @dfn{selected files} (@pxref{Selected files}).
712 You can mark and unmark files with these commands:
716 This marks the file that the cursor is positioned on. If the cursor is
717 positioned on a directory all files in that directory are marked
718 (@code{cvs-mode-mark}).@refill
721 Unmark the file that the cursor is positioned on. If the cursor is on a
722 directory, all files in that directory are unmarked
723 (@code{cvs-mode-unmark}).@refill
726 Mark @emph{all} files in the buffer (@code{cvs-mode-mark-all-files}).
729 Unmark @emph{all} files (@code{cvs-mode-unmark-all-files}).
732 Unmark the file on the previous line, and move point to that line
733 (@code{cvs-mode-unmark-up}).
736 Mark all files matching a regular expression
737 (@code{cvs-mode-mark-matching-files}).
740 Mark all files in a particular state, such as ``Modified'' or
741 ``Removed'' (@code{cvs-mode-mark-on-state}).
744 Toggle use of marks for the next command (@code{cvs-mode-toggle-marks}).
748 @node Committing changes, Editing files, Marking files, Commands
749 @section Committing changes
750 @cindex Committing changes
751 @findex cvs-mode-commit
752 @findex cvs-mode-commit-setup
753 @kindex c@r{--commit files}
754 @kindex C@r{--commit files with @file{ChangeLog} message}
755 @vindex cvs-auto-revert@r{ (variable)}
756 @cindex Commit buffer
758 @cindex Erasing commit message
759 @cindex Reverting buffers after commit
761 Committing changes basically works as follows:
765 After having selected the files you want to commit, you type either
766 @kbd{c} or @kbd{C} which brings up a special buffer
767 @samp{*cvs-commit*}.@refill
770 You type in the log message describing the changes you're about to
771 commit (@pxref{Log Edit Mode}).
774 When you're happy with it, you type @kbd{C-c C-c} to do the actual
778 There's no hidden state, so you can abort the process or pick it up
781 @vindex log-edit-confirm@r{ (variable)}
782 The set of files actually committed is really decided only during the
783 very last step, which is a mixed blessing. It allows you to go back and
784 change your mind about which files to commit, but it also means that you
785 might inadvertently change the set of selected files. To reduce the
786 risk of error, @kbd{C-c C-c} will ask for confirmation if the set of
787 selected files has changed between the first step and the last. You can
788 change this last detail with @code{log-edit-confirm}.
790 As for the difference between @kbd{c} (i.e. @code{cvs-mode-commit}) and
791 @kbd{C} (i.e. @code{cvs-mode-commit-setup}) is that the first gets you
792 straight to @samp{*cvs-commit*} without erasing it or changing anything
793 to its content, while the second first erases @samp{*cvs-commit*}
794 and tries to initialize it with a sane default (it does that by either
795 using a template provided by the CVS administrator or by extracting a
796 relevant log message from a @file{ChangeLog} file).
798 If you are editing the files in your Emacs, an automatic
799 @samp{revert-buffer} will be performed. (If the file contains
800 @samp{$@asis{Id}$} keywords, @samp{cvs commit} will write a new file with
801 the new values substituted. The auto-revert makes sure that you get
802 them into your buffer.) The revert will not occur if you have modified
803 your buffer, or if @samp{cvs-auto-revert} is set to
807 @node Editing files, Getting info about files, Committing changes, Commands
808 @section Editing files
809 @cindex Editing files
810 @cindex Finding files
811 @cindex Loading files
813 @cindex Invoking dired
814 @findex cvs-mode-find-file
815 @findex cvs-mode-find-file-other-window
816 @findex cvs-mode-add-change-log-entry-other-window
817 @kindex f@r{--find file or directory}
818 @kindex o@r{--find file in other window}
819 @kindex A@r{--add @file{ChangeLog} entry}
821 There are currently three commands that can be used to find a file (that
822 is, load it into a buffer and start editing it there). These commands
823 work on the line that the cursor is situated at. They always ignore any marked
828 Find the file that the cursor points to (@code{cvs-mode-find-file}). If
829 the cursor points to a directory, run @code{dired} on that directory;
830 @inforef{Dired, , emacs}.
833 Like @kbd{f}, but use another window
834 (@code{cvs-mode-find-file-other-window}).@refill
837 Invoke @samp{add-change-log-entry-other-window} to edit a
838 @file{ChangeLog} file. The @file{ChangeLog} file will be found in the
839 directory of the file the cursor points to, or in a parent of that
840 directory (@code{cvs-mode-add-change-log-entry-other-window}).@refill
844 @node Getting info about files, Adding and removing files, Editing files, Commands
845 @section Getting info about files
846 @cindex Status (cvs command)
847 @cindex Log (RCS/cvs command)
848 @cindex Getting status
849 @kindex l@r{--run @samp{cvs log}}
850 @kindex s@r{--run @samp{cvs status}}
852 @findex cvs-mode-status
856 Call the command @code{cvs-mode-log} which runs @samp{cvs log} on all
857 selected files, and show the result in a temporary buffer
858 @samp{*cvs-info*} (@pxref{Log View Mode}).
861 Call the command @code{cvs-mode-status} which runs @samp{cvs status} on
862 all selected files, and show the result in a temporary buffer
864 @c Fixme: reinstate when node is written:
865 @c (@pxref{CVS Status Mode}).
869 @node Adding and removing files, Undoing changes, Getting info about files, Commands
870 @section Adding and removing files
872 @cindex Removing files
873 @cindex Resurrecting files
874 @cindex Deleting files
875 @cindex Putting files under CVS control
876 @kindex a@r{--add a file}
877 @kindex r@r{--remove a file}
879 @findex cvs-mode-remove-file
881 The following commands are available to make it easy to add files to
882 and remove them from the CVS repository.
886 Add all selected files. This command can be used on @samp{Unknown}
887 files (@pxref{Buffer contents}). The status of the file will change to
888 @samp{Added}, and you will have to use @kbd{c} (@samp{cvs-mode-commit}
889 @pxref{Committing changes}), to really add the file to the
892 This command can also be used on @samp{Removed} files (before you commit
893 them) to resurrect them.
895 The command that is run is @code{cvs-mode-add}.
898 This command removes the selected files (after prompting for
899 confirmation). The files are deleted from your directory and
900 (unless the status was @samp{Unknown}; @pxref{Buffer contents}) they will
901 also be @samp{cvs remove}d. If the files' status was @samp{Unknown}
902 they will disappear from the buffer. Otherwise their status will change to
903 @samp{Removed}, and you must use @kbd{c} (@samp{cvs-mode-commit},
904 @pxref{Committing changes}) to commit the removal.@refill
906 The command that is run is @code{cvs-mode-remove-file}.
910 @node Undoing changes, Removing handled entries, Adding and removing files, Commands
911 @section Undoing changes
913 @cindex Flush changes
914 @kindex U@r{--undo changes}
915 @findex cvs-mode-undo-local-changes
919 If you have modified a file, and for some reason decide that you don't
920 want to keep the changes, you can undo them with this command. It works
921 by removing your working copy of the file and then getting the latest
922 version from the repository (@code{cvs-mode-undo-local-changes}).
926 @node Removing handled entries, Ignoring files, Undoing changes, Commands
927 @section Removing handled entries
928 @cindex Expunging uninteresting entries
929 @cindex Uninteresting entries, getting rid of them
930 @cindex Getting rid of uninteresting lines
931 @cindex Removing uninteresting (processed) lines
932 @cindex Handled lines, removing them
933 @kindex x@r{--remove processed entries}
934 @kindex C-k@r{--remove selected entries}
935 @findex cvs-mode-remove-handled
936 @findex cvs-mode-acknowledge
937 @findex cvs-mode-ignore
941 This command allows you to remove all entries that you have processed.
942 More specifically, the lines for @samp{Up-to-date} files (@pxref{Buffer
943 contents}) are removed from the buffer. If a directory becomes empty
944 the heading for that directory is also removed. This makes it easier to
945 get an overview of what needs to be done.
947 @vindex cvs-mode-remove-handled@r{ (variable)}
948 @kbd{x} invokes @code{cvs-mode-remove-handled}. If
949 @samp{cvs-auto-remove-handled} is set to non-@code{nil}, this will
950 automatically be performed after every commit.@refill
953 This command can be used for lines that @samp{cvs-mode-remove-handled} would
954 not delete, but that you want to delete (@code{cvs-mode-acknowledge}).
958 @node Ignoring files, Viewing differences, Removing handled entries, Commands
959 @section Ignoring files
960 @cindex Ignoring files
961 @kindex i@r{--ignoring files}
962 @findex cvs-mode-ignore
966 Arrange so that CVS will ignore the selected files. The file names are
967 added to the @file{.cvsignore} file in the corresponding directory. If
968 the @file{.cvsignore} file doesn't exist, it will be created.
970 The @file{.cvsignore} file should normally be added to the repository,
971 but you could ignore it as well, if you like it better that way.
973 This runs @code{cvs-mode-ignore}.
976 @node Viewing differences, Invoking Ediff, Ignoring files, Commands
977 @section Viewing differences
979 @cindex Invoking @code{diff}
980 @cindex Conflicts, how to resolve them
981 @cindex Viewing differences
982 @kindex d=@r{--run @samp{cvs diff}}
983 @kindex =@r{--run @samp{cvs diff}}
984 @kindex db@r{--diff against base version}
985 @kindex dh@r{--diff against head of repository}
986 @kindex dr@r{--diff between base and head of repository}
987 @kindex dv@r{--diff against vendor branch}
988 @kindex dy@r{--diff against yesterday's head}
989 @findex cvs-mode-diff
990 @findex cvs-mode-diff-backup
991 @findex cvs-mode-diff-head
992 @findex cvs-mode-diff-repository
993 @findex cvs-mode-diff-vendor
994 @findex cvs-mode-diff-yesterday
995 @vindex cvs-invert-ignore-marks@r{ (variable)}
1000 Display a @samp{cvs diff} between the selected files and the version
1001 that they are based on (@code{cvs-mode-diff}).@refill
1004 If CVS finds a conflict while merging two versions of a file (during a
1005 @samp{cvs update}, @pxref{Updating the buffer}) it will save the
1006 original file in a file called @file{.#@var{file}.@var{version}} where
1007 @var{file} is the name of the file, and @var{version} is the revision
1008 number that @var{file} was based on.@refill
1010 With the @kbd{d b} command you can run a @samp{diff} on the files
1011 @file{.#@var{file}.@var{version}} and @file{@var{file}}.@refill
1014 Display a @samp{cvs diff} between the selected files and the head
1015 revision (the most recent version on the current
1016 branch) in the repository (@code{cvs-mode-diff-head}).@refill
1019 Display a @samp{cvs diff} between the base revision of the selected
1020 files and the head revision in the repository. This displays the
1021 changes anyone has committed to the repository since you last executed
1022 a checkout, update or commit operation
1023 (@code{cvs-mode-diff-repository}).
1026 Display a @samp{cvs diff} between the selected files and the head
1027 revision of the vendor branch in the repository
1028 (@code{cvs-mode-diff-vendor}).@refill
1031 Display a @samp{cvs diff} between the selected files and yesterday's
1032 head revision in the repository
1033 (@code{cvs-mode-diff-yesterday}).@refill
1036 By default, @samp{diff} commands ignore the marks. This can be changed
1037 with @code{cvs-invert-ignore-marks}.
1039 @node Invoking Ediff, Updating files, Viewing differences, Commands
1040 @section Running ediff
1042 @cindex Invoking ediff
1043 @cindex Viewing differences
1044 @cindex Conflicts, how to resolve them
1045 @cindex Resolving conflicts
1046 @kindex e@r{--invoke @samp{ediff}}
1047 @findex cvs-mode-idiff
1048 @findex cvs-mode-imerge
1051 @vindex cvs-idiff-imerge-handlers@r{ (variable)}
1053 This uses @code{ediff} (or @code{emerge}, depending on
1054 @samp{cvs-idiff-imerge-handlers}) to allow you to view diffs.
1055 If a prefix argument is given, PCL-CVS will prompt for a revision against
1056 which the diff should be made, else the default will be to use the BASE
1059 @cindex Merging with @code{ediff} and @code{emerge}
1061 This command use @code{ediff} (or @code{emerge}, see above) to allow you
1062 to do an interactive 3-way merge.
1064 @strong{Please note:} when the file status is @samp{Conflict},
1065 CVS has already performed a merge. The resulting file is not used in
1066 any way if you use this command. If you use the @kbd{q} command inside
1067 @samp{ediff} (to successfully terminate a merge) the file that CVS
1068 created will be overwritten.@refill
1071 @node Updating files, Tagging files, Invoking Ediff, Commands
1072 @section Updating files
1073 @findex cvs-mode-update
1074 @cindex Updating files
1075 @kindex O@r{--update files}
1079 Update all selected files with status @samp{Need-update} by running
1080 @samp{cvs update} on them (@code{cvs-mode-update}).
1084 @node Tagging files, Miscellaneous commands, Updating files, Commands
1085 @section Tagging files
1086 @findex cvs-mode-tag
1087 @findex cvs-mode-untag
1089 @cindex Tagging files
1090 @kindex M-t@r{--repository tag files}
1091 @kindex t@r{--tag files}
1092 @vindex cvs-invert-ignore-marks@r{ (variable)}
1093 @vindex cvs-force-dir-tag@r{ (variable)}
1097 Tag all selected files by running @samp{cvs tag} on
1098 them (@code{cvs-mode-tag}). It's usually preferable to tag a directory
1099 at a time. Rather than selecting all files (which too often doesn't
1100 select all files but only the few that are displayed), clear the
1101 selection with @kbd{M-DEL} (@code{cvs-mode-unmark-all-files}), position
1102 the cursor on the directory you want to tag and hit @kbd{t}.
1105 By default, @samp{tag} commands ignore the marks. This can be changed
1106 with @code{cvs-invert-ignore-marks}. Also, by default @samp{tag} can
1107 only be applied to directories, see @code{cvs-force-dir-tag} if you want
1108 to change this behavior.
1111 @node Miscellaneous commands, , Tagging files, Commands
1112 @section Miscellaneous commands
1113 @findex cvs-mode-byte-compile-files
1114 @cindex Recompiling elisp files
1115 @cindex Byte compilation
1116 @findex cvs-mode-delete-lock
1117 @cindex Getting rid of lock files
1119 @kindex q@r{--bury the PCL-CVS buffer}
1120 @findex cvs-bury-buffer
1121 @findex cvs-mode-quit
1129 @item M-x cvs-mode-byte-compile-files
1130 Byte compile all selected files that end in @file{.el}.
1132 @item M-x cvs-mode-delete-lock
1133 This command deletes the lock files that
1134 the @samp{*cvs*} buffer informs you about. You should normally never have to
1135 use this command, since CVS tries very carefully to always remove the
1138 You can only use this command when a message in the @samp{*cvs*} buffer tells
1139 you so. You should wait a while before using this command in case
1140 someone else is running a @code{cvs} command.
1142 Also note that this only works if the repository is local.
1146 Show a summary of common command key bindings in the echo
1147 area (@code{cvs-help}).
1150 Bury the PCL-CVS buffer (@code{cvs-bury-buffer}).
1152 @item M-x cvs-mode-quit
1153 Quit PCL-CVS, killing the @samp{*cvs*} buffer.
1156 @node Log Edit Mode, Log View Mode, Commands, Top
1157 @chapter Editing a Log Message
1159 @cindex Log Edit mode
1160 @cindex mode, Log Edit
1161 Buffers for entering/editing log messages for changes which are about
1162 to be committed are put into Log Edit mode.
1164 Sometimes the log buffer contains default text when you enter it,
1165 typically the last log message entered. If it does, mark and point
1166 are set around the entire contents of the buffer so that it is easy to
1167 kill the contents of the buffer with @kbd{C-w}.
1169 @findex log-edit-insert-changelog
1170 If you work by writing entries in the @file{ChangeLog}
1171 (@pxref{(emacs)Change Log}) and then commit the change under revision
1172 control, you can generate the Log Edit text from the ChangeLog using
1173 @kbd{C-c C-a} (@kbd{log-edit-insert-changelog}). This looks for
1174 entries for the file(s) concerned in the top entry in the ChangeLog
1175 and uses those paragraphs as the log text. This text is only inserted
1176 if the top entry was made under your user name on the current date.
1177 @xref{(emacs)Change Logs and VC}, for the opposite way of
1178 working---generating ChangeLog entries from the revision control log.
1180 In the Log Edit buffer, @kbd{C-c C-f} (@kbd{M-x log-edit-show-files})
1181 shows the list of files to be committed in case you need to check
1184 When you have finished editing the log message, type @kbd{C-c C-c} to
1185 exit the buffer and commit the change.
1187 @c Fixme: customization variables
1189 @node Log View Mode, Customization, Log Edit Mode, Top
1190 @chapter Browsing a Log of Changes
1192 @cindex Log View mode
1193 @cindex mode, Log View
1194 @cindex output, logs
1196 @findex cvs-mode-log
1197 @findex vc-print-log
1198 Log View mode provides a few useful commands for navigating revision
1199 control log output. It is used for the output buffers of both
1200 @code{cvs-mode-log} and @code{vc-print-log}.
1202 In this mode, @kbd{n} goes to the next message and @kbd{p} goes to the
1203 previous message and @kbd{N} and @kbd{P} go to the next and previous
1204 files, respectively, in multi-file output. With a numeric prefix
1205 argument, these commands move that many messages of files.
1207 @c @node CVS Status Mode
1208 @c @chapter Viewing CVS' Status output
1210 @node Customization, Bugs, Log View Mode, Top
1211 @chapter Customization
1212 @vindex log-edit-changelog-full-paragraphs@r{ (variable)}
1213 @vindex cvs-auto-remove-handled@r{ (variable)}
1214 @vindex cvs-auto-remove-directories@r{ (variable)}
1215 @vindex cvs-update-prog-output-skip-regexp@r{ (variable)}
1216 @vindex cvs-cvsroot@r{ (variable)}
1217 @vindex cvs-auto-revert@r{ (variable)}
1218 @vindex log-edit-require-final-newline@r{ (variable)}
1219 @vindex cvs-sort-ignore-file@r{ (variable)}
1220 @cindex Customization
1221 @cindex Variables, list of all
1222 @cindex Erasing input buffer
1223 @cindex Context diff, how to get
1224 @cindex Unidiff, how to get
1225 @cindex Automatically remove handled files
1226 @cindex @samp{-u} option in modules file
1227 @cindex Modules file (@samp{-u} option)
1228 @cindex Update program (@samp{-u} option in modules file)
1229 @cindex Reverting buffers after commit
1230 @cindex Require final newline
1231 @cindex Automatically inserting newline
1232 @cindex Commit message, inserting newline
1233 @cindex Sorting @file{.cvsignore} file
1234 @cindex @file{.cvsignore} file, sorting
1235 @cindex Automatically sorting @file{.cvsignore}
1236 @cindex @samp{CVSROOT}, overriding
1238 If you have an idea about any customization that would be handy but
1239 isn't present in this list, please tell us!
1240 For info on how to reach us, see @ref{Bugs}.@refill
1243 @item cvs-auto-remove-handled
1244 If this variable is set to any non-@code{nil} value,
1245 @samp{cvs-mode-remove-handled} will be called every time you check in
1246 files, after the check-in is ready. @xref{Removing handled
1249 @item cvs-auto-remove-directories
1250 If this variable is set to any non-@code{nil} value, directories that do
1251 not contain any files to be checked in will not be listed in the
1252 @samp{*cvs*} buffer.@refill
1254 @item cvs-auto-revert
1255 If this variable is set to any non-@samp{nil} value any buffers you have
1256 that visit a file that is committed will be automatically reverted.
1257 This variable defaults to @samp{t}. @xref{Committing changes}.@refill
1259 @item cvs-update-prog-output-skip-regexp
1260 The @samp{-u} flag in the @file{modules} file can be used to run a command
1261 whenever a @samp{cvs update} is performed (see @code{cvs(5)}). This regexp
1262 is used to search for the last line in that output. It is normally set
1263 to @samp{$}. That setting is only correct if the command outputs
1264 nothing. Note that PCL-CVS will get very confused if the command
1265 outputs @emph{anything} to @code{stderr}.
1268 This variable can be set to override @samp{CVSROOT}. It should be a
1269 string. If it is set, then every time a @code{cvs} command is run, it
1270 will be called as @samp{cvs -d @var{cvs-cvsroot}@dots{}}. This can be
1271 useful if your site has several repositories.
1273 @item log-edit-require-final-newline
1274 @c wordy to avoid unhderfull hbox
1275 When you enter a log message by typing into the
1276 @samp{*cvs-commit-message*} buffer, PCL-CVS normally automatically
1277 inserts a trailing newline, unless there already is one. This behavior
1278 can be controlled via @samp{cvs-commit-buffer-require-final-newline}.
1279 If it is @samp{t} (the default behavior), a newline will always be
1280 appended. If it is @samp{nil}, newlines will never be appended. Any
1281 other value causes PCL-CVS to ask the user whenever there is no trailing
1282 newline in the commit message buffer.
1284 @findex cvs-mode-changelog-commit
1285 @item log-edit-changelog-full-paragraphs
1286 If this variable is non-@code{nil}, include full @file{ChangeLog}
1287 paragraphs in the CVS log created by @samp{cvs-mode-changelog-commit}.
1288 This may be set in the local variables section of a @file{ChangeLog}
1289 file, to indicate the policy for that @file{ChangeLog}.
1291 @cindex @file{ChangeLog} paragraphs
1292 A @dfn{@file{ChangeLog} paragraph} is a bunch of log text containing no
1293 blank lines; a paragraph usually describes a set of changes with a
1294 single purpose, but perhaps spanning several functions in several files.
1295 Changes in different paragraphs are unrelated.
1297 You could argue that the CVS log entry for a file should contain the
1298 full @file{ChangeLog} paragraph mentioning the change to the file, even though
1299 it may mention other files, because that gives you the full context you
1300 need to understand the change. This is the behavior you get when this
1301 variable is set to @code{t}, the default.
1303 On the other hand, you could argue that the CVS log entry for a change
1304 should contain only the text for the changes which occurred in that
1305 file, because the CVS log is per-file. This is the behavior you get
1306 when this variable is set to @code{nil}.
1308 @findex cvs-mode-ignore@r{, and @file{.cvsignore} sorting}
1309 @item cvs-sort-ignore-file
1310 If this variable is set to any non-@samp{nil} value, the
1311 @file{.cvsignore} file will always be sorted whenever you use
1312 @samp{cvs-mode-ignore} to add a file to it. This option is on by
1318 * Customizing Faces::
1321 @node Customizing Faces, , Customization, Customization
1322 @section Customizing Faces
1323 @vindex cvs-header (face)
1324 @vindex cvs-filename (face)
1325 @vindex cvs-unknown (face)
1326 @vindex cvs-handled (face)
1327 @vindex cvs-need-action (face)
1328 @vindex cvs-marked (face)
1329 @vindex cvs-msg (face)
1331 PCL-CVS adds a few extra features, including menus, mouse bindings, and
1332 fontification of the @samp{*cvs*} buffer. The faces defined for
1333 fontification are listed below:
1337 used to highlight directory changes.
1340 Used to highlight file names.
1343 Used to highlight the status of files which are @samp{Unknown}.
1346 Used to highlight the status of files which are handled and
1347 need no further action.
1349 @item cvs-need-action
1350 Used to highlight the status of files which still need action.
1353 Used to highlight the marked file indicator (@samp{*}).
1356 Used to highlight CVS messages.
1360 @node Bugs, GNU Free Documentation License, Customization, Top
1361 @chapter Bugs (known and unknown)
1362 @cindex Reporting bugs and ideas
1363 @cindex Bugs, how to report them
1364 @cindex Author, how to reach
1365 @cindex Email to the author
1369 @cindex Problems, list of common
1371 If you find a bug or misfeature, don't hesitate to tell us! Send email
1372 to @email{bug-gnu-emacs@@gnu.org} which is gatewayed to the newsgroup
1373 @samp{gnu.emacs.bugs}. Feature requests should also be sent there. We
1374 prefer discussing one thing at a time. If you find several unrelated
1375 bugs, please report them separately. If you are running PCL-CVS under
1376 XEmacs, you should also send a copy of bug reports to
1377 @email{xemacs-beta@@xemacs.org}.
1379 If you have problems using PCL-CVS or other questions, send them to
1380 @email{help-gnu-emacs@@gnu.org}, which is gatewayed to the
1381 @samp{gnu.emacs.help} newsgroup. This is a good place to get help, as
1382 is @email{cvs-info@@gnu.org}, gatewayed to @samp{gnu.cvs.help}.
1384 If you have ideas for improvements, or if you have written some
1385 extensions to this package, we would like to hear from you. We hope that
1386 you find this package useful!
1388 Below is a partial list of currently known problems with PCL-CVS.
1391 @item Unexpected output from CVS
1392 Unexpected output from CVS may confuse PCL-CVS. It will create
1393 warning messages in the @samp{*cvs*} buffer alerting you to any parse errors.
1394 If you get these messages, please send a bug report to the email
1395 addresses listed above. Include the contents of the @samp{*cvs*} buffer, the
1396 output of the CVS process (which should be found in the @samp{ *cvs-tmp*}
1397 buffer), and the versions of Emacs, PCL-CVS and CVS you are using.
1400 @node GNU Free Documentation License, Function and Variable Index, Bugs, Top
1401 @appendix GNU Free Documentation License
1402 @include doclicense.texi
1406 @node Function and Variable Index, Concept Index, GNU Free Documentation License, Top
1407 @unnumbered Function and Variable Index
1409 This is an index of all the functions and variables documented in this
1414 @node Concept Index, Key Index, Function and Variable Index, Top
1415 @unnumbered Concept Index
1417 This is an index of concepts discussed in this manual.
1421 @node Key Index, , Concept Index, Top
1422 @unnumbered Key Index
1424 This index includes an entry for each PCL-CVS key sequence documented in
1429 @setchapternewpage odd
1435 arch-tag: 5c7178ce-56fa-40b0-abd7-f4a09758b235