Next: , Previous: Accessing A Repository, Up: A Day With CVS

Starting A New Project

If you're learning CVS in order to work on a project that's already under CVS control (that is, it is kept in a repository somewhere), you'll probably want to skip down to the next section, "Checking Out A Working Copy." On the other hand, if you want to take existing source code and put it into CVS, this is the section for you. Note that it still assumes you have access to an existing repository; see Repository Administration if you need to set up a repository first.

Putting a new project into a CVS repository is known as importing. The CVS command, as you may have guessed, is

     floss$ cvs import

except that it needs some more options (and needs to be in the right location) to succeed. First, go into the top-level directory of your project tree:

     floss$ cd myproj
     floss$ ls
     README.txt  a-subdir/   b-subdir/   hello.c

This project has two files – README.txt and hello.c – in the top level, plus two subdirectories – a-subdir and b-subdir – plus some more files (not shown in the example) inside those subdirectories. When you import a project, CVS imports everything in the tree, starting from the current directory and working its way down. Therefore, you should make sure that the only files in the tree are ones you want to be permanent parts of the project. Any old backup files, scratch files, and so on should all be cleaned out.

The general syntax of an import command is

     floss$ cvs import -m "log msg" projname vendortag releasetag

The -m flag (for message) is for specifying a short message describing the import. This will be the first log message for the entire project; every commit thereafter will also have its own log message. These messages are mandatory; if you don't give the -m flag, CVS automatically starts up an editor (by consulting the EDITOR environment variable) for you to type a log message in. After you save the log message and exit the editor, the import then continues.

The next argument is the project's name (we'll use "myproj"). This is the name under which you'll check out the project from the repository. (What actually happens is that a directory of that name gets created in the repository, but more on that in Repository Administration.) The name you choose now does not need to be the same as the name of the current directory, although in most cases it usually is.

The vendortag and releasetag arguments are a bit of bookkeeping for CVS. Don't worry about them now; it hardly matters what you use. In Advanced CVS you'll learn about the rare circumstances where they're significant. For now, we'll use a username and "start" for those arguments.

We're ready to run import:

     floss$ cvs import -m "initial import into CVS" myproj jrandom start
     N myproj/hello.c
     N myproj/README.txt
     cvs import: Importing /usr/local/cvs/myproj/a-subdir
     N myproj/a-subdir/whatever.c
     cvs import: Importing /usr/local/cvs/myproj/a-subdir/subsubdir
     N myproj/a-subdir/subsubdir/fish.c
     cvs import: Importing /usr/local/cvs/myproj/b-subdir
     N myproj/b-subdir/random.c
     No conflicts created by this import

Congratulations! If you ran that command (or something similar), you've finally done something that affects the repository.

Reading over the output of the import command, you'll notice that CVS precedes each filename with a single letter – in this case, "N" for "new file". The use of a single letter on the left to indicate the status of a file is a general pattern in CVS command output. We'll see it later in checkout and update as well.

You might think that, having just imported the project, you can start working in the tree immediately. This is not the case, however. The current directory tree is still not a CVS working copy. It was the source for the import command, true, but it wasn't magically changed into a CVS working copy merely by virtue of having been imported. To get a working copy, you need to check one out from the repository.

First, though, you might want to archive the current project tree. The reason is that once the sources are in CVS, you don't want to confuse yourself by accidentally editing copies that aren't in version control (because those changes won't become part of the project's history). You want to do all of your editing in a working copy from now on. However, you also don't want to remove the imported tree entirely, because you haven't yet verified that the repository actually has the files. Of course, you can be 99.999 percent certain that it does because the import command returned with no error, but why take chances? Paranoia pays, as every programmer knows. Therefore, do something like this:

     floss$ ls
     README.txt  a-subdir/   b-subdir/   hello.c
     floss$ cd ..
     floss$ ls
     floss$ mv myproj was_myproj
     floss$ ls

There. You still have the original files, but they're clearly named as an obsolete version, so they won't be in the way when you get a real working copy. Now you're ready to check out.

Karl Fogel wrote this book. Buy a printed copy via his homepage at

copyright  ©  November 12 2019 sean dreilinger url: