Harvard-MIT Data Center | Providing tools, resources, and support for analyzing data.

Working with CVS in the RCE Summer 2009

Working with CVS in the RCE Summer 2009

Guide Overview

This guide helps you to use the Concurrent Versions System (CVS) version control system to record and track files and their changes in the RCE. (See CVS Basics for general information.) CVS enables you to collaborate on the use and management of source files among multiple users. Information included in this guide consists of:

Setting up to use CVS
Updating files from a repository
Committing (saving) files to a repository
Adding files to and removing files from a repository
Working with CVS on the command line

Note: Before you can use CVS, you must connect successfully to the RCE. Refer to Connecting to the RCE Summer 2009 for detailed information about how to connect.

Before You Begin

Before You Begin

Remember when you use CVS that other users might have changed your shared files in the time since you checked out the repository or last committed your changes to the repository. If you do not update your CVS work directory before you begin editing files, you risk working on out-of-date files.

Also remember that the first time you connect to the CVS server, you must change your assigned password and complete an account contact form. If you do not complete this form, you are prompted to complete it each time you issue a command to the CVS server. Refer to Accessing the RCE Classic for information about changing your password and completing the form.

Setting Up to Use CVS

Setting Up to Use CVS

If you have existing repositories checked out, and you edited files but did not commit your changes to CVS, using the menu option Checkout Repositories will overwrite your edited files. Be sure to commit any changes before you use this menu option to check out a new repository.

To set up your RCE environment to use CVS:

Connect to the RCE. For details, refer to the guide Connecting to the RCE Summer 2009. Note that you must change your assigned password before you can use CVS.
Choose one of the following menu options:
- Select the Applications menu in the RCE, select the RCE Utilities submenu, and then choose the option CVS Checkout Helper.
- Right-click on your desktop or in a file browser window, select the Scripts option, select the CVS submenu, and then choose the option Checkout Repositories.
  
  Do not use the option Open Scripts Folder at any time.
In the Enter Password window, type your <login account password>, and then click OK.
In the Select desired repositories window, click the check box for each repository that you choose to check out, and then click OK.

The directory /cvswork is created in your home directory, and each repository you selected is created under that as a subdirectory.
In the message window, click Yes to open a file browser and terminal window in the /cvswork directory and exit the checkout helper.

Click No to exit the checkout helper without opening any tools.

Details to Setting Up

Details to Setting Up

Before you begin working on shared files managed through CVS, you first set up your RCE environment and create a copy of a CVS repository to your environment. You can set up your environment by using either of the following menu options:

Applications menu, RCE Utilities submenu, Checkout Repositories option
Right-click menu Scripts option, CVS submenu, Checkout Repositories option

If you have existing repositories checked out, and you edited files but did not commit your changes to CVS, using this menu option will overwrite your edited files. Be sure to commit any changes before you use this menu option to check out a new repository.

To check out a repository from CVS:

Connect to the RCE.

For complete information about how to connect to the RCE, refer to the guide Connecting to the RCE Summer 2009.

Note: The first time you connect to the RCE and each time you connect to a new server in the RCE, you must change your assigned password and complete an account contact form. If you do not complete this form, you are prompted to complete it each time you log in to the server. This includes the CVS server.
Choose one of the following menu options:
- Select the Applications menu, RCE Utilities submenu, and then choose the option Checkout Repositories.
- Right-click on your desktop or in a file browser window, select the Scripts menu, select the CVS menu, and then choose the option Checkout Repositories.
The Enter Password window is displayed (Figure 1).

Figure 1. Enter Password Window
Type your <login account password> and then click OK to start the check out process.

When the script has determined to which CVS repositories you have access, a window prompts you to select the desired repositories to check out (Figure 2).

Figure 2. Please Select Desired Repositories Prompt

If you click Cancel the helper script terminates without setting up your environment.
Click the check box to select each repository that you choose to check out, and then click OK.

When the helper script completes the set up, the directory /cvswork is created in your home directory, and each repository you selected is created under that as a subdirectory. A window prompts you to continue (Figure 3).

