Section C.1. Usage Questions | Essential CVS (Essentials)

C.1. Usage Questions

These are the everyday questions about the basic use of CVS, collected in one small section for easy reference. These are not "how do I use CVS at all" questionsthose are answered in the quickstart guide. Rather, these answers provide useful combinations of commands, or CVS tips and tricks.

C.1.1. Creating Projects and Sandboxes

The very first step to successfully using a tool such as CVS is putting your files in it. So the questions about that are answered first.

C.1.1.1. How do I start a new project?

See "Importing Projects" in Chapter 2 (the quickstart guide) or "Creating a Project" in Chapter 7.

C.1.1.2. How do I avoid using a vendor tag and a release tag when I import?

There's no need to do so. When I know I won't be using them, I use a1 and b2 for the tagnames, and ignore them once I've finished using the import command. There's nothing special about a1 and b2, by the waythey're simply legal and meaningless names. You can use fred and ginger, or bert and ernie if you want.

C.1.1.3. How do I list all the projects in a repository?

If you have CVS 1.12.8 or later, you can use the easy method to see which directories are in the top level of the repository:

 cvs -d repository-path rls .

If there are any modules defined, you can list those with:

 cvs -d repository-path checkout -c

There's a discussion of this topic at the end of "Creating a Sandbox," in the "Sandboxes and Repositories" section of Chapter 3.

C.1.1.4. How do I check out all the projects in a repository?

You can check out all the projects in the repository with:

 cvs -d repository_path checkout -d whatever .

You'll need patience, particularly if it's a large repository. This command will install sandboxes for all the projects in the local directory whatever. If you have modules defined, you must check them out separately.

C.1.1.5. How do I get a checkout that doesn't have all that CVS administrative stuff?

The command you're after is cvs export. It's explained in "Exporting Files" in Chapter 7.

C.1.1.6. How do I check out only one file?

The checkout command takes, as parameters, a module name or the name (relative to repository root) of any file or directory in the repository. So you just need to specify the file name and pathfor example, cvs -d repository_path checkout /path/to/file/filename.

C.1.2. Using Sandboxes

Sandboxes are the most visible aspect of CVS, so there are quite a few questions about them. Answers here include an explanation of locks, and quite a few tips and tricks.

C.1.2.1. How do I tell whether there are files in the repository that I haven't checked out? How do I tell which files in my sandbox I haven't committed?

The least spammy method that I know of is to use cvs update with the -n CVS option and the -d command option, as in cvs -n update -d. The -n prevents CVS from actually modifying your sandbox, and the -d tells update to check for directories that are new to the sandbox.

You can also use cvs status, or in newer versions, cvs ls or rls. All of these commands are explained in Chapter 3.

C.1.2.2. How do I clear stickiness?

Stickiness, what it is, and how to clear it is explained in the section "Stickiness" in Chapter 4.

C.1.2.3. What does "move away (file), it is in the way" mean?

You see this message when CVS is trying to modify your sandbox. It happens when CVS needs to add a file with a particular name, but there's already a file of that name in the sandbox.

C.1.2.4. How do I rollback or uncommit?

This is explained in Chapter 3 in the section "Retrieving Past Revisions of a File." Take special note of the subsection "Reverting changes."

C.1.2.5. How do I recover deleted files?

This is also explained in Chapter 3, in the sections "Retrieving Past Revisions of a File" and "Retrieving Removed Files."

C.1.2.6. What is the Attic?

The most complete explanation of the Attic is in "Repository Structure," in Chapter 6. There is also a brief explanation in the section "Removing Files from the Repository" of Chapter 6.

C.1.2.7. How do I view changes since a particular date? What about between two dates?

Depending on what sorts of changes you want to see, you can use the commands cvs diff, cvs log, or cvs history. The diff and log commands are explained in "Comparing File Revisions" and "Displaying File History" in Chapter 5, and the history command is explained in the "Tools" section of Chapter 7.

These commands also permit you to specify two dates and see the changes that occurred between those dates.

C.1.2.8. How do I view a list of all the files with a given tag?

Use the cvs option -n in combination with update (or checkout) to produce a list but not actually change your sandbox. Then use -r tagname to specify the files with that tag. Your command would be something like cvs -n update -r tagname.

C.1.2.9. How do I find out which tag was set on a given date, or on what date a given tag was created?

The cvs log command provides both the tagname and the date for each revision of a file. It is explained in "Retrieving Past Revisions of a File" in Chapter 3, and "Displaying File History" in Chapter 4. For this purpose, you probably want to restrict its output to certain dates or certain revisions.

C.1.2.10. How do I retrieve a particular revision when I only know which date the revision was on?

This looks like a job for cvs log! Retrieve the log information for the date you want, and browse the log messages, tagnames, and other information until you've found the revision number or tagname you need. For further information on cvs log, see "Retrieving Past Revisions of a File" in Chapter 3, and "Displaying File History" in Chapter 4.

