ResearchSubscriptionsCVS < CF

CF Web>CscfSpecific>ResearchSubscriptions>ResearchSubscriptionsCVS (2006-01-27, EladLahav) (raw view)
---+ CVS

-- Main.EladLahav - 25 Nov 2005

%TOC%

---++ Preamble

CVS is an easy to use, yet powerful and effective version control system. It is based on a client-server architecture that stores all files in a common place, thus allowing several people to collaborate on a project.

---++ Terminology

Common terms used by CVS:
   * _Repository_: A collection of file and directory revisions managed by CVS. A repository is stored on the server-side.
   * _Module_: A project managed by CVS. A module is simply a directory in a CVS repository.
   * _Tree_: A snapshot of a module stored on the client-side.
   * _Root_: A string containing the access method, user name and path leading to a CVS repository.
   * _Import_: Populating a newly created module with files.
   * _Checkout_: The process of creating a tree in a work directory.
   * _Update_: Synchronising a tree so that it reflects the current state of the repository.
   * _Commit_: Synchronising a tree so that changes in the work directory are applied to the repository.

---++ CVS Life Cycle

Working with CVS usually involves the following stages:
   1 Create a module in the repository and import files into it.
   1 Create (check-out) and maintain (update) a tree in a work directory.
   1 Work on your tree.
   1 Transfer (commit) your changes.

We shall assume that a repository was already created and that it is accessed only through rsh/ssh. The root will be

   <verbatim>
   :ext:elahav@hopper:/u3/elahav/cvsroot
   </verbatim>

where =:ext:= means that the repository can only be accessed using rsh, =elahav= is the user name, =hopper= is the server on which the repository resides and =/u3/elahav/cvsroot= is the path to the repository.

   $ *Note*: To use ssh instead of rsh, set the environment variable =CVS_RSH= to =ssh=.

Every CVS command has the following form:

   <verbatim>
   cvs CVS_OPTIONS COMMAND COMMAND_OPTIONS
   </verbatim>

Most CVS commands work recursively, which means they are applied to all sub-directories.

---+++ Import

The import process creates a new module in the repository. The module is populated with all files in the current directory. The command has the following syntax:

   <verbatim>
   cvs -d ROOT import MODULE_NAME VENDOR_TAG START_TAG
   </verbatim>

where =ROOT= is the repository's root string, =MODULE_NAME= is simply the name of the module, and VENDOR_TAG and START_TAG are arbitrary symbols.

   $ *Note*: You can get rid of the =-d ROOT= part by setting the =CVSROOT= environment variable to the root string.

   $ *Note*: The vendor and start tags are just relics from old times. You can safely use the strings VENDOR and START for every module you create.

Assume =~/src/myproject= is a directory containing the files to import. The following commands create the module =myproject= in the repository

   <verbatim>
   cd ~/src/myproject
   cvs -d :ext:elahav@hopper:/u3/elahav/cvsroot import myproject VENDOR START
   </verbatim>

Alternatively, we can use the =CVSROOT= environment variable:

   <verbatim>
   export CVSROOT=:ext:elahav@hopper:/u3/elahav/cvsroot
   cd ~/src/myproject
   cvs import myproject VENDOR START
   </verbatim>

Since CVS works recursively, all sub-directories and their files will also be imported.

---+++ Checkout

The checkout command creates a tree by copying the latest version of all files in a module into a the current directory. Its basic syntax is:

   <verbatim>
   cvs -d ROOT co MODULE_NAME
   </verbatim>

Checkout can also create the tree in a specified directory:

   <verbatim>
   cvs -d ROOT co -d DIR MODULE_NAME
   </verbatim>

For example, to check out the =myproject= module in the current directory

   <verbatim>
   cvs -d :ext:elahav@hopper:/u3/elahav/cvsroot co myproject
   </verbatim>

or, if =CVSROOT= has already been set correctly

   <verbatim>
   cvs co myproject
   </verbatim>

This command creates a directory called =myproject= under the current directory, populated with the module files (including all sub-directories). Each directory in the tree has a CVS sub-directory, which contains such information as the name of the module, its root and the files in this directory that are included in the module.

Once the module has been checked out, you can work on the files in the tree directory. This will not affect the repository in any way.

   $ *Note*: There is no concept of "locking files" in CVS (as opposed to e.g., RCS).

---+++ Update

While working on your local tree, some changes may occur in the repository. For example, someone else may have changed some files, or even you may have done so from another tree (for instance, when working from your home computer). It is therefore advisable to update the tree as often as possible. Maintaining an updated tree will reduce the risk of conflicts that arise when several people are changing the same code.

To update the entire tree, simply move to the tree's top-most directory, and issue the command

   <verbatim>
   cvs up
   </verbatim>

For example, in order to update the =myproject= tree kept in =~/src=, run the commands

   <verbatim>
   cd ~/src/myproject
   cvs up
   </verbatim>

The tree is update recursively, so there is no need to issue the command again for each sub-directory. Note, also, that you do not need to specify the root in the update command, as the =CVS= sub-directory contains a =Root= file that is read automatically.

One can also update any sub-directory of the tree, by changing to that directory and running the =cvs up= command.

When CVS updates the tree, it outputs the names of any modified files and indicates their status. This status is given by any of the following letters:

   * *U*: This file was not in your tree, and was fetched from the repository.
   * *P*: The file exists in your tree, but had to be patched in order to update it to the latest version.
   * *M*: The file in your tree contains local changes (that were not yet committed to the repository).
   * *C*: The file was changed both locally and in the repository, resulting in conflicts. Conflicts need to be resolved manually.
   * *?*: A local file is not part of the module (you can ignore this message).