Figure 3. Check Out Complete Prompt
Click Yes to open a file browser and terminal window in the /cvswork directory (Figure 4) and exit the check out helper.

Figure 4. File Browser and Terminal Window in CVS Directory

Click No to exit the check out helper without opening any tools.

Image(s):

Updating Files from CVS

Updating Files from CVS

To update your local working directory from the CVS repository:

In a file browser, move to a repository folder. Right-click and select the Scripts option, select the CVS submenu, and then choose the option Update This Repository.
In the Enter Password window, type your <login account password>, and then click OK.
In the confirmation prompt window, click OK to complete the update process.

Details to Updating Files

Details to Updating Files

Each time you start work on files managed through CVS, update the files before you start working. Also update your copy of the repository if you think anything in your local directory is missing or does not look correct, such as the time stamp on a file.

Perform the following:

In a file browser, move to a repository folder. Right-click and select the Scripts option, select the CVS submenu, and then choose the option Update This Repository.

The Enter Password window is displayed (see).

If you are not in a CVS repository folder when you right-click, you see an error message that indicates the folder is not a valid repository.
Type your <login account password>, and then click OK.

A confirmation prompt window is displayed (Figure 5).

Figure 5. Update Confirmation Prompt
Click OK to complete the update process.

Image(s):

06WorkInCVS.gif

Committing (Saving) Files to CVS

Committing (Saving) Files to CVS

To commit your local copy of a file to the CVS repository:

In a file browser, right-click the file or files that you choose to commit, select the Scripts option, select the CVS submenu, and then choose the option Commit Changes.
In the Enter Password window, type your <login account password>, and then click OK.
In the Enter Log Message window, enter a comment to identify your saved changes. Then click OK.
In the confirmation prompt window, click OK to complete the commit process.

Details to Committing Changes

Details to Committing Changes

After you edit existing files in your copy of a CVS repository, you commit (save) the changed files from your work directory to the CVS repository by using the command cvs commit. Be sure to use the option -m to include a log message describing your changes.

Be sure to perform an update before you change and then commit any files.

Perform the following to commit (save) changed files to the repository:

In a file browser, right-click the file or files that you choose to commit, select the Scripts option, select the CVS submenu, and then choose the option Commit Changes.

The Enter Password window is displayed.
Type your <login account password>, and then click OK.

The Enter Log Message window is displayed (Figure 6).

Figure 6. Enter Log Message Window
Type a comment to identify your changes, and then click OK.

A confirmation prompt window is displayed (Figure 7).

Figure 7. Commit File Confirmation Prompt
Click OK to complete the commit process.

Note: If you did not perform an update before you started work on a shared file, and another user committed a changed version of that file to the repository since you updated your copy of it, you see a warning message similar to the following:

Up-to-date check failed for '<filename>'.

You must update your CVS work directory with the new version of that file and then enter your changes again to the new file.

Image(s):

07WorkInCVS.gif

08WorkInCVS.gif

Adding New Files to CVS

Adding New Files to CVS

For information about how to add a directory to CVS, see Details to Adding New Files.

Perform the following to add a new file to the CVS repository:

In a file browser, right-click the file or files that you choose to add, select the Scripts option, select the CVS submenu, and then choose the option Add Files.
In the Enter Password window, type your <login account password>, and then click OK.
In the confirmation window, click OK to commit the added file to the repository.

Click No to exit the add process without committing your changes.
In the confirmation prompt window, click OK to complete the added file commit process.

Details to Adding New Files

Details to Adding New Files

Before you can use the command cvs commit to save a new file to the repository, you must use the command cvs add to add that file to CVS control. When needed, use the option -kb to add a file in binary format. Files that contain either document formatting or graphics require you to use the binary format option to prevent data corruption.

Do not add to CVS any derived files, such as .gcg, .lcg, .o, or other binary files complied from sources. Do add to CVS the source files and makefiles used to create derived files.

Adding a File to CVS

Perform the following to add a file to the CVS repository:

In a file browser, right-click the file or files that you choose to add, select the Scripts option, select the CVS submenu, and then choose the option Add Files.

The Enter Password window is displayed.
Type your <login account password>, and then click OK.

An added files commit prompt window is displayed (Figure 8).

Figure 8. Added File Commit Prompt
To commit the added file to the repository, click OK. If you choose not to commit your files to CVS at this time, click No at the commit prompt.

A commit confirmation prompt window is displayed (Figure 9).

Figure 9. Commit Confirmation Prompt
Click OK to complete the added file commit process.

Workflow for Adding a Directory to CVS

If you plan to add a number of related files and choose to organize those files in a directory, use this workflow:

Add the directory to CVS control.
Add the files in that directory to CVS control.
Commit the files in your directory to CVS.

Note that you do not have to commit the directory to CVS after you add it, but you cannot add your files to CVS until you add the directory.

Image(s):

09WorkInCVS.gif

10WorkInCVS.gif

Removing Files from CVS

Removing Files from CVS

Perform the following to remove one or more files from a CVS repository:

In a file browser, right-click the file or files that you choose to remove, select the Scripts option, select the CVS submenu, and then choose the option Remove Files.
In the Enter Password window, type your <login account password>, and then click OK.
In the warning window, click OK to remove the files from the repository.

Click No to exit the remove process without deleting your files.

Details to Removing Files

Details to Removing Files

To remove a file from a CVS repository:

Perform the following to remove one or more files from a CVS repository:

In a file browser, right-click the file or files that you choose to remove, select the Scripts option, select the CVS submenu, and then choose the option Remove Files.

The Enter Password window is displayed.
Type your <login account password>, and then click OK.

A Warning window is displayed (Figure 10), listing the files that you selected to remove.

Figure 10. Remove Files Warning
In the warning window, click Yes to remove the files from the repository.

Click No to exit the remove process without deleting your files.

Image(s):

11WorkInCVS.gif

Working with CVS on the Command Line

Working with CVS on the Command Line

This section describes how to use CVS commands in the CLI. You can use the menu options to do most of the same tasks.

To execute CVS commands from the CLI, right-click your RCE desktop and choose the option Open Terminal.

Setting Up Manually

Setting Up Manually

To check out a CVS repository from the command line:

Connect to the RCE.

For complete information about how to connect to the RCE, refer to the guide Connecting to the RCE Summer 2009.

Note: The first time you connect to the RCE and each time you connect to a new server in the RCE, you must change your assigned password and complete an account contact form. If you do not complete this form, you are prompted to complete it each time you log in to the server. This includes the CVS server.

To start the HMDC script to set up your environment to use CVS, right-click the RCE desktop and select the option Open Terminal to open a terminal window. Then type the command cvshelper.

The system prompts you to enter a number corresponding to one or more repositories to which you have access. For example:

vnc-1:<username> [~]>cvshelper
Please select the desired repository from the list provided.
Select option 0, "FINISHED", when you have finished selecting
repositories.
To deselect a previously selected repository, select it again.

You have not yet selected any repositories.

Repositories available:
0) FINISHED
1) docs
2) gkbibtex

Choose (0-2):

Type the number of a repository to check it out of CVS, and then press Enter.

The system notifies you of the repository that you selected.
```
Please select the desired repository from the list provided.
Select option 0, "FINISHED", when you have finished selecting
repositories.
To deselect a previously selected repository, select it again.

You have selected the following repositories:
docs

Repositories available:
0) FINISHED
1) docs
2) gkbibtex

Choose (0-2):
```
If you choose to check out another repository to which you have access, type the corresponding number and press Enter. Continue doing this until you have selected all the repositories that you choose to check out.
When you finish selecting all repositories that you choose to check out, type "0" and press Enter to complete the CVS checkout process.

