TODO: Add stuff about binary vs. text files. TODO: The section on setting up a repository. TODO: Section on creating a new project. TODO: Short CVS command summary. This document describes how to use CVS on CAEN Linux and Unix servers. CVS stands for "Concurrent Versions System," and it is a version control system that can be used to: * Allow multiple programmers to share files in a programming project * Keep a history of all versions of your source code * Keep your source code on a safe server in case your PC crashes This document contains several sections: * "Basic Concepts of CVS" describes some terms you need to know to use CVS. * "Using CVS" describes how to use CVS to manage the files in your project. * "Setting Up A Repository" describes how to set up a CVS repository. If you are working in a group, all of the members in your group need to read the "Basic Concepts" and "Using CVS" sections. Only one group member needs to set up the repository, which is described in "Setting Up A Repository". BASIC CONCEPTS OF CVS CVS keeps the files in your project in a central location called the "repository". There is only one repository for a project (though a repository may have multiple projects), and the repository is shared by all of the programmers working on the project. Each programmer uses CVS to copy the current versions of the project files to her own working directory (typically in her AFS space). After working on the project, the programmer will tell CVS to load her changed copies into the repository, making her versions the new current versions of the project files. There are four CVS commands that you need to know to use CVS effectively. Two are commands that you will use frequently: "update" and "commit"; two are commands that you will use only when you have a new project or you have added a new file to your project: "checkout" and "add". Before we describe the syntax of the commands, it is important that you understand conceptually what each of them does. Update: The "update" command tells CVS to copy the most current versions of files in the shared repository to your working directory. Note that this is a little couter-intuitive: "update" means "update my local directories with whatever is current in the repository"; it does NOT mean "update the repository." Commit: The "commit" command tells CVS to load whatever changes have been made to the files in your working directory into the repository. Your versions of the project files become the current project versions when you use the "commit" command. Checkout: The "checkout" command is used to get the current project files for the first time because the project does not exist at all on your workstation. If you use a CAEN workstation for your programming, you will probably use the "checkout" command once each time you begin working on your project on a new workstation. If you use your own PC for programming and have CVS configured there (using CVS on your own PC is NOT described in this document), you might only use the "checkout" command one time during the life of a project. Add: The "add" command tells CVS that you are adding a new file to the project. When you create a new file that has not previously been part of your project, you need to use the "add" command before you can use the commit command to put the file in the repository for the first time. USING CVS SETTING THE REPOSITORY LOCATION To use CVS, you first need to know the location of the repository in which your project is stored. Typically this will be in the AFS space of someone in your project group. Whichever group member created the project in CVS should be able to tell you the location of the repository. In this example, we'll suppose that the repository is in "/afs/engin.umich.edu/u/u/n/uniqname/cvs". For the rest of this document after this section, we will assume that you have either used an alias (how to do this is described in this section) or set the CVSROOT environment variable so that you may use "cvs" instead of the more lengthy "cvs -d " to run CVS commands. If you have not aliased the "cvs" command (described shortly) or set the CVSROOT variable (not covered in this document), each time you use a CVS command, you must begin the command with: cvs -d In our example, this would be: cvs -d /afs/engin.umich.edu/u/u/n/uniqname/cvs To avoid typing all of this repeatedly, you can alias the CVS command by running the command: alias cvs cvs -d (replace with the correct location of your repository). You can add this line to your .cshrc file so that it will be done every time you log on. If you work with multiple CVS repositories (because you have more than one class with group projects), you could create multiple commands, such as: alias cvs280 cvs -d /afs/engin.umich.edu/u/a/b/abuser/cvsrepository alias cvs281 cvs -d /afs/engin.umich.edu/u/c/d/cduser/cvs281 With these aliases, you could use the commands "cvs280" and "cvs281" to access two different repositories. (But you must then be careful to use the "cvs280" or "cvs281" command everywhere that the "cvs" command is normally used in the rest of this document.) Another way to tell CVS your repository location is to set the CVSROOT environment variable. This document will not describe how to do this. If you know how to do it, CVS automatically looks for the repository location in the CVSROOT variable if you do not specify a location with the "-d" option. GETTING THE PROJECT FILES FOR THE FIRST TIME If you do not already have the project in a local directory, you first need to use the "checkout" command to get the project files for the first time. You need to know the name of the project in CVS to do this; whichever member of your group created the project should tell you the name. We'll assume here that your project is named "proj1". Go to a directory where you want to keep your projects, and use the command: cvs checkout proj1 (If you have not aliased the "cvs" command, you'll need to use the long form "cvs -d checkout proj1" to do this.) The "checkout" command will create the "proj1" directory in your current directory and copy all of the current versions of the project files from CVS into the newly created "proj1" directory. WORKING ON THE PROJECT AND COMMITTING CHANGES To work on your project, use the editor or IDE of your choice to work on the files. When you have reached a point that you want to add your changes to the CVS repository, you typically run the command: cvs commit -m "" from the project directory (in our example, the "proj1" directory). This normally adds your changes to the CVS repository. There are two special situations in which your changes may not be added without some additional work: "commit" will not automatically add new files to your project, and "commit" may fail for a file if someone else has already committed other changes to the file. The "-m" flag and the empty quotation marks in the "commit" command above tell CVS not to attach a message to your versions of the files. If you forget this option, the commit command will automatically present a screen for you to edit a message to attach to the files. If this happens, you can exit that screen by typing ":q" (don't type the quotation marks - just type the colon, the letter "q", and press ). CVS will ask you if you want to abort or continue - type "c" to continue and press . CVS will run the commit command and put your changes into the repository. ADDING NEW FILES When you add a new file, you must use the CVS "add" command to tell CVS that you want to include the new file in the project, and then use the "commit" command to put the file in the repository. If you are not sure if you've added a new file, run this command: cvs -n update (The "-n" flag tells CVS to report on the files without actually updating anything.) If any files are listed with a question mark to the left of their name, those are files that you need to add. To add a single file named "file1.cpp", use the command: cvs add file1.cpp To add all new files in your project directory that are not yet in CVS, use the command: cvs add * After you add a new file, you must still use "commit" to put the current version of the file in the repository. CONFLICTS WHEN COMMITTING CHANGES When you commit changes to CVS, you may encounter a "conflict", which means that someone else has changed a file in a way that CVS cannot merge the changes together automatically. A safe way to resolve a conflict is to follow this procedure: * In this example, suppose the conflict is in "file1.cpp". * Run the command: "cvs update -C file1.cpp". This command will do two things: first, it will rename your changed version of "file1.cpp" to ".#file1.cpp.1.1" (the "1.1" part may be different); second, it will get the current version of "file1.cpp" from the repository. * Edit "file1.cpp" to add your changes to it again. You can look at the file ".#file1.cpp" to see your changes. * Commit your changes. Unless someone has changed it since you started this procedure, there should no longer be a conflict. GETTING THE LATEST FILES FROM CVS To get the latest versions of files from CVS, run the command: cvs update The "update" command will get the latest versions of your project files from CVS. If there is a conflict, CVS will update the file in your directory by adding some delimiting text to show you where the conflict occurred. You must edit the file to resolve the conflict. AVOIDING CONFLICTS The best way to avoid conflicts is to commit and update often. You should commit and update whenever you reach a point where you have completed a unit of work that can added to the repository without breaking any existing code. For example, you might commit and update if you finish adding a method or two to one class. As a guideline, try to commit and update at least once per hour while you are working. Experienced programmers often commit and update every few minutes to avoid conflicts and make sure that their team always has access to the latest code. You can see if a conflict exists without committing any of your changes or updating any files in your directory by running an update command with a "-n" flag to indicate that you want to view the results of the update without actually updating anything: cvs -n update (IMPORTANT: make sure you specify the "-n" before the "update"; it has a different meaning when specified after "update".) This command will list files where there are differences between your versions and the current versions in the repository, like this: C file1.cpp M file3.cpp ? file4.cpp The letter to the left of each filename tells you its status: C = Conflict - there is a conflict that you will need to resolve M = Modified - your version has been modified and needs to be committed U = Update - your version is out-of-date and needs to be updated from the repository ? = New file - this file has not yet been added to CVS with "cvs add" and is not in the repository A = Add - this file has been added with "cvs add", but is not in the repository; you need to commit it