The LockServer client protocol

The LockServer normally listens on port 2402/tcp. This can be changed by the user, however. There is one lockserver per repository, but one lockserver may serve many repositories (on many machines). The LockServer is not usually bound to a public port, unless the user requests it.

Upon connection to the lockserver it sends an initial greeting including its protocol version number

  CVSLock 1.3 Ready

Potential clients must check that they are running the correct version. It is valid for a 1.0 client to connect to (for example) a 1.1 server, but not for a 1.1 client to connect to a 1.0 server.

This document describes versions 1.1, 1.2 and 1.3 of the protocol.

As of server version 1.3, all communication is case sensitive and path separators must be '/'. It is the responsibility of the client to ensure that this is adhered to.

Each lockserver session is divided into modes. Different commands are valid in each mode.

Login Mode

Client <user>'|'<root>['|'<client_host>]

Login to the server and begin a standard cvs locking session

Example:

  Client foo|d:/repo|mymachine.local.not

Client mode

Lock {Read|Write} {Advisory|Full} [Recursive] {File|Directory}'|'<path>

Start a lock on a file or directory. Ther are two locks 'levels' - advisory and full. An advisory lock is an 'I intend to lock in the future' lock, and is only binding in that you can't have two write advisory locks covering the same file. A full lock is an 'I am now writing to' lock and gives you exclusive access to the file. It is recommended that the granularity of full locks is kept to a minimum.

On protocol version 1.2 or above, a full lock on a file may return an 003 response if the file has been modified since the client connected. The text will contain a section in brackets with a list of versions that were valid at the point of connection. Any branch not in this list can be assumed to be unchanged. The list is formatted as <branch>:<version> <branch>:<version> ...

Example:

 Lock Read Advisory Recursive Directory|d:/repo/MyDir
 000 OK Lock granted

 Lock Read Full Recursive Directory|d:/repo/MyDir
 003 WARN File modified (HEAD:1.3 foo:1.2.1.4) - Lock granted

Unlock [{Read|Write} [Recursive] {File|Directory}'|'<path>]
Unlock All

Terminate a lock. This is also called implicitly if you break connection to the lockserver.

Example:

 Unlock Read Full Recursive Directory|d:/repo/MyDir
 000 OK Unlocked

1.1 Modified [Added|Deleted]'|'<RCS path>'|'<branch>'|'<version>
1.2 Modified [Added|Deleted]'|'<RCS path>'|'<branch>'|'<version>'|'<previous version>

Inform the lockserver that you have modified a file, and give the new revision. This is then reflected to the monitor clients who can use it for live status updates.

Example:

 Modified |d:/repo/foo.txt|HEAD|1.3

Error returns

All commands return an error code on completion, which is one of the following:

• 000 OK {message}	Everything went OK - no error
  001 FAIL {message}	Something went wrong - error text is in the message
  002 WAIT {message}	A conflicting lock is already active. Try again later
  003 WARN {message}	Something was amiss, but the command executed anyway.