NAME
       vcs - version control system wrapper

SYNOPSIS
       vcs [OPTION...] COMMAND [OPTION...] [ARGUMENTS...]

DESCRIPTION
       vcs  guesses  what  version control system you are using and translates
       its own command set accordingly.

OPTIONS
       These options are global to vcs and appear before the command name.

       --verbose, -v
              Verbose operation.

       --debug, -d
              Debug mode.  Can be used more than once for extra debug output.

       --dry-run, -n
              Instead of executing native commands, just display them on stan-
              dard output.

       --guess, -g
              Identify  the  native  version control system.  Normally this is
              done silently and automatically; this option displays the chosen
              version control system and then exits.

       --commands, -H
              Displays a list of commands.

       --help, -h
              Display usage message.

       --version, -V
              Display version number.

COMMANDS
       Commands  may  be abbreviated to a non-ambiguous prefix.  Commands have
       their own options which must appear after the command name.   All  com-
       mands  have  a  --help option (not listed below) which summarizes their
       usage.

   add
       vcs add [--binary|-b] FILENAME...

       Subjects the listed files to version control.  The files are  not  com-
       mitted.

       --binary  indicates  that the file should not be translated in any way.
       This is suitable for image files, etc.  Note that not every native ver-
       sion  control  system has a corresponding option (some prefer to figure
       it out themselves or do no translation).  In such cases,  the  --binary
       option is ignored.

       If  you  try  to  add directories and the native version control system
       (for instance Perforce)  does  not  support  that,  they  are  silently
       ignored.

   annotate
       vcs annotate FILENAME

       Outputs  the named file with each line annotated with information about
       its origin.  Depending on the version control system in used, this will
       usually  some  of the revision number it was last modified in, the date
       of the last revision and the user who modified it.

       vcs blame is a synonym for vcs annotate.

   clone
       vcs clone URI [DIRECTORY]

       Attempts to deduce what version control system is used by URI and check
       out a copy.  If DIRECTORY is specified then that is used, otherwise the
       leaf name of the URI is used.

       In some cases the version control system can be inferred directly  from
       the  URI,  for  instance  if it is a git: URI.  In other cases vcs will
       check for the existence of particular files such as  .git  or  .bzr  to
       figure out what version control system is used.

       Use  the -v option to see details of what it tries, if it isn't working
       and you think it should.

   commit
       vcs commit [--message|-m MESSAGE] [FILENAME...]

       Commits the listed files, or all modified files if none are listed.

       --message allows the commit message to be set.  If  none  is  specified
       then  an  editor  is  started.  If possible, vcs lets the native system
       invoke the editor rather than doing so itself.

       vcs ci and vcs checkin are a synonyms for vcs commit.

   diff
       vcs diff [FILENAME...]

       Displays differences between the last committed version and the current
       checkout.  If no filename is specified then all files are diffed.  Oth-
       erwise only the listed files are diffed.

       vcs diff -c CHANGE

       This is equivalent to vcs show CHANGE.

   edit
       vcs edit FILENAME...

       Makes files editable.  For most (but not all) version  control  systems
       this is not needed and is a no-op.

   log
       vcs log [FILENAME]

       Display the change history for FILENAME, or for all files if no file is
       specified.  (Beware, the latter case is very verbose for CVS!)

   remove
       vcs remove [--force|-f] FILENAME...

       Removes the named files.

       The default behaviour is the same as the native version control system.
       For  instance  if  it  insists that you delete the files first, or only
       remove unchanged files, then so will vcs remove.

       With --force, the files will be deleted and removed from  version  con-
       trol unconditionally.

       vcs rm is a synonym for vcs remove.

   rename
       vcs rename SOURCE...  DESTINATION

       Rename files.

       If  the  destination does not exist then there must be only one source,
       and its name will be changed to match the destination.

       If the destination does exist then it must be a directory, and all  the
       source files and directories are renamed "into" it.

       vcs mv is a synonym for vcs rename.

   revert
       vcs revert [FILENAME...]

       Revert changes to the listed files, or to all files if none are listed.

       Removed  files  are  resurrected  and  modified  files have any changes
       undone.  Some version control systems will save the modified version to
       a  backup file.  Newly added files are removed from version control and
       may be deleted (depending on the underlying version control system).

       Note that not all version control systems can selectively revert  indi-
       vidual files.

   show
       vcs show CHANGE

       Displays  an  existing, committed, change.  The change is identified in
       the native way for the underlying version control system.

       vcs describe is a synonym for vcs show.

   status
       vcs status

       Displays a summary of the current status, showing files that have  been
       added, edited, removed or are not in version control (and not ignored).

       Note  that  the  output  format is generally that of the native version
       control system.  One exception to this for Perforce; see below for full
       details.

   update
       vcs update

       Updates the working tree to the latest revision.  Note that (currently)
       it is not possible to update only a subset of files, or to  synchronize
       to a non-head revision.

       For  distributed  version  control  systems this both fetches revisions
       from a parent branch and updates your working tree.

       vcs update does not attempt to handle conflicts in a uniform way across
       version  control systems.  You get whatever the underlying system gives
       you: for instance, conflict markers in files, or questions asked during
       update.   You  may have to run commands such as bzr resolve to indicate
       conflicts resolved or p4 resolve  to  invoke  the  conflict  resolution
       tool.

