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 Directory Mode
   8 @subsection VC Directory Mode
   9
  10 @cindex PCL-CVS
  11 @pindex cvs
  12 @cindex CVS directory mode
  13   The VC directory 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   @kbd{C-x v d} creates a buffer which uses VC directory mode. This
  28 buffer will contain a listing of version-controlled files beneath
  29 the current directory, and their containing directories.  Files
  30 which are up-to-date (have no local differences from the repository
  31 copy) will be omitted; if all files in a directory are up-to-date,
  32 the directory will be omitted as well.  But there is an exception;
  33 if VC mode detects that a file changed to up-to-date state since your
  34 last look at it, that state will be shown.
  35
  36   The line for an individual file will show the version control state of
  37 the file.  Under RCS and SCCS, the name of the user locking the file
  38 is shown; under CVS, an abbreviated version of the @samp{cvs status}
  39 output is used.  Here is an example using RCS:
  40
  41   Here is an example using CVS:
  42
  43 @smallexample
  44 @group
  45     DIRECTORY            ./
  46     (modified)           file1.c
  47     (update)            file2.c
  48 @end group
  49 @end smallexample
  50
  51   Here @samp{file1.c} is modified with respect to the repository, and
  52 @samp{file2.c} is not.  @samp{file3.c} is modified, but other changes
  53 have also been checked in to the repository---you need to merge them
  54 with the work file before you can check it in.
  55
  56 @vindex vc-stay-local
  57 @vindex vc-cvs-stay-local
  58   In the above, if the repository were on a remote machine, VC would
  59 only contact it when the variable @code{vc-stay-local} (or
  60 @code{vc-cvs-stay-local}) is nil (@pxref{CVS Options}).  This is
  61 because access to the repository may be slow, or you may be working
  62 offline and not have access to the repository at all.  As a
  63 consequence, VC would not be able to tell you that @samp{file3.c} is
  64 in the ``merge'' state; you would learn that only when you try to
  65 check-in your modified copy of the file, or use a command such as
  66 @kbd{C-x v m}.
  67
  68   In practice, this is not a problem because CVS handles this case
  69 consistently whenever it arises.  In VC, you'll simply get prompted to
  70 merge the remote changes into your work file first.  The benefits of
  71 less network communication usually outweigh the disadvantage of not
  72 seeing remote changes immediately.
  73
  74 @vindex vc-directory-exclusion-list
  75   When a VC directory displays subdirectories it omits some that
  76 should never contain any files under version control.  By default,
  77 this includes Version Control subdirectories such as @samp{RCS} and
  78 @samp{CVS}; you can customize this by setting the variable
  79 @code{vc-directory-exclusion-list}.
  80
  81 @node VC Directory Commands
  82 @subsection VC Directory Commands
  83
  84   VC directory mode has a full set of navigation and marking commands
  85 for picking out filesets.  Some of these are also available in a
  86 context menu invoked with the right mouse button.
  87
  88   Up and down-arrow keys move in the buffer; @kbd{n} and @kbd{p}  also
  89 move vertically as in other list-browsing modes.  @kbd{SPC} and
  90 @kbd{TAB} behave like down-arrow, and the back-tab behaves like up-arrow.
  91
  92   Both @kbd{C-m} and @kbd{f} visit the file on the current
  93 line. @kbd{o} visits that file in another window.  @kbd{q} dismisses
  94 the directory buffer.
  95
  96   @kbd{x} toggles hiding of up-to-date files.
  97
  98   @kbd{m} marks the file on the current line.  @kbd{M} marks all
  99 files. @kbd{u} marks the file on the current line.  @kbd{U} unmarks all
 100 files.
 101
 102   Normal VC command with the @kbd{C-x v} prefix work in directory
 103 buffers.  Some single-key shortcuts are available as well; @kbd{=},
 104 @kbd{+}, @kbd{l}, @kbd{i}, and @kbd{v} behave as through prefixed with
 105 @kbd{C-x v}.
 106
 107   The command @kbd{C-x v v} (@code{vc-next-action}) operates on all the
 108 marked files, so that you can lock or check in several files at once.
 109 If the underlying VC supports atomic commits of multiple-file
 110 changesets @kbd{v v} with a selected set of modified but not committed
 111 files wuill commit all of them at once as a single changeset.
 112
 113   When @kbd{C-x v v} (@code{vc-next-action}) operates on a set of files,
 114 it requires that all of those files must be in the same state;
 115 otherwise it will throw an error.  Note that this differs from the
 116 behavior of older versions of VC, which did not have fileset
 117 operations and simply did @code{vc-next-action} on each file
 118 individually.
 119
 120   If any files are in a state that calls for commit, @kbd{C-x v v} reads a
 121 single log entry and uses it for the changeset as a whole.  If the
 122 underling VCS is file- rather than changeset-oriented, the log entry
 123 will be replicated into the history of each file.
 124
 125 @ignore
 126    arch-tag: 8e8c2a01-ad41-4e61-a89a-60131ad67263
 127 @end ignore