A CVS Repository for the RNB Group

Transcription

1 A CVS Repository for the RNB Group Anthony Villano September 5, 2008 Abstract With the large number of projects and varying editors/authors on certain works, it is useful to have a central repository for documentation, code, and simple images or figures. The CVS (Concurrent Version System) package provides such an environment and can be very useful for the group. A CVS repository has been set up on a computer resident at Notre Dame (einstein1.phys.nd.edu). All members of the group have access to this computer and therefore to the repositories. Requirements for Use The use of CVS requires that you have the package installed and that you have a working version of ssh installed. This document will describe how to use a typical UNIX installation with command-line input. There are several clients available for Windows but are not covered here, though the commands are mostly the same (the main difference is a graphical interface). Most UNIX or LINUX distributions including Mac s built on the UNIX- BSD core, have a distribution of both CVS and ssh already installed. One can download the source and get an introduction to the idea of CVS at: A valid UNIX distribution of ssh can be obtained at: The basic idea of a CVS repository is to centralize all the saved files in a given project and keep a copy of every revision of each file in the repository. This is achieved in an efficient way by CVS which cannot be matched by manual saving and renaming. A repository location is created (it can be local or remote and is in our case resident on einstein1.phys.nd.edu) and all other interactions with the repository are made through the CVS program. After the initial creation of the repository directory, it is therefore never necessary to modify the directory manually, but only through CVS commands. This is as long as CVS is working properly, which it typically does. Directories containing projects are place into the repository for the first time with a cvs import command. After directories are imported into the repository 1

2 the local version can be deleted 1. The cvs checkout command can then be used to request a local copy of a specific repository directory. After the local copy is edited as desired the cvs commit command can be used to lock the changes into the repository. This method allows many people to work on the same files simultaneously and with periodic cvs update commands one can keep up with the revisions of all users. Occassionally there are conflicts, and CVS lets the user know about these and the files are usually tagged, but most conflicts can be merged by CVS automatically. For these reasons the most useful types of files to archive in CVS are those which are or can be derived from text files. This system works beautifully for code and/or documents prepared with L A TEX. Other types of documents can be committed to the repository but CVS will deal with conflicts on these files less elegantly. One of the most attractive features of CVS is that for any project, one can retrieve past versions by version number or by date. Create Repository The first task in using CVS is to create a repository and make that repository visible in your UNIX environment (either local or remote). First make a directory named <cvs dir> in the path <cvs path>. The system now needs to have the path to the directory stored in the environmental variable named CVSROOT. This variable tells the CVS client commands which directory the repository is stored in and this directory can be either local or remote. Local: One simply needs to set CVSROOT by the following commands 2 : usr>cvsroot=<cvs path>/<cvs dir>/ usr>export CVSROOT On some systems one should use the next command instead of the previous one: usr>setenv CVSROOT <cvs path>/<cvs dir>/ Remote: One should set an environmental variable named CVS RSH in addition to the variable CVSROOT. The CVS RSH environmental variable tells CVS where the desired secure shell software is. usr>cvs RSH=<ssh path> usr>export CVS RSH usr>cvsroot=:ext:<username>@<server>:<cvs path>/<cvs dir>/ usr>export CVSROOT 1 What I like to do is first move the directory and confirm that the import was successful by checking out a copy, and only then deleting the original directory. 2 Using the text, usr> to represent the command prompt. 2

3 This, as above, may have to be done using the setenv command if that is how your shell environment is set up. After the environmental variables are set properly one can then simply execute the command: usr>cvs init You will be asked for your password to the server machine. The RNB repository is set up on the computer einstein1.phys.nd.edu at the directory /repositories/rnb/. It is set up so that everyone has permission to read and write to the directory. Therefore one can use their own username on that machine, I usevillaa. An example of the commands that would have set up that directory are (DO NOT run these commands now, the repository is set up already, try your own repository if you like): usr>cvs RSH=/usr/bin/ssh usr>export CVS RSH usr>cvsroot=:ext:villaa@einstein1.phys.nd.edu:/repositories/rnb/ usr>export CVSROOT usr>cvs init These commands must be run every time you use that CVS repository. If you use mostly one repository, like I do, you can set the environmental variables CVS RSH and CVSROOT in your shell initialization file so that it automatically executes whenever a shell is open. On my Mac this file is /Users/villaa/.profile. Import and Checkout There is now a central repository for file storage and update management. The first step in interacting with this repository is placing new files and directories in it for CVS control and actually checking out a local copy. The commands to do this are cvs import and cvs checkout with various options supplied to them. First the command for starting CVS version control on a set of files can be issued, this command is the cvs import command. It is typically used in any directory with all lower directories being placed into CVS. For example, suppose the full directory path for a directory with files and directories belonging to a specific project is called <project dir>. Further suppose one wants to use CVS version control with all files below this directory. The following commands can be issued: usr>cd <project dir> usr>cvs import -m "a descriptive note" <project cvs path> <vendor tag> start 3

