vipsi - how to use the cvs
Author: kio@little-bat.de
Keywords: vipsi shell script interpreter programming

# vipsi - shell and script language

## how to use the cvs

### Introduction to the Concurrent Versions System CVS

this introduction is aimed to developers, not admins. in essence it says nothing more than sourceforge's documentation, it only leaves out 90% of it. :-) though it's written for developers working for vipsi, it's generally appliable for any other project at sourceforge.

first i'll tell you some basics. then all the unix stuff; as far as i consider it useful. finally i hope i can add some Windows stuff too.

if you find an error, something unclear or important to add, please send me a note and i'll add it.

#### why do we need a CVS?

when multiple developers work on the same source it is very likely that they simultaneously modify the same files. there needs to be some means of synchronization, merging the different branches back into the official source. you won't do this by hand.

#### how does it work, generally speaking?

the main source is hosted at sourceforge and it is called the "repository". when you decide to join the effort on the project, you must retrieve a copy of the source, formally called "checkout", just like a book from the library.

now you can work with your local copy of the source, make modifications to it, compile it, verify that it works as expected and add some documentation.

regularly you must synchronize the main source, so that your fellow developpers can use your new or improved code. this is done in two or - maybe - three steps:

- update your own local copy from the main source so that your local copy becomes the most up-to-date version of the source in the world. this process is called "update".
- if `cvs` tells you that it has encountered interfering changes in some files that can't be merged automatically, then you must manually work out the problems: you must edit all the problematic files and resolve all the problems. cvs has marked all locations very cleary in the source files.
- finally synchronize the main source from your local copy. this is called "commit".

note: if you can't resolve the problems after you have updated your local copy, you may well delete your local copy of the source discarding all your modifications so far. to reduce the probability of such an uncomfortable situation you should update your source right before you start work on it, thus incorporating all commits which were made in the past hours or days, and synchronize the repository every time you come to a safe state in your source modifications, which will not leave it unusable for others.

### how does it work for me?

obviously you need `cvs` installed on your computer to retrieve and hand back source from the repository. you hopefully already have the `cvs` command installed on your system. if not, slot-in your OS installer CD and install it.

it is required to log into the cvs server at sourceforge using the secure shell `ssh`. so you must also verify that you have installed the `ssh` command.

a comprehensive introduction to the `ssh` can be found on sourceforge's documentation page.

#### (1) your initial checkout of the source

cvs looks for some environment variables, which should be set before it is executed. you can also supply these values as command line parameters there are 3 environment variables to set.

if you use `bash` or something similar:

    localhost: export EDITOR=joe
    localhost: export CVS_RSH=ssh
    localhost: export CVSROOT=YOUR_NAME@cvs.vipsi.sourceforge.net:/cvsroot/vipsi

if you use the `csh`:

    localhost: setenv EDITOR  joe
    localhost: setenv CVS_RSH ssh
    localhost: setenv CVSROOT YOUR_NAME@cvs.vipsi.sourceforge.net:/cvsroot/vipsi

the EDITOR variable is only required for committing and you may have configured your system so that this variable is already set when you start a shell. set it to your favourite editor or you'll end up with `vi`, the default.

CVS_RSH tells your `cvs` that it must use the `ssh` for connections to the `cvs` at sourceforge. this variable is required in all operations.

CVSROOT tells your `cvs` the location of the repository. this is required only for the initial checkout. you can also supply this information directly to the `cvs` command with the `-d` option.

go to the directory where you want to settle your local copy of the source. it is also ok to retrieve it anywhere and copy the whole thing around on your harddisk.

checkout the source. vipsi's source tree is currently split into three subtrees:

    your_dev_root/
    your_dev_root/vipsi/                  <-- from project "vipsi"
    your_dev_root/vipsi/documentation     <-- from project "vipsi"
    your_dev_root/vipsi/libraries         <-- from project "lib-kio"

so, to checkout all sources do the following:

    bash$  cd YOUR_DEV_ROOT
    bash$  export CVS_RSH=ssh
    bash$  cvs -d:ext:YOU@cvs.vipsi.sourceforge.net:/cvsroot/vipsi checkout vipsi
    bash$  cvs -d:ext:YOU@cvs.vipsi.sourceforge.net:/cvsroot/vipsi checkout documentation
    bash$  cvs -d:ext:YOU@cvs.lib-kio.sourceforge.net:/cvsroot/lib-kio checkout libraries
    bash$  mv libraries vipsi/
    bash$  mv documentation vipsi/