ENVIRONMENT
       VCS_PAGER

       VCS_DIFF_PAGER
              vcs   diff  and  vcs  show  will  filter  their  output  through
              VCS_DIFF_PAGER or, if that is not set, VCS_PAGER.  vcs  log  and
              vcs annotate will filter their output through VCS_PAGER.

              The  pager  command is executed via the shell.  In both cases no
              filter will be done executed if standard output is not a  termi-
              nal.

              You might, for example, set these as follows:

              VCS_PAGER=less
              VCS_DIFF_PAGER='colordiff|less -R'

SUPPORTED VERSION CONTROL SYSTEMS
       This  section  describes  the  supported  version control systems.  Any
       issues specific to them are describe here.

   CVS
       Web page: http://www.nongnu.org/cvs/

       CVS does not auto-detect file types, so use of vcs add --binary  option
       when adding images files, etc is mandatory.  vcs rename and vcs show do
       not work with CVS.

   Bazaar
       Web page: http://bazaar-vcs.org/

       vcs up will invoke bzr up in a bound branch (created with bzr checkout)
       and bzr pull in any other branch.

   Subversion
       Web page: http://subversion.tigris.org/

   Git
       Web page: http://git-scm.com/

       vcs  has a more CVS-like model than Git; therefore vcs commit will com-
       mit all your changes, not just those mentioned with git add.

       vcs revert will delete newly added files.

   Mercurial
       Web page: http://www.selenic.com/mercurial/

   Darcs
       Web page: http://darcs.net/

   Perforce
       Web page: http://www.perforce.com/

       vcs edit (or p4 edit) is required before editing existing files.

       Commands that apply to multiple files are applied only to files  in  or
       below the current directory.

       vcs  status  produces  CVS-like output summarizing which files are open
       and which are unknown to Perforce.  The characters at the start of each
       line have the following meaning:

       A      File is opened for add.

       E, e   File is opened for edit.  e means that it has not been modified.

       D      File is opened for delete.

       B      File is opened for branch.

       I, i   File is opened for integrate.  i means that it has not been mod-
              ified.

       R      File needs to be resolved.

       ?      File is unknown to Perforce (and not ignored).

       You can put filenames or glob patterns in .vcsignore in each directory,
       or  in  your home directory, to hide files that would otherwise show up
       as ?.  If you ignore a file that is known to Perforce then a warning is
       printed.

       Perforce  will  only be detected if at least one of P4PORT, P4CONFIG or
       P4CLIENT is set, and detection works by invoking p4 changes to  see  if
       the current directory is inside a P4 workspace.

   RCS
       Web page: http://www.gnu.org/software/rcs/

       For  the commands that take multiple filenames, if none are given, then
       all (relevant) RCS-controlled files in and below the current  directory
       are affected.

       vcs edit is required before editing existing files.

       vcs  add creates a dot-file recording that the file was added.  It will
       only be committed when you run vcs  commit.   On  the  other  hand  vcs
       remove removes the file immediately.  This might be changed in a future
       version.

       vcs update will ensure that working files exist.

       vcs annotate, vcs rename and vcs show are not implemented for RCS.

       .vcsignore files work as described above.

       Binary files are not supported.

   SCCS
       Web page: http://www.gnu.org/s/cssc/

       SCCS support is similar to RCS support except:

       o      Binary files are supported.

       o      Files with "awkward" names do not work properly.

       It has only been tested with GNU CSSC.

DESIGN PRINCIPLES
       vcs has a deliberately limited command set.  The idea  is  to  reliably
       support  common  operations  rather than to support rare operations but
       only some of the time.

       vcs is not intended to give exactly identical semantics for every  ver-
       sion control system, just essentially similar ones.

       vcs does not usually attempt to translate the output of native commands
       to a consistent format.  As a rule you get what the native system gives
       you.

       vcs is intended to be useful rather than to adhere to arbitrary rules.

AUTHOR
       Richard Kettlewell <rjk@greenend.org.uk>

       The VCS home page is: http://www.greenend.org.uk/rjk/2009/vcs.html