Section 3.3. Committing Changes to the Repository

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.

"Choosing Your Editor," earlier in this chapter, explained how to change the default editor.

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:

-f

Force a commit even if there are no changes to the file. (This option implies -l as well.)

-l

Perform a local, nonrecursive commit operation on the current working directory only.

-R

Perform a recursive commit operation on all subdirectories, as well as the current directory (default).

-m message

Provide a log message.

-F filename

Provide a log message from the specified file.

-r revision

Set an updated revision number (not recommended for novice users).

When you need to record important information in the log for a particular file (or files), use the -f option to force CVS to commit those files even if they're unchanged.

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

 /home/jenn/cvs/wizzard$ cvs commit cvs commit: Examining . cvs commit: Examining doc cvs commit: Examining lib cvs commit: Examining man cvs commit: Examining src . . . RCS file: /var/lib/cvs/wizzard/src/main.c,v done Checking in src/main.c; /var/lib/cvs/wizzard/src/main.c,v  <--  main.c initial revision: 1.1 done RCS file: /var/lib/cvs/wizzard/src/wizzard.h,v done Checking in src/wizzard.h; /var/lib/cvs/wizzard/src/wizzard.h,v  <--  wizzard.h initial revision: 1.1 done /home/jenn/cvs/wizzard$ 

Example 3-4. Entering log messages for cvs commit

 Added main.c: parses parameters and calls functions in other files. Added wizzard.h: defines compile-time global variables. CVS: ------------------------------------------------------------------ CVS: Enter Log.  Lines beginning with 'CVS:' are removed automatically CVS: CVS: Committing in . CVS: CVS: Added Files: CVS:  src/main.c src/wizzard.h CVS: ------------------------------------------------------------------ 

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 

or:

 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.

Use cvs status or cvs -n update to find out which files need to be updated or committed.

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.

CVS developers recommend you use tags to track revisions, and leave the internal revision numbers as CVS sets them by default. Chapter 4 explains how to use tags.

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:

-l

Perform local, nonrecursive operation on this directory only.

-R

Perform recursive operation on all subdirectories, as well as the current directory (default).

-v

Use verbose mode (display information about tags as well).

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

 ===================================================================== File: wizzard.h             Status: Up-to-date    Working revision:    1.5    Repository revision: 1.5     /var/lib/cvs/wizzard/src/wizzard.h,v    Sticky Tag:          (none)    Sticky Date:         (none)    Sticky Options:      (none) 

Figure 3-5. TkCVS status display

A file may be in one of the following states:

Up-to-date

The file in the sandbox is synchronized with the file in the repository.

Needs Checkout

The file does not exist in the sandbox; it exists only in the repository.

Needs Patch

The file in the sandbox has not been modified, and the file in the repository is more recent. The sandbox file needs to be patched using cvs update in order to be brought up to date with the repository.

Unresolved Conflict

The repository copy and the sandbox copy cannot be merged. This status occurs when you have a file in the sandbox with the same name as a file in the repository, but which you did not receive from the repository.

Locally Added

The file in the sandbox has been added, but the addition has not been committed.

Locally Removed

The file in the sandbox has been removed, but the removal hasn't been committed.

File had conflicts on merge

There is a known conflict between the file in the repository and the file in the sandbox.

Locally Modified

The file in the sandbox has been modified but not committed.

Needs Merge

The file in the repository does not match the file in the sandbox and both files have new data. The files need to be merged using cvs merge.

There are three error states:

Classify Error

CVS could not determine the state of this file.

Unknown

This file is not known to CVS. Normally, the cvs status command displays unknown files at the start of its sequence with a ? beside them. If an unknown file does get passed to the status command, CVS displays its name in the main body of its display with the status Unknown.

For example, if you run the command cvs status filename and the filename refers to a file that is not stored in the repository, CVS reports its status as Unknown.

Entry Invalid

The state of the repository and sandbox files does not match CVS's record keeping. This usually occurs when one of the files has been removed by editing the repository directly, or when a newly added file has been removed from the sandbox without calling cvs remove.

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.