.TH RVC-EXAMPLES 1 "Jan 21, 2007" "" .SH NAME rvc-examples - Usage examples for rvc. .SH Collecting sparsely scattered files under version control The motivation that lead to rvc being written, was the observation that most configuration files of your favourite distribution of your operating system are just what you need. However, as time evolves, you start modifying some of them, following your changed needs. Wouldn't it be nice to use version control to keep track of these changes? However, getting all of /etc/ under version control seems overkill---not that version control systems wouldn't be able to cope with this. It's just, that the few files you changed get buried in tons of unchanged files. And, moreover, when installing new packages more files come that you have to tell you version control about... The alternative that rvc proposes is to have a small repository and control these files remotely (hence the name "remote version control"). In the example above you---using your normal user account--would create a directory remote-vc in your home directory and within that you create a working directory, say you call it my-confs, of your favourite version control system. That's it, for the start, i.e., as long as you don't have any files under remote version control. Now say you are about to change /etc/network/interfaces to adopt to a changed network environment (if this is the place where your network configuration is stored). So you change to /etc/network. To see what is already under version control you type \fBrvc ls\fR .br and find out that nothing is under version control yet. As changing a file involves the risk of messing it up, you decide to get a copy of the current state of the file under remote version control; putting it to my-confs and calling it interfaces there seems natural to you. So you type \fBrvc add interfaces my-confs interfaces\fR .br where the first "interfaces" specifies the file you wish to add and the second "interfaces" is how you call it in your working directory. Changing back to ~/remote-vc/my-conf you find a copy of the interfaces directory and a file rvc-installed, which contains a line like interfaces root root 644 /etc/network/interfaces saying that the remote place of the file interfaces is /etc/network/interfaces and at this place it should have owner and group root and permissions 644. You do whatever you need to do in version control system to commit these newly added files. Then, as root, you do the necessary changes. As your normal user, you can always type \fBrvc diff interfaces\fR .br to see what has changed compared to the version you've added. Once you're happy with the changes, you decide to store the new changes as well, so you type \fBrvc store interfaces\fR .br in directory /etc/network. Then, in directory ~/remote-vc/my-conf you'll find that in your copy of interfaces the changes are incorporated as well. (That's why it was a good idea to commit before changing the file.) If you also changed the permissions, the file rvc-places will be changed as well. So, you commit the changes in your working directory. As you might note, after each call to "rvc add" or "rvc store" some version control action have to be carried out. rvc is willing to do this for you, but---being only a fancy way to call cp---it doesn't know which version control system you are using and how you call it; so you have to tell rvc this. The way to do this, is to set the environment variables RVC_ADD_COMMAND, RVC_STORE_COMMAND, and RVC_RELEASE_COMMAND appropriately. The contents of these variables are called after "rvc add", "rvc store", and "rvc release", respectively. To help adapting these calls to your needs, the string RVCWORKINGDIR is replaced by the absolute path to the working directory where the change happened. In case of "rvc add", the string RVCFILE is also (in a second substitution step) replaced by the name of the file within the module. Note that rvc does no quoting for you. If, for example, you are using cvs and know that you will never have single quotes in any file names occurring in your working directory and the path to it, a sensible setting for RVC_ADD_COMMAND could be (cd 'RVCWORKINGDIR'; cvs add 'RVCFILE'; cvs ci) and a sensible setting for RVC_STORE_COMMAND could be (cd 'RVCWORKINGDIR'; cvs ci) note the single quotes around the file name to avoid bad surprises. .SH Reverting, updates, logs Continuing the above example, after a while your have to undo the changes in your network configuration (e.g., your company decides to go back to the good old things they had). One way would to, to revert back, using the version control system in ~/remote-vc/my-conf, to the old version. Then, with appropriate permission (using su(1)), you call the command \fBrvc update my-conf\fR .br to get the changes copied to the remote place (note that this copying is the only action where you actually need root privileges). rvc is very carefully not to overwrite any files that are not under its control or that have changed at the remote place. Of course, you can use the same command for any other form of updates that you got (presumably using some form of version control) into your working directory. However, usually you would \fBnot\fR use the above described pedestrian way and go to ~/remote-vc if you know where the remote place is. Assuming that you have set RVC_VCS to the binary of the version control system you are using in the background (let's do the examples for cvs, but for other version control systems it would be quite similar), you can just go to the \fBremote\fR place, i.e., /etc/network, and call (again, appropriate permissions provided) \fBrvc do update \-r1.1 interfaces\fR .br What happens internally is, that the file is copied to the appropriate file in the correct module directory, then, using the module directory as working directory, "$RVC_VCS " is called and the changed file is copied back. The changes are also tracked in the rvc-installed directory. Here, the are all but the last argument of the call to rvc do; in the above example that would be "update" and "\-r1.1". Similar uses of "rvc do" include \fBrvc do log interfaces\fR .br \fBrvc do diff \-r1.1 interfaces\fR .br Note that this way all version control operations can be carried out without ever changing to ~/remote-vc or actually worrying which module (and therefore repository) a particular file belongs. .SH Installation The easiest way to get a prepared module distributed to the place the files belong is to enter the module directory and type "rvc install". Say, for example, that you come to a new machine and you want to have all your configuration files like .bashrc---which you keep under version control ready for rvc---at their usual places. Then you might type something as follows. \fBcd\fR .br \fBmkdir remote-vc\fR .br \fBcd remote-vc\fR .br \fBcvs checkout \-d :ext:user@some.host:/path/to/repository config\fR .br \fBcd config\fR .br \fBrvc install\fR .br If at the new places, people were nice to you and already provided you with some .bashrc, etc, which you don't want to bother looking at, you might type "rvc \-force install" instead of the "rvc install" in the previous example. .SH SEE ALSO .BR rvc "(1)" .SH AUTHOR Klaus Aehlig