---+++ Commit

Once your changes were made and tested, you are ready to incorporate them into the repository. This is done using the command

   <verbatim>
   cvs commit FILE1 FILE2 FILE3 ...
   </verbatim>

This command requires you to explicitly provide the names of the modified files you would like to commit. Once the command is issued, an editor session will begin, which you can use to write a log entry describing the changes made to these files. If you want a different log message for each file, you need to run the =commit= command separately. The files are committed once you save the contents and quit the editor (e.g., using =wq= in Vi). Note that lines in this file beginning with "CVS" are comments, and are not saved as part of the log entry.

   $ *Note*: You can skip the editor session by supplying the log entry with the =-m= switch, e.g.,

   <verbatim>
   cvs commit -m "This is my informative log entry" hello.c hello.h
   </verbatim>


---+++ Add/Remove Files

If you add files to your tree, and would like these files to also be added to the module, use

   <verbatim>
   cvs add FILE1 FILE2 FILE3 ...
   </verbatim>

Similarly, to remove files from the module use

   <verbatim>
   cvs remove FILE1 FILE2 FILE3 ...
   </verbatim>

None of these changes take effect until you issue a =commit= command including these files.

For example, to add =foo.c= and =bar.h= to =myproject=, issue the commands

   <verbatim>
   cvs add foo.c bar.h
   cvs commit foo.c bar.h
   </verbatim>

---++ GUI Clients

While CVS is pretty simple and can be easily operated from the command line, it is sometimes more convenient to use a GUI client instead. Here are some suggestions of clients available for different environments:

   * [[http://www.lincvs.com/][LinCVS]] is a multi-platform client for Windows, Mac OS X and Linux.
   * [[http://www.wincvs.org/][CvsGui]] have different clients (the Mac OS and Linux clients are somewhat outdated).
   * [[http://cervisia.sourceforge.net/index.html.new][Cervisia]] is a very good client that is distributed as part of KDE.

---++ More Help

To learn more about the CVS command line options, use

   <verbatim>
   cvs --help
   </verbatim>

or

   <verbatim>
   cvs -H COMMAND
   </verbatim>

for details on the specific commands (such as =import=, =co=, =up=, =commit=, etc.). Under Unix, the =man= command should give you more details.

Documentation is available on the CVS main [[http://www.nongnu.org/cvs/][website]] and in [[http://www.network-theory.co.uk/docs/cvsmanual/index.html][this]] manual.

---+ The Subscription Website and CVS

---++ Repository Information

   $ Repository: =asimov.cscf:/projects/research/cvsroot=
   $ Module: =sub=
   $ Access method: SSH (=:ext:=)

---++ Versioning Scheme and Tags

We follow a _Major_. _Minor_ versioning scheme for production versions. For ecample, the current version number is 3.0, the next minor changes (bug fixes and small features) will appear in version 3.1, and the next overhaul will result in version 4.0.

Before a version is released for production, it undergoes a Release Candidate (RC) phase, during which it is publicly tested. Release candidate versions have the same number as the future production version, with -RC _N_ appended, where _N_ denotes the current revision. For example, the first release candidate for version 3.0 is 3.0-RC1, the second is 3.0-RC2, etc. Once a release candidate has been approved to be of production quality, the RC number is dropped, and the version is moved as-is to the production directory.

CVS tags for the production versions follow the scheme =V_Major_Minor=. Thus version 3.0 is associated with the CVS tag =V_3_0=. For release candidates, the suffix =_RCN= is added, e.g., =V_3_0_RC4= for the fourth release candidate of version 3.0.


---++ Deploying a New Version

We keep three folders under the Research Subscription website:

   1 Development (=subdev=)
   1 Release candidate (=subRC=)
   1 Production (=sub=)

The =subdev= directory always points to the =HEAD= version of the CVS tree, while =subRC= and =sub= contain tagged versions. Deploying a new version is therefore only a matter of updating the relevant directory. For example, to upgrade the RC directory to version 3.0-RC2, use:

<verbatim>
research$ export CVS_RSH=ssh
research$ cd subRC
subRC$ cvs up -r V_3_0_RC2
subRC$ ./fixperm
</verbatim>

(note that the =fixperm= script needs to be called to set the correct permissions for the different files.)

Similarly, the following commands upgrade the production version to 3.1:

<verbatim>
research$ export CVS_RSH=ssh
research$ cd sub
subRC$ cvs up -r V_3_1
subRC$ ./fixperm
</verbatim>

Usually =sub= and =subRC= should not be modified in any other way. However, if, for some reason, a new =sub= or =subRC= directory need to be created, the code should be checked out from the CVS repository, and the files =.options= and =.rtoptions= should be copied into the new directory. (These two files contain user-configurable information, and are therefore not part of the CVS module. They can be fetched from a backup of the old =sub= or =subRC= directory.)

In the following example, a new subRC directory is created:

<verbatim>
research$ export CVS_RSH=ssh
reseacrh$ cvs -d :ext:elahav@asimov.cscf:/projects/research/cvsroot co -r V_3_0_RC1 -d subRC sub
research$ cd subRC
subRC$ cp .snapshot/nightly.0/.options .
subRC$ cp .snapshot/nightly.0/.rtoptions .
subRC$ ./fixperm
</verbatim>
Topic revision: r6 - 2006-01-27 - EladLahav
Information in this area is meant for use by CSCF staff and is not official documentation, but anybody who is interested is welcome to use it if they find it useful.
Other Webs
My links
- People
- CERAS
- WatForm
- Tetherless lab
- Ubuntu Main.HowTo
- eDocs
- RGG NE notes
- RGG
- CS infrastructure
- Grad images
Edit