The system notifies you that the repositories are checked out and available for you to use.
```
*****************
Your selected repositories are being checked out. Please be patient.
*** Checking out repository docs...done

The following repositories have been checked out into
/nfs/fs1/home/<First Initial>/<username>/cvswork:
docs
vnc-1:<username> [~]>
```
The script creates the directory /cvswork in your home directory, and then creates a subdirectory for each repository that you check out. This example indicates that the directory ~/cvswork/docs contains a copy of all files in the CVS docs repository.

You now can create new files or edit existing files in a repository. To view the contents of a repository, type cd ~/cvswork/<repository> and then type ls.

If the script returns any warnings or errors and does not exit with a statement that specifies the repositories you selected were checked out, repeat this process by executing the cvshelper script again. Also, if the ~/cvswork directory or subdirectories for each of your selected repositories do not exist or do not contain any files, execute the cvshelper script again. If you continue to have problems, contact us.

Updating Files Manually

Updating Files Manually

Perform the following:

In a terminal window, change to your CVS work directory:
```
login:<username> [~]>cd ~/cvswork
```
Update your source files by typing the command cvs update.

Include the options -dP to download new directories from the repository and to remove (prune) empty directories from your work directory:
```
login:<username> [~/cvswork/<repository name>]>cvs update -dP
<username>@cvs.hmdc.harvard.edu's password:
```
Type your <login account password> and press Enter to continue.

CVS downloads the current repository files to your local work directory, and lists the steps performed:
```
<username>@cvs.hmdc.harvard.edu's password: <login account password>
cvs update: Updating .
U <filename1>
U <filename2>
U <filen....>
```
If the system response includes an entry in the form M <filename>, you have a more current version of a file in your local copy of the repository than the CVS repository has. This indicates that you changed the file since the last time you updated or checked out the repository.

You now can create new files or edit existing files. To view the updated contents of a repository, type cd ~/cvswork/<repository> and then type ls.

Committing File Changes Manually

Committing File Changes Manually

Be sure to perform an update before you change and then commit any files.

Perform the following to commit (save) changed files to the repository:

In a terminal window, type cd ~/cvswork to change to your work directory.
Type the following command on one line:
```
login:<username> [~/cvswork/<repository name>]>cvs commit -m "<comment>" 
<filename>
<username>@cvs.hmdc.harvard.edu's password:
```
Note: If you do not include -m "<comment>" when you commit a file to the repository, CVS invokes a text editor automatically for you to add a comment. See Adding Comments Using emacs Editor or Adding Comments Using vi Editor for information about using a text editor to enter a comment during the commit process.

Type <login account password> and press Enter to continue.

<username>@cvs.hmdc.harvard.edu's password: <login account password>
Checking in <filename>;
/CVS/<repository name>/<filename>,v <-- <filename> 
new revision: <new version number>; previous revision: <old version number>
done

Up-to-date check failed for '<filename>'.

You must update your CVS work directory with the new version of that file and then enter your changes again to the new file.

Adding a New File Manually

Adding a New File Manually

Before you can use the command cvs commit to save a new file to the repository, you must use the command cvs add to add that file to CVS control. When needed, use the option -kb to add a file in binary format. Files that contain either document formatting or graphics require you to use the binary format option to prevent data corruption.

Determining the Need to Specify Binary Format

If you add a binary-format file to CVS control and do not specify the option -kb, your file can become corrupt or unusable during future commit processes.

Use the following guidelines to determine if you need to use the the binary format option with the command cvs add:

Text format (default) - Any text-only, non-formatted files, such as .txt, .c, .h, .pl, .tex, .sty, .bst, .bib, .R, and so on
Binary format - Formatted documents and image files, such as .pdf, .doc, .xls, .jpg, .gif, and so on

Adding a File from the Command Line

Perform the following to add a file to the CVS repository:

In a terminal window, type cd ~/cvswork to change to your work directory.

Type the following command:

login:<username> [~/cvswork/<repository name>]>cvs add <-kb> <filename> 
<username>@cvs.hmdc.harvard.edu's password:

Type <login account password> and press Enter to continue:

<username>@cvs.hmdc.harvard.edu's password: <login account password>
cvs add:scheduling file '<filename>' for addition 
cvs add: use 'cvs commit' to add these files permanently

