3.4 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.

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)

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 has not 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.