4 The parameter <project cvs path> represents the path you want the newly imported directory to have in the CVS repository relative to CVSROOT. The parameter <vendor tag> is typically used to denote the creator of the program (e.g. in industry a vendor can tag all of its projects with some vendor name). This can be anything for repositories which do not contain the source code for a program that is proprietary, its good practice to use something consistent like a username or nickname for the project. This tag rarely comes up in checkouts and subsequent work with the repository. After a repository is created and a directory is imported, the original local copy can be discareded (though it is wise to keep a copy under a different name until one tests the checkout command). The checkout command can be issued by knowing the CVS path of the directory one wishes to work on or view, this has been called <project cvs path> in the previous paragraphs and will remain as such going forward. In order to check out a directory it must have been imported already. The checkout commands run as follows: usr>cvs checkout <project cvs path> One now has a fresh copy of the project as it looks in the repository as of the current date. There are serveral useful options which can be used with the checkout command, which allow one to observe the repository as it looked at a certain date or at a certain revision number. Commit To commit updated files to the repository one will simply need to move to the CVS controlled directory where the updated files reside. A simple command like: usr>cvs commit -m "comment" <file> will commit a single file named <file> to be updated, whereas the command: usr>cvs commit -m "comment" will commit the entire directory and all lower directories (recursive). The option -m allows one to place a descriptive comment in-line for storage with any updated file versions. If one does not use this option the command will put the terminal into the default text editor to store the comment. To check on the version and revision comments for a given file under CVS control one should issue the following command: usr>cvs log <file> 4

5 Update To update a given directory under CVS control to the most current version one can issue the following command: usr>cvs update If this command does not seem to be giving the most recent version of things one can always simply remove the local copy of the directory and check the CVS directory out again. Modules and Aliases Occasionally it is useful to have several CVS directories grouped together or have a shorter name for a given CVS directory. This can be accomplished by using the modules file. The modules file is a file which is included in all properly instantiated CVS repositories and stores information about groups of top level directories and/or short names for CVS repository directories. To set this up one must (for the first time only) edit a CVS administrative file manually on the machine which holds the repository. The file to edit is CVSROOT/modules relative to the CVSROOT top directory. This is the modules file which contains all nicknames and aliases that CVS uses, one must make it so that this file can be checked out and committed like any other file. When this is done, one will not have to manually edit the repository to change this file and add new modules. The following line should be added to the file after the comments: modules CVSROOT modules Once this line is added directly to the repository version of the modules file, it places that file under CVS control and allows it to be checked out and modified at any time either locally or remotely. Use the command cvs checkout modules to obtain a local copy of the modules file. This will place the file modules/modules relative to wherever you executed the command from. An example of a modules file looks like the following: Three different line formats are valid: key -a aliases... key [options] directory key [options] directory files... Where "options" are composed of: -i prog Run "prog" on "cvs commit" from top-level of module. -o prog Run "prog" on "cvs checkout" of module. -e prog Run "prog" on "cvs export" of module. -t prog Run "prog" on "cvs rtag" of module. 5

6 -u prog Run "prog" on "cvs update" of module. -d dir Place module in directory "dir" instead of module name. -l Top-level directory only -- do not recurse. NOTE: If you change any of the "Run" options above, you ll have to release and re-checkout any working directories of these modules. And "directory" is a path to a directory relative to $CVSROOT. The "-a" option specifies an alias. An alias is interpreted as if everything on the right of the "-a" had been typed on the command line. You can encode a module within a module by using the special & character to interpose another module into the current module. This can be useful for creating a module that consists of many directories spread out over the entire source repository. modules CVSROOT modules stdpaw paw thesis baryon_doc/dissertation thesis_arxiv baryon_doc/diss_small candidacy baryon_doc/candidacy script_test simc_script/ libutil -a avmath/ c_functions/ data_manip/ The comments in the above file show the basic operations possible. The example also shows the two commands I use most. Firstly lines like: stdpaw paw says that when a users asks to checkout stdpaw to give them the paw/ directory relative to the CVSROOT. In this case the local copy will have the directory name stdpaw/ but have the contents of the CVS top directory paw/. This is useful because sometimes directory names can be somewhat long and descriptive but you can give a shorter name for checkout purposes. The second type of lines that are typically used are basically groups of directories to be checked out at one time. For example a line like: libutil -a avmath/ c functions/ data manip/ will check out all the listed directories at the local directory where the command is executed. In this case the directories are not named by the alias libutil but retain their original names and are checked out as a package deal. Modifying and updating the directories which are aliased procedes in exactly the same way as before, CVS keeps track of all the names. If you 6

7 have a top level directory and an alias of the same name, CVS will checkout the alias version by default. Comments There are several good practices and cautionary comments that should be mentioned here. Do not import an already CVS controlled directory. CVS usually ignores any directories called CVS, but if it doesnt the import command will get stuck in a loop and there will be many copies of things unnecessarily stored in CVSROOT. Use the commit command to submit your changes. Be sure you are using the correct repository by checking the CVSROOT variable. This can be done by simply executing usr>echo $CVSROOT on most UNIX or LINUX based systems. Be patient when commiting changes. If you commit large amounts of changes (especially things like postscript files) it can take a reasonable amount of time. The way CVS manages things is that whenever someone is issuing a commit command it locks all files in the repository so that nobody else can commit. If you terminate the command after it locks all the files but before it unlocks them, it could cause someone to have to manually edit the repository to remove the locks by force. Include useful comments when commiting different versions. Keep all your local copies up-to-date. The reason for this is that if you make many changes and then find that the files were not up-to-date to begin with, there could be conflicts when you commit the changes. 7