%FDP-ENTITIES; ]> The Concurrent Versions System (CVS) provides a framework for collaborative revision. Without such a framework, a group of users editing files in a single directory would cause chaos. Using CVS, however, a group of people can safely work on the same set of files. The CVS server keeps the master copy of the files, and it records all changes and associated data, such as authors and time, in a central repository. If conflicts arise, CVS advises the users. Programmers often use CVS to share code, but it also works well for documentation. cvs

cvs how it works cvs overview In most cases, each set of files that make up a package or project is stored as a module on the CVS server. When working with files from CVS, you checkout a copy of the module on your local file system. After modifying one or more files, you commit them back to the central CVS repository server. With CVS you may edit a file without first getting permission or locking the file. As long as none of the changes overlap, CVS can correctly record their changes. When duplicate changes occur, they are clearly marked in the files and the authors must resolve the issue among themselves. When you commit changes, only changes to files the server knows about are committed. In other words, if you created a file in your local checkout of a module, the new file is not automatically uploaded to the server. You must add the file to the repository and then commit it. If you remove a file from your local checkout of a module, you must specify that you want to remove it from the repository on the CVS server and then commit the removal of the file. The specific commands to perform these actions are discussed in . If someone has modified the file between the last time you grabbed the file from CVS and when you try to commit a change, CVS will try to merge the changes into the master copy of the CVS server. If the content you changed is in a different location in the file than the content changed by someone else, the commit action will likely go through without a conflict. If someone modified the same content as the content you just changed and tried to commit, you will see a message that a file conflict has occurred. Thus, you need to update your files frequently. It is a good practice to update them right before you start modifying a file. Refer to for instructions on resolving conflicts.

cvs preparing for use Before using CVS, you need to establish an account with the CVS server. After you get an account, you do not need to perform these actions again.

cvs RPM installation You must have the CVS RPM package installed. Verify its presence by typing the command: rpm -q cvs If you see output similar to cvs-1.11.19-1, then the package is installed. A message similar to package cvs is not installed means you must install the cvs package before continuing. If you do not know how to do this, consult your system administrator who can install it for you.

OpenSSH authorization keys The CVS server uses SSH Protocol 2 keys to authenticate users. Thus, you need to generate a pair of keys before applying for a CVS account. If you already have an SSH DSA key, you may skip this step. You already have a DSA key if you have the file ~/.ssh/id_dsa.pub on the system. If your existing DSA key does not require a passphrase, you are strongly urged to generate one that does require a passphrase. Use the following steps to generate a DSA key used by SSH Protocol 2. It is required for an cvs.fedoraproject.org CVS account. OpenSSH ssh-keygen ssh-keygen To generate a DSA key to work with version 2.0 protocol, at a shell prompt, type the command: ssh-keygen -t dsa Accept the default file location of ~/.ssh/id_dsa. You are strongly urged to define and use a passphrase to enhance the security of your key. Enter a passphrase different than your account password and confirm it by entering it again. Copy your new key to the correct file by typing the following at a shell prompt. > ~/.ssh/authorized_keys]]> Check this command carefully before you press the Enter key. If ~/.ssh/authorized_keys already exists, the contents of ~/.ssh/id_dsa.pub will be appended to the end of the ~/.ssh/authorized_keys file. Change the permissions of your ~/.ssh directory and your keys with the commands: chmod 700 ~/.ssh chmod 644 ~/.ssh/authorized_keys You can have your system remember your passphrase so that you do not have to type it every time you access the CVS server. Refer to the documentation of the ssh-add program.

cvs configuring for access cvs CVSROOT cvs CVS_RSH CVSROOT CVS_RSH cvs .cvsrc .cvsrc

cvs avoiding repetitive typing Many CVS commands need certain command line switches to operate consistently. Rather than typing them every time that command is used, you can save the switches in a file that CVS will read before executing your command line. Create a file named ~/.cvsrc in your home directory. It should contain the following commands, one per line:

cvs configuring read-only access cvs anonymous access If your goal is to download the various &FC; documents and to render them on your system, you only need read-only access to the CVS repository. Follow the instructions in this section and then skip directly to . Change directories to where you want your files from CVS to be located, and execute the following commands: export CVSROOT=:pserver:anonymous@cvs.fedoraproject.org:/cvs/docs cvs login cvs checkout module-name cvs checkout module-name cd module-name Once you have checked the module out, the value of your $CVSROOT environment variable does not matter. It is stored in the file CVS/Root for each directory in your local repository. As long as your current working directory has a CVS/ directory, the CVS program will automatically locate the &FDP; repository.

cvs configuring read/write access cvs configuring access for authors To author a new document or to change an existing one, you must obtain full read/write access to the &FDP; CVS repository. For the full details on this process, refer to the http://fedoraproject.org/wiki/DocsProject/Join web site. Every author has a unique $CVSROOT to access the CVS repository: export CVSROOT=:ext:yourname@cvs.fedoraproject.org:/cvs/docs export CVS_RSH=/usr/bin/ssh With the $CVSROOT and $CVS_RSH environment variables in place, you can access the repository: cvs co -c You will be asked for the passphrase for your SSH key. Press Enter to receive a list of modules already in the repository.

cvs commands After configuring your system to work with CVS, checkout the modules you will be working on. To see if you need a correctly-set $CVSROOT variable, or the -m repository command line switch, see if you have a CVS/ subdirectory in your working directory. If you have a CVS/ directory, CVS ignores any $CVSROOT or -m command line switch.

cvs checking out modules You only need to checkout a module once. Once a local copy of the module is on your system, you may continue to use it for additional work. To checkout a module, use the following command: cvs co module-name For example, to checkout the example-tutorial module, change to your work directory, and execute the following command: cvs co example-tutorial A directory called example-tutorial/ is created in the current directory. If a branch name is not specified when checking out a module, it is referred to as the HEAD of the CVS module.

cvs check out modules checking out branches Think of a CVS branch as a version of the files for a particular version of a manual or package. To checkout a branch of a module, use the following command: cvs co -d directory -r branchname module-name A directory named directory is created, and the files for the branchname branch of the module-name module are copied in the directory. For example, to checkout a branch named BRANCH-VERSION-1.2 from the mymodule module, use the command: cvs co -d mymodule-1.2 -r BRANCH-VERSION-1.2 mymodule The BRANCH-VERSION-1.2 branch of the module is checked out in the mymodule-1.2 directory on your system. To determine which branches and tags exist for a file, use the command: cvs status -v filename For example, the status of the file foo.xml is as follows: Only tags marked as branches in the second column under the Existing Tags section can be checked out as a branch.

cvs updating files To retrieve the latest versions of the files in a module, change to the directory that contains the files for the module and execute the command: cvs update The latest versions of all the files in the module are downloaded into your local copy. If you notice a file conflict, refer to .

cvs committing files After modifying files in your local version of a module, commit them to save the changes on the CVS server: cvs commit -m "some log message" filename If you would prefer to write your log message with your favorite text editor, as defined by the $VISUAL or the $EDITOR environment variable, just omit the -m "some log message". The buffer will already contain comments describing the change. You do not need to delete them as you enter your own text. The log message should be as descriptive as possible so that you and anyone else working on the module understands what changed. Using a log message such as updated some files does not accurately describe what has changed and will not help you in the future. If you are correcting a bug, use the Bugzilla reference. The filename can be one filename, a series of filenames separated by spaces, or a group of filenames specified using wildcards such as *.png or foo-*.xml. If no filename or group of filenames is specified in the commit command, all outstanding changes of any kind are committed to the server. The command is recursive and will include changes in any subdirectories of the module. Use caution when issuing the commit command without any filenames because you might not remember exactly what files changed. If you notice a file conflict, refer to .

cvs adding files To add a file to a module, create the file in your local copy then execute the following command: cvs add file-to-add After adding the file, you must commit the add to copy it to the server: cvs commit -m "some log message" file-to-add