Commit the new file to the CVS repository:

login:<username> [~/cvswork/<repository name>]>cvs commit -m â€œAdded new filesâ€ <filename>
<username>@cvs.hmdc.harvard.edu's password:

Type <login account password> and press Enter to continue.

<username>@cvs.hmdc.harvard.edu's password: <login account password>
<filename> initial revision: 1.1
done
RCS file: <filename>,v
done
Checking in <filename>;
/CVS/<repository name>/<filename>,v <-- <filename> initial revision: 1.1
done

Removing CVS Repositories Manually

Removing CVS Repositories Manually

You can copy or move a file out of your CVS directories before you delete the repository. If you delete a repository and check out the same repository again, then move your file back in to that subdirectory, CVS recognizes the file name and marks that file as changed locally.

To remove a repository and all of its contents from your local environment, perform the following:

To remove one repository and keep other CVS files intact, open a terminal window and change to the cvswork directory:
```
> cd ~/cvswork
```
To remove all repositories, open a terminal window and remain in your home directory.
Type the following command to remove a repository and all contents:
```
> rm -rf <directory>
```
Use this command with caution. All files are deleted from the specified directory when you execute this command.

Exiting a CVS Session

Exiting a CVS Session

After you commit all changes to CVS, type exit in your terminal window to end the session on the CVS server.

Implementation Details

Implementation Details

This appendix describes the implementation of CVS supported by HMDC for use in the RCE.

CVS Basics

CVS Basics

CVS records and tracks the history of source files and documents used by one or more persons, and maintains a central repository of these files. Each user checks out or updates files needed from a central repository, works on those files, and then commits (saves) their changes to the repository to make those changes available to other users. CVS tracks all changes made to files and who made them. For advanced users, CVS enables you to retrieve older versions of files from the repository, and to combine or merge multiple file versions into one.

CVS Terminology

Terms used in this guide to describe CVS activities include the following:

Repository - In CVS, a repository is the master version of all files for a specific branch of CVS. You copy a repository to your local environment, and you save files to the repository from your local environment.
Check out - When you copy a repository to your local environment, you use the check out process to write the current version of a CVS directory to your local directory. This process tells CVS that you have a version of the files in your environment, and enables CVS to track your work when you save your files to the repository.
Update - After you check out a repository, you copy changed versions of repository files to your local environment by using the update process. This tells CVS to compare your local version with the repository and copy to your environment any files that are more current than your local copy.
Commit - To save your changed files to the repository and enable other users to access your changes, you use the commit process.

CVS Setup Script and Commands

The HMDC setup script, cvshelper, includes a help file. To see information about this script, type the following command: cvshelper â€“-help.

For detailed information about other CVS commands and tools available for use in the RCE, refer to CVS Tool Reference Summer 2009.

Adding Comments Using emacs Editor

Adding Comments Using emacs Editor

If you do not include the option -m "<comment>" when you commit a file to the repository, CVS invokes a text editor automatically for you to add a comment.

If your RCE is configured to use emacs as the default text editor, the window shown in Figure A.1 is displayed.

Figure A.1. The emacs Editor

Perform the following:

Type your comment.
Select the File menu Save (current buffer) option to save your comment.
Select the File menu Exit Emacs option to exit emacs and commit your change to the CVS repository.

For more information about how to use the emacs editor, refer to the guide Working with CVS in the RCE Summer 2009.

Image(s):

12WorkInCVS.gif

Adding Comments Using vi Editor

Adding Comments Using vi Editor

If you do not include the option -m "<comment>" when you commit a file to the repository, CVS invokes a text editor automatically for you to add a comment.

If your RCE is configured to use vi as the default text editor, the window shown in Figure A.2 is displayed.

Figure A.2. The vi Editor

Perform the following:

Type "i" to enter Insert mode.
Enter your comment.
Press the Esc key.
Type :wq to save your comment, exit vi, and commit your change to the CVS repository.

Image(s):

01WorkInCVS.gif