man/vc1-xtra.texi

   1 @c This is part of the Emacs manual.
   2 @c Copyright (C) 2004, 2005, 2006, 2007 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.  Most of these commands apply
 124 to the file name on the current line.
 125
 126   The command @kbd{v v} (@code{vc-next-action}) operates on all the
 127 marked files, so that you can lock or check in several files at once.
 128 If it operates on more than one file, it handles each file according to
 129 its current state; thus, it might lock one file, but check in another
 130 file.  This could be confusing; it is up to you to avoid confusing
 131 behavior by marking a set of files that are in a similar state.  If no
 132 files are marked, @kbd{v v} operates on the file in the current line.
 133
 134   If any files call for check-in, @kbd{v v} reads a single log entry,
 135 then uses it for all the files being checked in.  This is convenient for
 136 registering or checking in several files at once, as part of the same
 137 change.
 138
 139 @findex vc-dired-toggle-terse-mode
 140 @findex vc-dired-mark-locked
 141   You can toggle between terse display (only locked files, or files not
 142 up-to-date) and full display at any time by typing @kbd{v t}
 143 (@code{vc-dired-toggle-terse-mode}).  There is also a special command
 144 @kbd{* l} (@code{vc-dired-mark-locked}), which marks all files currently
 145 locked (or, with CVS, all files not up-to-date).  Thus, typing @kbd{* l
 146 t k} is another way to delete from the buffer all files except those
 147 currently locked.
 148
 149 @ignore
 150    arch-tag: 8e8c2a01-ad41-4e61-a89a-60131ad67263
 151 @end ignore