.TH RVC 1 "Nov 23, 2009" "" "" .SH NAME rvc - allow keeping remote files under version control by copying them back and forth to working directories .SH SYNOPSIS \fBrvc install []\fR .br \fBrvc installfile [] \fR .br \fBrvc appendfile [] \fR .br \fBrvc update []\fR .br \fBrvc add \fR .br \fBrvc addmultifile [ ]*\fR .br \fBrvc notedir \fR .br \fBrvc diff \fR .br \fBrvc do [ ...] \fR .br \fBrvc store \fR .br \fBrvc restore \fR .br \fBrvc release \fR .br \fBrvc ldiff []\fR .br \fBrvc lrestore []\fR .br \fBrvc status []\fR .br \fBrvc dirstatus []\fR .br \fBrvc ls []\fR .br .SH DESCRIPTION rvc is a glorified version of cp(1), just as stow(8) is a glorified version of ln(1). rvc is usually used to keep files that are sparsely scattered over the file system under central version control by copying them back and forth between the places they are supposed to reside and a working directory where they are kept under version control. Other uses include keeping files under version control if at the place they're supposed to reside the administrative information of your version control system cannot be kept for some reason. The files rvc knows about consist of a remote version control directory (usually $HOME/remote-vc) which contains several module directories. Each module contains a file (typically called rvc-places) which files are to be copied to remote places, and where precisely they are supposed to be copied to. The file structure is described in rvc-files(5) in detail. rvc also keeps a copy of each "installed" file (i.e., of each file copied to a remote place), so that changes at the remote place and changes in the module can be tracked separately. Example uses of rvc are described in rvc-examples(1). Background and examples on using rvc multifiles are given in rvc-multifiles(1). Once files are in place, \fBrvc do\fR is the actual workhorse to work with your local version controll system on the remote place. \fBrvc install []\fR .br Copy files from the specified module to the places they are intended to reside. This is specified by the file rvc-places in that module; see rvc-files(5) for a description of the file format. If no module is specified and the current working directory is a module directory, this module is taken. If the directory the file is supposed to reside in does not exist, it is created with ownership and permissions as described in the directories file (asuming the user running rvc is able to do so). A copy of the file is kept in the administrative directory, so that changes at the remote place and changes in the module can be traced separately. Unless the option \-force is given, rvc will not overwrite a file existing at the remote place; instead it will abort resulting in a possibly partial installation. If the option \-force is given, rvc will remove regular files at the remote places before installing that particular file. Normally, rvc will abort, if a place where a file is to be installed is already under rvc control. This may result in the installation being partial. If the option \-partial is given, rvc will just ignore these files. \fBrvc installfile [] \fR .br Same "rvc install", however only do the installation, where the local file name is as specified. This function is intended to install new files that an update in the module has brought you. Note that "rvc update" will not do this for you, to avoid accidental installation of files that are not to be installed at a particular machine. \fBrvc appendfile [] \fR .br Same as "rvc installfile", but instead insisting that the place be empty, we require that something is already installed at the given place and a multi-file will be build on this place by making the given file the last part of the multifile. \fBrvc update []\fR .br Include the changes in the module into the remote places. If no module is specified and the current working directory is a module directory, this module is taken. rvc update will replace all unmodified files in the remote places by the corresponding local files. It will not install any new files remotely, and will not touch any files that are changed at the remote place; change of ownership or permission is considered a change. \fBrvc add \fR .br Copy the remote file to the specified file in the specified module. The rvc-installed file in this directory will be updated accordingly. This will make rvc believe that this file is installed. If set, the content of the environment variable RVC_ADD_COMMAND is executed, using /bin/sh \-c. Before doing so the string RVCWORKINGDIR is replaced by the working directory to which the addition took place and the string RVCFILE is replaced by the file name within the module. Both substitutions are done unconditionally, in that order, without taking care about any quoting issues. \fBrvc addmultifile [ ]*\fR .br As rvc add, however the file is added as multifile (if the optional arguments are present). All the lines from the beginning till, but not including, the first line matching the first regexp are assigned to the first module/file pair. All following lines till one matching the next regular expression are assigned to the next module/file pair, and so on. After each part that is copied to the module directory and the places file appended accordingly the RVC_ADD_COMMAND is called as for the case of an rvc add. \fBrvc notedir \fR .br From the realpath of the directory mentioned up to the root directory, for each directory note owner and permissions in the directories file of the given module. If set, the content of the environment variable RVC_NOTE_DIR_COMMAND is executed, using /bin/sh \-c. Before doing so the string RVCWORKINGDIR is replaced by the working directory to which the addition took place. This substitution is done unconditionally without taking care about any quoting issues. \fBrvc diff \fR .br Show the changes that happened to the remote filed as compared to the installed version. \fBrvc do [ ...] \fR .br This command is the actual work horse, once files are installed properly. It checks, unless the option \-force is given, whether both, the installed file and the local file are unchanged. If this is the case, the following actions are carried out. 1.) change the working directory to the module directory the installed file originates from .br 2.) execute '$(RVC_VCS) ... ' where is the file name in the module that corresponds to the installed file .br 3.) update the changes (if any) to the local file to the remote file \fBrvc store \fR .br Store the changes to the specified remote file in the appropriate module directory; this changes that rvc believes to be installed. rvc store also updates the permissions in the rvc-places file of that module. rvc store will refuse any action if the file is changed locally. If set, the content of the environment variable RVC_STORE_COMMAND is executed, using /bin/sh \-c. Before doing so the string RVCWORKINGDIR is replaced by the working directory to which the addition took place. This substitution is done unconditionally without taking care about any quoting issues. \fBrvc restore \fR .br Restore a file that was lost remotely. rvc will get the remote file to the state (contents and permissions) it believes it last copied a file to this place. rvc will not do anything if a file exists at the remote place. Note that you have to have the needed permissions to set owner and group correctly. \fBrvc release \fR .br Release a file out of rvc control, i.e., remove the installation record. In case the file is \fBnot\fR a multi-file, the entry in the corresponding rvc-places file is removed as well. Note that in either case, the file will still reside in its remote place and also in its local place. The only change is that rvc stops feeling responsible for it. Before any action is taken, the file is checked for local and remote changes. In case of a \fBnon\fR multi-file the content of the environment variable RVC_RELEASE_COMMAND, if set, is executed, using /bin/sh \-c. Before doing so the string RVCWORKINGDIR is replaced by the working directory to which the addition took place. This substitution is done unconditionally without taking care about any quoting issues. \fBrvc ldiff []\fR .br Show the changes that happened to the specified file of the specified module as compared to the installed version. If no module is specified and the current directory is a module directory, this module is taken. \fBrvc lrestore []\fR .br Restore a file that was lost locally. rvc file get the specified file of the specified module from its installation copy. If no module is specified and the current directory is a module directory, this module is taken. rvc lrestore will not replace any existing file. \fBrvc status []\fR .br Gives a summary of the state of the various files in the specified module; if no module is specified and the current working directory is a module directory, this module is taken. For each file, the name and intended remote place is listed and a state is given, which can be one of the following. "uninstalled", meaning that rvc has no record of this file being copied to the remote place and the remote place is empty. "(space occupied)", meaning that rvc has no record of this file being copied to the remote place, but some file is residing at the remote place. In this case it is also reported whether the existing file coincides with the file that would be at the remote place. "[module:file]", signalling that the specified place has already been used by an installation of the given named file of the named module. "installed", meaning that the file from that module was copied to the remote place. In this case also changes are reported: a file could have been lost locally, lost remotely, changed locally, changed remotely, or changed at both place. The latter is reported as a conflict. \fBrvc dirstatus []\fR .br Show the directories of all directories noted in that module and compare with the actual permissions. \fBrvc ls []\fR .br Show the same summary as "rvc status", but instead of doing so for every file of a module, rvc does so for every installed file in the specified directory (defaults to the current one). .SH ENVIRONMENT VARIABLES \fBRVC_DIRECTORY\fR .br This variable contains the location of the remote version control directory; see rvc-files(5) for a description on how the directory has to look like. If this environment variable is not specified the default "$HOME/remote-vc" is taken. \fBRVC_PLACES\fR .br This variable may contain an alternative name of the places file; see rvc-files(5) for details. The default is "rvc-places" and it is recommended to keep it. \fBRVC_DIRS\fR .br This variable may contain an alternative name of the directories file; see rvc-places(5) for details. The default is "rvc-dirs" and it is recommended to keep it. \fBRVC_ADMIN_USER\fR .br User name, or "user:group", of the user (and group) to which newly created files and directories in the rvc-installed directory should belong. Note that you need superuser privileges to change ownership. So this environment variable will be mainly useful for the root user; its intended use is to allow all the operations that do not change the remote place to be carried out by a designated normal user, thus potentially reducing the need to act as superuser. \fBRVC_VCS\fR .br The name of the command to be used for the do command. So, most probably, it should be the way how you call the version control system you use for your rvc-modules. If this variable is not specified, "rcs" is used as a default. \fBRVC_ADD_COMMAND \fR .br If set, the content of the environment variable RVC_ADD_COMMAND is executed, using /bin/sh \-c, after an "rvc add". Before doing so the string RVCWORKINGDIR is replaced by the working directory to which the addition took place and the string RVCFILE is replaced by the file name within the module. Both substitutions are done unconditionally, in that order, without taking care about any quoting issues. \fBRVC_STORE_COMMAND \fR .br If set, the content of the environment variable RVC_STORE_COMMAND is executed, using /bin/sh \-c, after an "rvc store". Before doing so the string RVCWORKINGDIR is replaced by the working directory to which the addition took place. This substitution is done unconditionally without taking care about any quoting issues. \fBRVC_RELEASE_COMMAND \fR .br If set, the content of the environment variable RVC_RELEASE_COMMAND is executed, using /bin/sh \-c, after an "rvc release" that did not concern a multi-file. Before doing so the string RVCWORKINGDIR is replaced by the working directory to which the addition took place. This substitution is done unconditionally without taking care about any quoting issues. \fBRVC_STATUS_FORMATSTRING\fR .br The format string to be used to display the summaries shown by "rvc status" and "rvc ls". Defaults to " %-10s %-35s %-20s %-17s %s". \fBRVC_DIRSTATUS_FORMATSTRING\fR .br The format string to be used to display the summaries shown by "rvc dirstatus". Defaults to "%1s %-60s %-23s %-23s". .SH OPTIONS \fB-force\fR .br Force "rvc install" and "rvc installfile" to overwrite already existing files at the remote place. Force "rvc do" to carry out the command and installation afterwards, even if there are local or remote changes that might be overwritten by this action. Force "rvc appendfile" to build a multifile, discarding all changes in the installed file. \fB-observer\fR .br Make "rvc install" and "rvc installfile" agnostic about the remote places. In other words, rvc will only manipulate its installed directory. If no file is at the remote place, then the file will be considered "lost remote" immediately afterwards; if a file with a different content exists in the remote place, it will be considered changed remotely. Additionally, make "rvc release" leave the rvc-places untouched. The option \-observer implies the option \-partial. \fB-part\fR .br Tell "rvc do" which part of a multi file to use. Defaults to 0. \fB-partial\fR .br Allow "rvc install" (and "rvc installfile") to install only a few files of the module, if the others are already under rvc control. .SH NOTE After any failing file operation, rvc will abort with an appropriate error message; it will not try to get the data structure into a consistent state. The rational is, that such operations usually fail due to missing permissions of the calling user or file systems being mounted read-only; in this case there is no reasonable way of recovering and a simple abort is likely to cause the least harm. Note that the files in questions are still present in their original location. Also note, that the consistency of the database can always trivially be restored by removing the subdirectory for that file in the rvc-installed directory (see rvc-files(5) for details of the file structure); however, this might result in data loss and is therefore never done automatically. .SH WARNING Multi-files have only recently (February 2009) been added to rvc and so far only been tested by a small group of users. Please inform the author about any bugs you find. .SH SEE ALSO .BR rvc-files "(5), "rvc-examples "(1), "rvc-multifiles "(5)" .SH AUTHOR Klaus Aehlig .