C.1.2.11. What is locking all about?

There are three different types of locking that are relevant to CVS. The first, repository locks, are internal to CVS and usually won't affect users. The other two forms are ways to help multiple developers work on the same file. The three methods of collaboration that CVS supports are explained in Chapter 5, in "Using Simultaneous Development," "Watching a File," and "Reserving Files."

Repository locks: These are internal to CVS, and are how CVS prevents itself from trying to read a file which is being changed, or worse, write to it while it's being changed. Users should only ever see the message explained in "Lock Files" in Chapter 3. Repository administrators may need to read the section on "Clearing Locks" in Chapter 6. These locks are fully explained in "Locks" in Chapter 6.
Locks in the advisory exclusive development model: The section "Watching a File" in Chapter 5 explains how to signal that a file is yours to edit, and that everyone else should leave it alone. It also explains how to be notified when someone else has signaled that a file is theirs: by watching it. A lock in this sense doesn't really lock the file; it simply puts a metaphorical bright red sticker on it saying "this is mine, go away."
Locks in the exclusive development model: Instead of a metaphorical red sticker, it's possible to actually prohibit another person from committing a file you've claimed as yours. This is the third sense of locking and is explained in "Reserving Files" in Chapter 5.

C.1.2.12. How do I lock files so that only I can commit them?

This is the exclusive development model, which is not CVS's native method of working. CVS can do it, however, and it's explained in "Reserving Files" in Chapter 5.

C.1.3. Using Branches

No aspect of CVS seems to cause as much confusion as branches. The questions in this section range from how to merge, to how to resurrect a deleted branch.

C.1.3.1. How do I lock a particular branch so no one can commit to it?

Write a script that takes the commitinfo parameters, tests whether the attempted commit is to the branch in question, and returns a nonzero value if it is. You then add this script to the commitinfo scripting file. You can find examples of commitinfo scripting files that affect permissions in the cvs_acls or rcslock scripts described in Appendix B. The scripting files are explained in Chapter 7.

C.1.3.2. How do I get the history of all files in a particular branch?

Use cvs log or cvs diff for this purpose. Try using cvs log with the -r branch-base-tag:: option, or diff -s or diff brief with -r branch-base-tag -r branch-tag.

C.1.3.3. How do I check out multiple branches of a project?

Use a different sandbox for each branch. You can create a sandbox with a sandbox root name different from the project name by using the -d command option:

 cvs -d repository_path checkout -r branch-tag -d new-sandbox-root-name

C.1.3.4. How do I merge from branch to trunk, or trunk to branch?

See the section "Merging Branches" in Chapter 4.

C.1.3.5. How do I avoid fixing the same conflicts over and over when I merge branches?

In "Merging Branches" in Chapter 4, I mention that it's good practice to tag when you've merged, and to do the next merge from that tag rather than from the root of the branch. The reason for this is to avoid fixing the same conflicts multiple times.

C.1.3.6. How do I remove a branch?

Please don't! But if you feel you must, see the section "Deleting or Moving a Branch" in Chapter 4.

C.1.3.7. How do I branch a branch? Why would I want to?

See the section "Nested branches" in Chapter 4.

C.1.3.8. How do I recreate a deleted branch tag?

Very, very painfully. Larry Jones describes the process in this archived email: http://lists.gnu.org/archive/html/info-cvs/2004-02/msg00306.html. Derek Price has suggestions as well, in the email: http://lists.gnu.org/archive/html/info-cvs/2004-02/msg00309.html.

The essence of their method requires you to follow this process for each file in the tagless branch:

Run cvs log on the file to get a list of revision numbers.
Identify which revision number should have the deleted branch tag.
Use cvs admin -n to relink the tagname to the branch.

The section "Branch Revision Numbers" in Chapter 4 will help you identify the revision number for your branch.

C.1.4. Managing Projects

Project managers have problems all their own. From managing common files for multiple projects to sending emails automatically on commit, there are always issues which make a given project unique.

C.1.4.1. How do I make a patch?

This is explained in "Making Patchfiles" in Chapter 7.

C.1.4.2. How do I make CVS support symbolic links?

You don't. CVS isn't designed to store pseudofiles such as symbolic links. Instead, put the creation of the symbolic links into your build script.

C.1.4.3. How do I import vendor upgrades directly to a branch?

This is explained in "Vendor Branches" in Chapter 7.

C.1.4.4. How can I share common files between projects?

The best way I'm aware of is to use modules. See "Project Structure and Sandboxes" and "The modules File" in Chapter 7.

C.1.4.5. How do I send emails automatically?

Use a script in one or more of the scripting files to send the mail. Choose the scripting file that runs at the time you want the mail sent: for example, use commitinfo or loginfo for commits, or postwatch for watch notifications. See "Scripting Files" in Chapter 7 and the activitymail script in Appendix B.

You can also use the watch family of commands for some emails if you want to allow your users to determine which files they are emailed for. See "Watching a File" in Chapter 5.