now you have your own copy of the source and can work on it. don't touch the folders named CVS. they contain administrative files for `cvs` and must remain in the folders they reside in.

#### (2) update your local copy from the repository

instruct `cvs` to use the `ssh`, go to the directory which you want to update and do it:

    bash$  export CVS_RSH=ssh
    bash$  cd YOUR_DEV_ROOT/vipsi
    bash$  cvs update

`cvs` most times works on the current directory and retrieves most required informations from the data stored in the CVS folders. so in this case you only need to define CVS_RSH so that the `ssh` is used. perhaps some time they will store this in the CVS folders too.

there are some useful options to update which you may decide to use:

the option `-d` tells `cvs` that it shall create new subdirectories in your local source tree to match new directories in the repository. `cvs` does not create them by default! you must specify this option.

appending option `-P` has the opposite effect: if a subdirectory becomes empty after `cvs update`, then it is silently removed.

you may find it best to always include these two options:

    localhost: cvs update -dP

#### (3) resolve conflicts

when you update your copy of the source, `cvs` lists all files inspected and prepends them with a flag:

    cvs server: Updating .   info: cvs starts to inspect the current directory
    M value.cp               value.cp has been locally modified (by you)
    P value.h                value.h is updated in the cvs, patches were transferred
    U verrors.h              verrors.h is updated in the cvs, file was transferred anew
    C token.h                modified simultaneously in overlapping lines: collision!

you must edit the incriminated files, in the above example `token.h`, and work out the problems manually before you can commit your changes. differences are marked similarly to a diff output and look very prominent. working out the problems may be easy - or nearly impossible. you may decide to discard your changes and checkout the source anew, because you can't resolve the collissions. to reduce the probability of such an uncomfortable situation update your source regularly!

#### (4) synchronize the repository from your source

go to the directory which you want to commit back to the repository. then commit your source:

    bash$ export CVS_RSH=ssh
    bash$ cd YOUR_DEV_ROOT/vipsi
    bash$ cvs commit -m "add a comment about this commit here"

if you forget the comment or intentionally leave it out, `cvs` starts the editor as mentioned above for you to insert one. in this case it is better that you have the EDITOR variable set:

    bash$ export EDITOR=joe
    bash$ export CVS_RSH=ssh
    bash$ cd YOUR_DEV_ROOT/vipsi
    bash$ cvs commit

this will fire up the editor `joe` after you have entered the commit command.

#### (5) add files and directories

sometimes you must introduce new files into the source tree. `cvs` does not automatically add all files in the directories you commit to the repository. it only updates the files which it initially got with checkout. in fact, i have a lot more files around in vipsi's source tree, tests, docs and most notably intermediate files from the compiler. they are more or less ignored by `cvs`.

to add a file or directory to the repository, you must create it, add it to your local cvs and submit the change:

    bash$ export CVS_RSH=ssh
    bash$ cd YOUR_DEV_ROOT/vipsi
    bash$ cvs update
    bash$ mkdir testdir
    bash$ cvs add testdir
    bash$ cvs commit -m "it's a test only"

don't add directories just for fun - they cannot be removed from the cvs repository!

#### (6) delete files and directories

when you reorganize parts of your source it may also happen, that entire files or directories become obsolete. to remove a file from the repository, you first must delete it in your local tree (for security reasons), then remove it from your local cvs and finally submit the change:

    bash$ export CVS_RSH=ssh
    bash$ cd YOUR_DEV_ROOT/vipsi
    bash$ cvs update
    bash$ rm testfile
    bash$ cvs rm testfile
    bash$ cvs commit -m "it's a test only"

directories cannot be removed. the only thing you can do is to delete all files in it and use the `-P` option whenever you update your local source. the `-P` option prunes empty directories from your local copy, as told above.

#### (7) renaming files and folders

unluckily enough, this is also not supported by the `cvs`. instead, you must delete the old file and add it with the new name:

    bash$ export CVS_RSH=ssh
    bash$ cd YOUR_DEV_ROOT/vipsi
    bash$ cvs update
    bash$ mv oldname newname
    bash$ cvs rm oldname
    bash$ cvs add newname
    bash$ cvs commit -m "it's a test only"

because directories cannot be removed from the cvs, they cannot be "moved" this way either. all you can do is create a new directory and ignore the old one...

#### the Windows version

still working on that - i don't have Windows! maybe s.o. else will do this for me?