doc/emacs/vc1-xtra.texi

   1 @c This is part of the Emacs manual.
   2 @c Copyright (C) 2004, 2005, 2006, 2007, 2008 Free Software Foundation, Inc.
   3 @c See file emacs.texi for copying conditions.
   4 @c
   5 @c This file is included either in vc-xtra.texi (when producing the
   6 @c printed version) or in the main Emacs manual (for the on-line version).
   7 @node VC Dired Mode
   8 @subsection Dired under VC
   9
  10 @cindex PCL-CVS
  11 @pindex cvs
  12 @cindex CVS Dired Mode
  13   The VC Dired Mode described here works with all the version control
  14 systems that VC supports.  Another more powerful facility, designed
  15 specifically for CVS, is called PCL-CVS.  @xref{Top, , About PCL-CVS,
  16 pcl-cvs, PCL-CVS --- The Emacs Front-End to CVS}.
  17
  18 @kindex C-x v d
  19 @findex vc-directory
  20   When you are working on a large program, it is often useful to find
  21 out which files have changed within an entire directory tree, or to view
  22 the status of all files under version control at once, and to perform
  23 version control operations on collections of files.  You can use the
  24 command @kbd{C-x v d} (@code{vc-directory}) to make a directory listing
  25 that includes only files relevant for version control.
  26
  27 @vindex vc-dired-terse-display
  28   @kbd{C-x v d} creates a buffer which uses VC Dired Mode.  This looks
  29 much like an ordinary Dired buffer
  30 @iftex
  31 (@pxref{Dired,,,emacs, the Emacs Manual});
  32 @end iftex
  33 @ifnottex
  34 (@pxref{Dired});
  35 @end ifnottex
  36 however, normally it shows only the noteworthy files (those locked or
  37 not up-to-date).  This is called @dfn{terse display}.  If you set the
  38 variable @code{vc-dired-terse-display} to @code{nil}, then VC Dired
  39 shows all relevant files---those managed under version control, plus
  40 all subdirectories (@dfn{full display}).  The command @kbd{v t} in a
  41 VC Dired buffer toggles between terse display and full display
  42 (@pxref{VC Dired Commands}).
  43
  44 @vindex vc-dired-recurse
  45   By default, VC Dired produces a recursive listing of noteworthy or
  46 relevant files at or below the given directory.  You can change this by
  47 setting the variable @code{vc-dired-recurse} to @code{nil}; then VC
  48 Dired shows only the files in the given directory.
  49
  50   The line for an individual file shows the version control state in the
  51 place of the hard link count, owner, group, and size of the file.  If
  52 the file is unmodified, in sync with the master file, the version
  53 control state shown is blank.  Otherwise it consists of text in
  54 parentheses.  Under RCS and SCCS, the name of the user locking the file
  55 is shown; under CVS, an abbreviated version of the @samp{cvs status}
  56 output is used.  Here is an example using RCS:
  57
  58 @smallexample
  59 @group
  60   /home/jim/project:
  61
  62   -rw-r--r-- (jim)      Apr  2 23:39 file1
  63   -r--r--r--            Apr  5 20:21 file2
  64 @end group
  65 @end smallexample
  66
  67 @noindent
  68 The files @samp{file1} and @samp{file2} are under version control,
  69 @samp{file1} is locked by user jim, and @samp{file2} is unlocked.
  70
  71   Here is an example using CVS:
  72
  73 @smallexample
  74 @group
  75   /home/joe/develop:
  76
  77   -rw-r--r-- (modified) Aug  2  1997 file1.c
  78   -rw-r--r--            Apr  4 20:09 file2.c
  79   -rw-r--r-- (merge)    Sep 13  1996 file3.c
  80 @end group
  81 @end smallexample
  82
  83   Here @samp{file1.c} is modified with respect to the repository, and
  84 @samp{file2.c} is not.  @samp{file3.c} is modified, but other changes
  85 have also been checked in to the repository---you need to merge them
  86 with the work file before you can check it in.
  87
  88 @vindex vc-stay-local
  89 @vindex vc-cvs-stay-local
  90   In the above, if the repository were on a remote machine, VC would
  91 only contact it when the variable @code{vc-stay-local} (or
  92 @code{vc-cvs-stay-local}) is nil (@pxref{CVS Options}).  This is
  93 because access to the repository may be slow, or you may be working
  94 offline and not have access to the repository at all.  As a
  95 consequence, VC would not be able to tell you that @samp{file3.c} is
  96 in the ``merge'' state; you would learn that only when you try to
  97 check-in your modified copy of the file, or use a command such as
  98 @kbd{C-x v m}.
  99
 100   In practice, this is not a problem because CVS handles this case
 101 consistently whenever it arises.  In VC, you'll simply get prompted to
 102 merge the remote changes into your work file first.  The benefits of
 103 less network communication usually outweigh the disadvantage of not
 104 seeing remote changes immediately.
 105
 106 @vindex vc-directory-exclusion-list
 107   When VC Dired displays subdirectories (in the ``full'' display mode),
 108 it omits some that should never contain any files under version control.
 109 By default, this includes Version Control subdirectories such as
 110 @samp{RCS} and @samp{CVS}; you can customize this by setting the
 111 variable @code{vc-directory-exclusion-list}.
 112
 113   You can fine-tune VC Dired's format by typing @kbd{C-u C-x v d}---as in
 114 ordinary Dired, that allows you to specify additional switches for the
 115 @samp{ls} command.
 116
 117 @node VC Dired Commands
 118 @subsection VC Dired Commands
 119
 120   All the usual Dired commands work normally in VC Dired mode, except
 121 for @kbd{v}, which is redefined as the version control prefix.  You can
 122 invoke VC commands such as @code{vc-diff} and @code{vc-print-log} by
 123 typing @kbd{v =}, or @kbd{v l}, and so on.  These commands will apply
 124 to the set of files you have marked for operation in the VC-Dired
 125 buffer.
 126
 127   The command @kbd{v v} (@code{vc-next-action}) operates on all the
 128 marked files, so that you can lock or check in several files at once.
 129 If the underlying VC supports atomic commits of multiple-file
 130 changesets @kbd{v v} with a selected set of modified but not committed
 131 files wuill commit all of them at once as a single changeset.
 132
 133   When @kbd{v v} (@code{vc-next-action}) operates on a set of files,
 134 it requires that all of those files must be in the same state;
 135 otherwise it will throw an error.  Note that this differs from the
 136 behavior of older versions of VC, which did not have fileset
 137 operations and simply did @code{vc-next-action} on each file
 138 individually.
 139
 140   If any files are in a state that calls for commit, @kbd{v v} reads a
 141 single log entry and uses it for the changeset as a whole.  If the
 142 underling VCS is file- rather than changeset-oriented, the log entry
 143 will be replicated into the history of each file.
 144
 145 @findex vc-dired-toggle-terse-mode
 146 @findex vc-dired-mark-locked
 147   You can toggle between terse display (only locked files, or files not
 148 up-to-date) and full display at any time by typing @kbd{v t}
 149 (@code{vc-dired-toggle-terse-mode}).  There is also a special command
 150 @kbd{* l} (@code{vc-dired-mark-locked}), which marks all files currently
 151 locked (or, with CVS, all files not up-to-date).  Thus, typing @kbd{* l
 152 t k} is another way to delete from the buffer all files except those
 153 currently locked.
 154
 155 @ignore
 156    arch-tag: 8e8c2a01-ad41-4e61-a89a-60131ad67263
 157 @end ignore