3.3. Committing Changes to the Repository
Files are edited in the sandbox, but changes to the sandbox have no effect on the repository until they are committed. The cvs commit command uploads changes from the sandbox to the repository. After determining which files need to be changed in the repository, cvs commit opens an editor and expects you to enter a log message.
The syntax of cvs commit is:
cvs [cvs-options] commit [command-options] [filename]
cvs commit has only a few options, the most useful of which are:
Example 3-3 shows a typical cvs commit. The vertical ellipsis denotes the point at which CVS normally calls the editor. Example 3-4 shows the default text displayed in the editor and the log message for this commit. Figure 3-4 shows the Pharmacy graphic client just before a commit.
Example 3-3. Using cvs commit
Example 3-4. Entering log messages for cvs commit
Figure 3-4. Commit with Pharmacy
By default, cvs commit operates recursively on the current working directory. It can also take files or directories as parameters and operate recursively on them.
Use either of the following variations of cvs commit to avoid having to enter a message during the commit process:
cvs commit -m message
cvs commit -F filename
Examples 3-3 and 3-4 show a recursive commit, which commits files not only in your current working directory, but also in all subdirectories. If you want to commit only the current working directory (sometimes called the local directory), use cvs commit -l.
3.3.1. Setting Revision Numbers
You can use the -r option of cvs commit to set every file currently being committed to a specific revision number. This option is not used often; if it is used, it's usually by the project lead. The option changes the most recent revision number on the current line of development of all files being committed, regardless of whether they've changed in the sandbox. The revision number must be higher than any number currently in the repository, and it must be in the same format as the existing revision numbers for the files.
3.3.2. When to Commit
If your changes will not affect anyone else, commit frequently. Commit every time you'd hate to have to redo your work. Frequent commits keep your work in a single place for backup. If you are working in a team, frequent commits and updates reduce the chance of having to do a major, difficult merge.
If your changes will affect others, especially in a way that risks breaking the build, commit every time the effect will be negligible. For example, run a test-compile before lunch and before you leave, and commit if it compiles.
Don't ever work for long without committing. If a full day's work doesn't compile, wrap comment tags around your changes and commit the commented-out code or consider committing to a branch. Always speak to your project manager before branching.
There are several different work styles and commit strategies possible with CVS. Your project manager may have a different commit strategy than the one mentioned here; if so, follow that. Chapter 7 discusses commit strategies in more detail.
3.3.3. Checking File Status
The cvs status command is a quick way to determine which files are up to date and which need to be committed or merged.
Files that have not been added to the repository are prefixed with a question mark. Files stored in CVS are shown with the filename, the current status, the working (or sandbox) revision, the revision currently stored in the repository and its location in the repository, and the sticky state of the file. Stickiness is explained in Chapter 4.
The syntax of cvs status is:
cvs [cvs-options] status [command-options] [filename]
The status command has only three options:
Example 3-5 shows the CVS status report for the wizzard.h file. Figure 3-5 shows the TkCVS graphic client display for this book, at the time I'm writing this, including displays of the status, last modified date, and revision level.
Example 3-5. Output from the cvs status command
Figure 3-5. TkCVS status display
A file may be in one of the following states:
There are three error states:
Note that the revision number shown in the status (and other places) is the CVS internal revision number; it has nothing to do with the version number that a file or project may have outside of CVS.