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/vcs/