code.delx.au - gnu-emacs/blob - 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-dir
  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-dir}) 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 below the
  29 current directory, and their containing directories.  Files which are
  30 up-to-date (have no local differences from the repository copy) will be
  31 omitted; if all files in a directory are up-to-date, the directory will
  32 be omitted as well.  (However, the directory in which @code{vc-dir} was
  33 run will always be shown as @file{./}.)  There is an exception to this
  34 rule: if VC mode detects that a file changed to up-to-date state since
  35 you last looked at it, that state will be shown.
  36
  37   If a directory uses more that one VC system, you can select which VC
  38 system to use for the @code{vc-dir} command by invoking @code{vc-dir}
  39 with a prefix argument, i.e.@: @kbd{C-u C-x v d}.
  40
  41   The line for an individual file will show the version control state of
  42 the file.  Under RCS and SCCS, the name of the user locking the file
  43 is shown; under CVS, an abbreviated version of the @samp{cvs status}
  44 output is used.  Here is an example using RCS:
  45
  46   Here is an example using CVS:
  47
  48 @smallexample
  49 @group
  50                        ./
  51     modified           file1.c
  52     needs-update       file2.c
  53     needs-merge        file3.c
  54 @end group
  55 @end smallexample
  56
  57   Here @samp{file1.c} is modified with respect to the repository, and
  58 @samp{file2.c} is not.  @samp{file3.c} is modified, but other changes
  59 have also been checked in to the repository---you need to merge them
  60 with the work file before you can check it in.
  61
  62 @vindex vc-stay-local
  63 @vindex vc-cvs-stay-local
  64   In the above, if the repository were on a remote machine, VC would
  65 only contact it when the variable @code{vc-stay-local} (or
  66 @code{vc-cvs-stay-local}) is nil (@pxref{CVS Options}).  This is
  67 because access to the repository may be slow, or you may be working
  68 offline and not have access to the repository at all.  As a
  69 consequence, VC would not be able to tell you that @samp{file3.c} is
  70 in the ``merge'' state; you would learn that only when you try to
  71 check-in your modified copy of the file, or use a command such as
  72 @kbd{C-x v m}.
  73
  74   In practice, this is not a problem because CVS handles this case
  75 consistently whenever it arises.  In VC, you'll simply get prompted to
  76 merge the remote changes into your work file first.  The benefits of
  77 less network communication usually outweigh the disadvantage of not
  78 seeing remote changes immediately.
  79
  80 @vindex vc-directory-exclusion-list
  81   When a VC directory displays subdirectories it omits some that
  82 should never contain any files under version control.  By default,
  83 this includes Version Control subdirectories such as @samp{RCS} and
  84 @samp{CVS}; you can customize this by setting the variable
  85 @code{vc-directory-exclusion-list}.
  86
  87 @node VC Directory Commands
  88 @subsection VC Directory Commands
  89
  90   VC Directory mode has a full set of navigation and marking commands
  91 for picking out filesets.  Some of these are also available in a
  92 context menu invoked by the @kbd{mouse-2} button.
  93
  94   Up- and down-arrow keys move in the buffer; @kbd{n} and @kbd{p}  also
  95 move vertically as in other list-browsing modes.  @key{SPC} and
  96 @key{TAB} behave like down-arrow, and @key{BackTab} behaves like
  97 up-arrow.
  98
  99   Both @kbd{C-m} and @kbd{f} visit the file on the current
 100 line.  @kbd{o} visits that file in another window.  @kbd{q} dismisses
 101 the directory buffer.
 102
 103   @kbd{x} toggles hiding of up-to-date files.
 104
 105   @kbd{m} marks the file or directory on the current line.  If the
 106 region is active, @kbd{m} marks all the files in the region.  There
 107 are some restrictions when marking: a file cannot be marked if any of
 108 its parent directories are marked, and a directory cannot be marked if
 109 any files in it or in its child directories are marked.
 110
 111   @kbd{M} marks all the files with the same VC state as the current
 112 file if the cursor is on a file.  If the cursor is on a directory, it
 113 marks all child files.  With a prefix argument: marks all files and
 114 directories.
 115
 116   @kbd{u} unmarks the file or directory on the current line.  If the
 117 region is active, it unmarks all the files in the region.
 118
 119   @kbd{U} marks all the files with the same VC state as the current file
 120 if the cursor is on a file.  If the cursor is on a directory, it
 121 unmarks all child files.  With a prefix argument: unmarks all marked
 122 files and directories.
 123
 124   It is possible to do search, search and replace, incremental search,
 125 and incremental regexp search on multiple files.  These commands will
 126 work on all the marked files or the current file if nothing is marked.
 127 If a directory is marked, the files in that directory shown in the VC
 128 directory buffer will be used.
 129
 130   @kbd{S} searches the marked files.
 131
 132   @kbd{Q} does a query replace on the marked files.
 133
 134   @kbd{M-s a C-s} does an incremental search on the marked files.
 135
 136   @kbd{M-s a C-M-s} does an incremental search on the marked files.
 137
 138   Commands are also accessible from the VC-dir menu.  Note that some VC
 139 backends use the VC-dir menu to make available extra backend specific
 140 commands.
 141
 142   Normal VC commands with the @kbd{C-x v} prefix work in VC directory
 143 buffers.  Some single-key shortcuts are available as well; @kbd{=},
 144 @kbd{+}, @kbd{l}, @kbd{i}, and @kbd{v} behave as through prefixed with
 145 @kbd{C-x v}.
 146
 147   The command @kbd{C-x v v} (@code{vc-next-action}) operates on all the
 148 marked files, so that you can check in several files at once.
 149 If the underlying VC supports atomic commits of multiple-file
 150 changesets, @kbd{C-x v v} with a selected set of modified but not
 151 committed files will commit all of them at once as a single changeset.
 152
 153   When @kbd{C-x v v} (@code{vc-next-action}) operates on a set of files,
 154 it requires that all of those files must be either in the same state or
 155 in compatible states; otherwise it will throw an error (added,
 156 modified and removed states are considered compatible).  Note that this
 157 differs from the behavior of older versions of VC, which did not have
 158 fileset operations and simply did @code{vc-next-action} on each file
 159 individually.
 160
 161   If any files are in a state that calls for commit, @kbd{C-x v v} reads a
 162 single log entry and uses it for the changeset as a whole.  If the
 163 underling VCS is file- rather than changeset-oriented, the log entry
 164 will be replicated into the history of each file.
 165
 166 @ignore
 167    arch-tag: 8e8c2a01-ad41-4e61-a89a-60131ad67263
 168 @end ignore