cvs binary files The most commonly-archived files are simple text files, but sometimes binary files are also archived. The cvs program recognizes most common filename extensions such as .png or .jpg, and usually behaves as the user intends. When a copy of a file is checked out of the repository, cvs scans it for special keywords such as $id:$. The cvs program replaces the keyword with a generated value such as the file version number. This keyword substitution usually corrupts binary files, so it must be turned off if cvs does not recognize your file as binary. To mark your file as being binary, and thus needing the keyword expansion turned off, use the command: cvs admin -kk filename Note that the file must already be checked in to the CVS repository before the admin command can be used. This is acceptable, since the keyword expansion is done as the file is checked out and copied to the local directory, not when the file is committed to the repository. If you check a binary file into the repository and then find it corrupted when it is checked out, do not panic. Use the admin command as described above, delete your local file copy, and check it out again.

cvs removing files If a file is no longer needed in the module, use the remove command to remove it from your local copy and then commit the removal to the server. Even though the file is removed from current version of the module, an archived copy is still kept on the server and can be retrieved at any time with the add command. cvs rm -f file-to-remove After removing the file, you must commit the removal: cvs commit -m "some log message" file-to-remove You can not use wildcards in the commit command to identify removed files. They must be specified with a exact filename. If you need to rename a file, it is best to rename the file on the CVS server so that the history of the file is preserved. If you need to rename a file, send an email to cvsdocs-administrator@fedoraproject.org asking to have the file renamed.

cvs status of files Sometimes it is necessary to view the status of a file in a CVS module. To view the status of a file, use the command: cvs status filename The status report of a repository file is as follows: Up-to-date Your revision of the file is identical to the latest revision on the CVS server. Locally Modified You have updated to the latest revision from the server, but then you modified the file on your system. Locally Added You added the file with the cvs add command but have not yet committed the addition of the file. Locally Removed You removed the file with the cvs remove command but have not yet committed the removal. Needs Checkout A newer version of the file is on the server and needs to be retrieved. Even though the status includes the word checkout, it really means that you need to update your files with the cvs update command. Needs Patch The revision in your local checkout needs a patch to be the latest revision from the server. Issue the cvs update command to resolve. Needs Merge A newer revision exists on the server and your local version contains modification not yet committed. This status usually occurs if you don't have the latest revision of the file and edit it anyway. File had conflicts on merge Similar to Needs Merge, except when you tried to issue the cvs update command, the differences could not be resolved automatically. Refer to for more information on resolving conflicts. Unknown The CVS server does not know anything about this file. It has neither been added nor removed locally and has never been committed to the server. This status usually occurs for files you should not commit to CVS such as generated-index.sgml or for files that you want to add to the repository but have not yet issued the cvs add command.

cvs resolving conflicts If you modify a file and the same region is modified by someone else and committed first, you will probably see a message similar to the following when committing the file or updating your local copy of the module: To resolve the conflict, open the file, search for and determine which version of the content is correct. For example: Some sentence. <<<<<<< filename.sgml A sentence that was changed in the working copy. ======= A same sentence that was changed differently and committed. >>>>>>> 1.13 ]]> The content between the , and the ======= is the content from your working copy. The content between the ======= and the >>>>>>]]> is the content from the server. Resolve the conflict by editing your copy, and commit the file.

cvs commands summary of All commands assume you are in the proper directory for the CVS module. Command Description cvs checkout <module-name> or cvs co <module-name> Creates a directory called <module-name> with the contents of the module in the directory cvs co -d <directory> -r <branchname><module-name> Creates the <directory> directory with the contents of the <branchname> branch of the <module-name> module cvs update or cvs up Update your files with the latest files from the CVS server cvs add <filename> Add a new file "filename" to the CVS server cvs commit -m "My message" <filename> Update file <filename> with the latest copy from your computer cvs log <filename> View the commit messages for the file <filename> cvs status <filename> View status of the file, such as Locally Modified cvs status -v <filename> View existing tags and branches for file cvs diff <filename> Show diff of the working copy of the file and the latest version of the file for the branch cvs diff -r1.1 -r1.2 <filename> Show diff of version 1.1 and 1.2 for file For more information, read the CVS manual available on your system at /usr/share/doc/cvs-<version-number>/cvs.ps (the CVS version might vary) and visit the CVS webpage available at http://www.cvshome.org/. Since CVS is using ssh to connect to the CVS server, you will be prompted your password before performing your CVS request. If you want to configure your machine so that you do not have to enter a password, refer to the &RHEL; Deployment Guide for details about using ssh-agent.