3. CVS Overview and Concepts

Here, in words, is how CVS works. You create a special directory (called a CVS "root" directory) that you never, ever work in directly. Think of it as a repository of your "master copies" of any projects that you've placed under CVS control.

The master copy of a particular project (kept in a CVS root directory) is referred to as the project archive in this howto. One never works directly with an archive, but rather accesses it only via cvs commands. This archive is a lot more than just a "copy" of the current working snapshot of a project. It actually contains the information required to reconstruct all the variants of the project files that were ever committed to the archive, with contemporaneous log documentation, timestamps, and more.

Using cvs commands, you check a working copy of a project out from its archive, update any or all of the files in the working copy, edit or otherwise change them, test them, and eventually commit the changes back to the archive (documenting what you have done in the process). You can do anything you want to the working copy without affecting the archive unless/until you commit the changes. You can have several working copies out at the same time and work in each in turn. You and somebody else can each have their own working copies out and work (each on their own copy) at the same time.

By only working on the actual archive and root via CVS commands, you protect yourself against many of the slings and arrows of outrageous fortune. This may seem cumbersome if you are not used to it, but in fact it is all very easy and can even be largely automated by Clever Tricks, some of which are given below.

3.1 Filesystem Constructs

As we just saw, there are three basic filesystem constructs underlying CVS:

• The CVS "root" directory. CVS roots typically fall into two classes: your "default" CVS root where you put all your personal projects and one CVS root directory per separate shared project or project group for projects that involve others.
• A working directory (tree). This is created (usually) before the CVS archive of the project, although it may be created as a mere project skeleton before putting the whole thing under CVS control and subsequently working with it via CVS commands.
• The CVS archive directory (tree) for a particular project. This is located within a CVS root directory. Human hands should only rarely need to touch files in this directory, and only then if they are expert hands.

The next section will tutorially focus on setting up these filesystem constructs.

3.2 Setup Steps.

To use CVS (initially) you typically perform the following steps:

• You create a CVS root directory just once for your personal projects and once per group for shared projects.
• You create an initial project working directory (for new projects) or unpack and/or clean up an existing working directory.
• You "put the working directory into CVS" as a CVS archive, temporarily move the original working directory (for safety) and "check out" a new copy of the working directory from CVS.
• You verify that all project documents made it into the archive and are present in the working directory. They are now "CVS controlled" and have a revision number associated with them, a logged revision history begun (empty), and can be manipulated in various ways with "CVS commands".

3.3 Work Cycle

From this point on a typical project work cycle will be either (for personal documents):

• Change to the (CVS controlled) working directory. If necessary or desired, update your working sources from the last commited changes.
• Edit or otherwise make changes to the local copies you have of the project documents in the working (CVS controlled) directory and save the work.
• "Commit" the changes to the CVS archive whenever you have reached a suitable point. This will REQUIRE that you document the changes made since the last commit.
• "Tag" all the project sources whenever you reach a suitable point. This will usually be the point where you would reasonably bump the entire project's "revision number" and permits you to retreive the entire project as of its state as of the last commit with a single command.

or, for shared projects:

• Change to the (CVS controlled) working directory.
• Always begin by updating your copy of the project sources in the (CVS controlled) working directory from the currently commited CVS archive. Remember, other people might have made changes to the documents you are about to work on since you last udpated, and if you work on an old version you are more likely to create conflicts that must be resolved later on!
• Edit or otherwise make changes to the local copies you have of the project documents in the working (CVS controlled) directory and save the work in the working directory.
• "Commit" the changes to the CVS archive whenever you have reached a suitable point. This will REQUIRE that you document the changes made since the last commit. This is especially important for shared projects, as your documentation will be what others will read to have some idea of what has been done by whom as the document evolves.
• "Tag" all the project sources whenever you reach a suitable point. This will usually be the point where you would reasonably bump the entire project's "revision number" and permits you to retreive the entire project as of its state as of the last commit with a single command, and, in a shared project, is probably done only by the project manager.

That's pretty much it. Although CVS has many, rich, powerful commands for sophisticated manipulation of complex projects, most people just don't need most of them most of the time. This mini-howto will concentrate on getting you through just enough of the CVS commands that you can accomplish these work cycles for personal or shared projects. If and when you need to do something that is above and beyond this list, you will need to consult the actual CVS manual(s):

• man cvs
• On a linux system, a typeset, printable postscript version of the CVS manual is often to be found in e.g. /usr/share/doc/cvs-some-number/cvs.ps