vc - a Version Control wrapper for CVS and RCS.
vc [cvs-options] command [command-options] [command-arguments]
This documentation supplements, but does not replace, the
documentation for CVS and the various RCS tools. There are
several new commands and commands whose behavior is somewhat
modified; These are described in most detail.
The Concurrent Versions System (CVS) is a version control system built on the Revision Control System (RCS) which can handle entire directory trees of files rather than entries just within a directory. While RCS stores its revision data files in the directory under version control, CVS has an abstract location for these, called the CVSROOT. One uses RCS "in place", or in just one location, whereas under CVS one checks out a sandbox to make changes in, then checks those changes in to the repository when satisfied with them.
This wrapper script, VC, aims to combine the interfaces somewhat, and to "fix" behaviors in each that the author deemed "broken". In general, commands that are meaningful to both RCS and CVS should work similarly under each. The point was not to hide CVS and RCS from the user, but to cut down on the amount of discontinuity and frustration when working with either one or switching between them.
Please read the CVS manpage and the various RCS manpages for more in-depth documentation on most commands.
This section details commands. Your intuitions from CVS should work and are relied upon in these descriptions. Emphasis is on differences between CVS and RCS behaviors for the most common syntax of commands, and the most common usages.
Display version information about vc.
Display this man page.
Synonyms: h
import update rcs2cvs repository root gasps
Initiate version control in the current directory, initially adding almost* all contents.
Synonyms: imp im
Uses CVS if the $CVSROOT environment variable is defined, otherwise RCS.
When using CVS, you can optionally specify the repository name. The current directory name is used by default. The vendor and release tags will be set to the $USER environment variable and "START" for CVS.
Note when importing into CVS that the current directory does NOT become an active sandbox, unlike importing into RCS. For CVS you must check out a new sandbox after import and may remove the original directory.
if .cvsignore is present, filenames in it, one per line, will be ignored during import.
* for RCS, emacs ~ files, .\# files and \#...\# files are ignored. for CVS, these are expected to be in the cvsroot/cvsignore file. Symbolic links are not followed.
Bring the working directory up to date with changes from the repository.
Under RCS, this correctly displays CVS-style status for files in the current directory, paying attention to .cvsignore files, and resurrecting files which have been 'lost'.
if .cvsignore is present, filenames in it, one per line, will be ignored during update.
NOTE: The ideal situation is that in which vc update says nothing at all.
Synonyms: upd up
Convert the current RCS-controlled directory to CVS control
NOTE: this involves 'hacking the repository' so you must be on the same filesystem as the CVSROOT.
Set the repository name for the current sandbox to be new_name.
This is rarely useful, but good to have.
Synonyms: rep
Set the CVSROOT associated with the current sandbox to new_CVSROOT.
This is most useful when relocating the CVSROOT.
Occasionally cvs will fail slightly during remote checkout, complaining about 'unexpected dying gasps from <server>'. This will try to fix the resulting sandbox.
add checkout remove rename
Put a file under version control for the first time.
Synonyms: ad new
For CVS, you need to be in a sandbox for an existing repository.
For RCS, there needs to be an RCS directory already. (import will create one)
if .cvsignore is present, filenames in it, one per line, will be ignored during adding of entire directories (as with import).
check out a file or repository from version control.
Synonyms: co get
CVS and RCS mean slightly different things by checkout. Under RCS you get a fresh copy of a file. Under CVS you get an entire fresh sandbox.
Remove files and directories from the source repository.
In CVS, does not take effect until a commit on the same files.
In RCS, puts files in the Attic -- a deviation from standard RCS.
Synonyms: rm delete
Renames old_name to new_name in the repository and in the current directory.
This is history preserving in that repository files are removed and then readded.
Synonyms: ren mv
commit cu tag log message diff edit unedit rdiff
"publish" changes to files under version control.
Synonyms: checkin check ci
if .cvsignore is present, filenames in it, one per line, will be ignored during checkin.
RCS NOTE: this keeps a lock! See also the new command vc cu.
Check in and Unlock filenames.
This is most useful in RCS, or when you regularly vc edit before modifying files. It checks in and lets go in one step.
if .cvsignore is present, filenames in it, one per line, will be ignored during checkin.
Other Mnemonic: "see you!" :-)
Specify a symbolic tag for files in the repository. By default this tags the latest revision.
Setting a tag to a name already tagged for that file clobbers the old tag, marking the new revision with it (i.e. rcs -N style)
Synonyms: ta freeze
Display log information. If -r revision is specified, then display only the message for that revision.
Does not affect repository or working directory.
Synonyms: lo rlog
Change the log message for a revision, by default the latest, of a file
WARNING: this replaces the current log message! Do not destroy information!
Synonyms: msg
see differences between revisions, between the current revision and a particular one, or between the current and latest versions (depending on how many -rs you specify).
Synonyms: di dif rcsdiff
Update files and lock them for editing.
Synonyms: edit lock
Under CVS does update THEN edit.
Under RCS does co -l.
Revert filenames to those last checked into the repository, and unlock.
This is usually done with either cu or by removing the file from the sandbox and updating.
Synonyms: unlock
Prepare a collection of diffs as a patch file between two releases in the repository.
Does not affect repository or working directory.
Synonyms: patch pa
Lots of bugs have been reported, and they are all listed here. Mostly I have not yet had time to fix them, or am not sure how.
the dumb terminal emacs forces on people makes the "less" in the help mode not page right - requires return after the space. ugh. Not sure how to fix it. OTOH this is a command-line tool. Emacs has its own version control stuff...
I can add this when CVSROOT is not :ext: at any rate.
like -kb, yes, but also like branchpoints? renaming under cvs is best done by removing the file, then adding it under a new name. This preserves the property of being able to go back in time and see what you actually saw, and is thus better than hacking the repository even though you can no longer vc log to see older changes. Should rename preserve what branch the file lives on? probably. Should it preserve a sticky version number? probably not.
yes, it should. soon.
okay, there is no equivalent to vc message in emacs already, so I suppose this is a problem. I think the deal is that I have to pass the text to rcs, and I either do it wrong or there is no good way to do it. must explore.
vc add on something that needs to be imported should be smarter than cvs and actually ask if you meant to import a new thing rather than just saying you used the wrong command. There is basically no useful purpose for import as far as I can tell that would not be as well served by the "add" keyword.
one of the "advantages" of rcs over cvs is apparently that if you want to find when you did something to what file, you can simply grep -r in the general vicinity of the change and get something reasonable. There is no good reason I should not support that if CVSROOT is not :ext:*.
oops. yep, that is true. workaround: vc up -d removed-directory, vc ci removed-directory, rm removed-directory. I will fix this soon.
Gregory A. Marton http://csail.mit.edu/~gremio/