5. Commands

The nodes in this menu contains explanations about all the commands that you can use in pcl-cvs. They are grouped together by type.

5.1 Setting flags for CVS commands

This section describes the convention used by nearly all pcl-cvs commands for setting optional flags sent to CVS. A single C-u prefix argument is used to cause the command to prompt for flags to be used for the current invocation of the command only. Two C-u prefix arguments are used to prompt for flags which will be set permanently, for the current invocation and all that follow, until the flags are changed, or unless temporary flags are set which override them.

Perhaps an example or two is in order. Say you are about to add a binary file to the repository, and want to specify the flags `-kb' to `cvs add'. You can type C-u a -kb RET, enter the description, and the file will be added. Subsequent adds will use the previously prevailing flags, found in `cvs-add-flags'.

As a second example, say you are about to perform a diff and want to see the result in unified diff format, i.e. you'd like to pass the flag `-u' to both `cvs diff' and `diff'. You'd also like all subsequent diffs to use this flag. You can type C-u C-u = -u RET and the diff will be performed, and `cvs-diff-flags' will be set to ("-u"). You can of course override this flag for a single diff by using a single C-u prefix argument.

Additionally to this, some commands can take special prefix arguments. These work as follows: when called with a C-u prefix, the user is prompted for a new value of the special prefix and the special prefix is activated for the next command. When called without the C-u prefix, the special prefix is re-activated (with the same value as last time) for the next command. The special prefixes are:

b

Provide the next command with a branch (can be any version specifier) to work on.

5.2 Entering pcl-cvs

Most commands in pcl-cvs require that you have a `*cvs*' buffer. The commands that you use to get one are listed below. For each, a `cvs' process will be run, the output will be parsed by pcl-cvs, and the result will be printed in the `*cvs*' buffer (see see section 4. Buffer contents for a description of the contents).

M-x cvs-update

Run a `cvs update' command. You will be asked for the directory in which the `cvs update' will be run.

M-x cvs-examine

Run a `cvs -n update' command. This is identical to the previous command, except that it will only check what needs to be done but will not change anything. You will be asked for the directory in which the `cvs -n update' will be run.

M-x cvs-status

Run a `cvs status' command. You will be asked for the directory in which the `cvs status' will be run.

M-x cvs-checkout

Run a `cvs checkout' command. You will be asked for the directory in which the `cvs update' will be run and the module to be checked out.

CVS uses lock files in the repository to ensure the integrity of the data files in the repository. They might be left behind i.e. if a workstation crashes in the middle of a CVS operation. CVS outputs a message when it is waiting for a lock file to go away. Pcl-cvs will show the same message in the *cvs* buffer, together with instructions for deleting the lock files. You should normally not have to delete them manually -- just wait a little while and the problem should fix itself. But if the lock files do not disappear you can delete them with M-x cvs-mode-delete-lock RET.

By default, the commands above will descend recursively into subdirectories. You can avoid that behavior by including `-l' in the flags for the command. These flags can be set by giving a prefix argument to the command (e.g., by typing C-u M-x cvs-update RET -l RET).

5.3 Updating the `*cvs*' buffer

The following commands can be used from within the `*cvs*' buffer to update the display:

M-u

This will run `cvs update' and prompt for a new directory to update. This runs the command `cvs-update'.

M-e

This will run `cvs -n update' and prompt for a new directory to examine. This runs the command `cvs-examine'.

M-s

This will run `cvs status' and prompt for a new directory to status. This runs the command `cvs-status'.

5.4 Movement Commands

You can use most normal Emacs commands to move forward and backward in the buffer. Some keys are rebound to functions that take advantage of the fact that the buffer is a pcl-cvs buffer:

SPC

C-n

n

These keys move the cursor one file forward, towards the end of the buffer (cookie-next-cookie).

C-p

p

These keys move one file backward, towards the beginning of the buffer (cookie-previous-cookie).

5.5 Marking files

Pcl-cvs works on a set of selected files (see section 4.2 Selected files). You can mark and unmark files with these commands:

m

This marks the file that the cursor is positioned on. If the cursor is positioned on a directory all files in that directory will be marked. (cvs-mode-mark).

u

Unmark the file that the cursor is positioned on. If the cursor is on a directory, all files in that directory will be unmarked. (cvs-mode-unmark).

M

Mark all files in the buffer (cvs-mode-mark-all-files).

ESC DEL

Unmark all files (cvs-mode-unmark-all-files).

DEL

Unmark the file on the previous line, and move point to that line (cvs-mode-unmark-up).

%

Mark all files matching a regular expression (cvs-mode-mark-matching-files).

T

Toggle use of marks for the next command (cvs-mode-toggle-marks).

5.6 Committing changes

c

All files that have a "need to be checked in"-marker (see section 4. Buffer contents) can be checked in with the c command. It checks in all selected files (see section 4.2 Selected files) (except those who lack the "com"-marker - they are ignored). Pressing c causes cvs-mode-commit to be run.

When you press c you will get a buffer called `*cvs-commit-message*'. Enter the log message for the file(s) in it. When you are ready you should press C-c C-c to actually commit the files (using cvs-edit-done).

Normally the `*cvs-commit-message*' buffer will retain the log message from the previous commit, but if the variable cvs-erase-input-buffer is set to a non-nil value the buffer will be erased. Point and mark will always be located around the entire buffer so that you can easily erase it with C-w (`kill-region').

If you are editing the files in your emacs an automatic `revert-buffer' will be performed. (If the file contains `$Id$' keywords `cvs commit' will write a new file with the new values substituted. The auto-revert makes sure that you get them into your buffer). The revert will not occur if you have modified your buffer, or if `cvs-auto-revert' is set to `nil'.

C

This is just like `cvs-mode-commit', except that it tries to provide appropriate default log messages by looking at the `ChangeLog's handling the files to be checked in. The idea is to write your ChangeLog entries first, and then use this command to commit your changes. Pressing C causes cvs-mode-changelog-commit to be run.

To select default log text, pcl-cvs:

• finds the ChangeLogs for the files to be checked in;
• verifies that the top entry in the ChangeLog is on the current date and by the current user; if not, no default text is provided;
• searchs the ChangeLog entry for paragraphs containing the names of the files being checked in; and finally
• uses those paragraphs as the default log text in the `*cvs-commit-message*' buffer.

You can then commit the `ChangeLog' file once per day without any log message.

5.7 Editing files

There are currently three commands that can be used to find a file (that is, load it into a buffer and start editing it there). These commands work on the line that the cursor is situated at. They always ignore any marked files.

f

Find the file that the cursor points to. Run `dired' (@xref{Dired,,,Emacs}) if the cursor points to a directory (cvs-mode-find-file).

o

Like f, but use another window (cvs-mode-find-file-other-window).

A

Invoke `add-change-log-entry-other-window' to edit a `ChangeLog' file. The `ChangeLog' will be found in the directory or a parent of the directory of the file the cursor points to. (cvs-mode-add-change-log-entry-other-window).

5.8 Getting info about files

Both of the following commands can be customized. See section 6. Customization.

l

Run `cvs log' on all selected files, and show the result in a temporary buffer (cvs-mode-log).

s

Run `cvs status' on all selected files, and show the result in a temporary buffer (cvs-mode-status).

5.9 Adding and removing files

The following commands are available to make it easy to add and remove files from the CVS repository.

a

Add all selected files. This command can be used on `Unknown' files (see section 4.1 File status). The status of the file will change to `Added', and you will have to use c (`cvs-mode-commit', see section 5.6 Committing changes) to really add the file to the repository.

This command can also be used on `Removed' files (before you commit them) to resurrect them.

Selected files that are neither `Unknown' nor `Removed' will be ignored by this command.

The command that is run is cvs-mode-add.

r

This command removes the selected files (after prompting for confirmation). The files are `rm'ed from your directory and (unless the status was `Unknown'; see section 4.1 File status) they will also be `cvs remove'd. If the files were `Unknown' they will disappear from the buffer. Otherwise their status will change to `Removed', and you must use c (`cvs-mode-commit', see section 5.6 Committing changes) to commit the removal.

The command that is run is cvs-mode-remove-file.

5.10 Undoing changes

U

If you have modified a file, and for some reason decide that you don't want to keep the changes, you can undo them with this command. It works by removing your working copy of the file and then getting the latest version from the repository (cvs-mode-undo-local-changes.

5.11 Removing handled entries

x

This command allows you to remove all entries that you have processed. More specifically, the lines for `Up-to-date' files (see section 4.1 File status are removed from the buffer. If a directory becomes empty the heading for that directory is also removed. This makes it easier to get an overview of what needs to be done.

The command is called cvs-mode-remove-handled. If `cvs-auto-remove-handled' is set to non-nil this will automatically be performed after every commit.

C-k

This command can be used for lines that `cvs-mode-remove-handled' would not delete, but that you want to delete (cvs-mode-acknowledge).

5.12 Ignoring files

i

Arrange so that CVS will ignore the selected files. The file names are added to the `.cvsignore' file in the corresponding directory. If the `.cvsignore' doesn't exist it will be created.

The `.cvsignore' file should normally be added to the repository, but you could ignore it also if you like it better that way.

This runs cvs-mode-ignore.

5.13 Viewing differences

=

d =

Display a `cvs diff' between the selected files and the RCS version that they are based on. (cvs-mode-diff).

d b

If CVS finds a conflict while merging two versions of a file (during a `cvs update', see section 5.3 Updating the `*cvs*' buffer) it will save the original file in a file called `.#FILE.VERSION' where FILE is the name of the file, and VERSION is the RCS version number that your file was based on.

With the b command you can run a `diff' on the files `.#FILE.VERSION' and `FILE'. This command only works on files that have status `Conflict' or `Merged'. (cvs-mode-diff-backup).

d h

Display a `cvs diff' between the selected files and the head revision in the repository. (cvs-mode-diff-head).

d v

Display a `cvs diff' between the selected files and the head revision of the vendor branch in the repository. (cvs-mode-diff-vendor).

For all of the diffing commands, if `cvs-diff-ignore-marks' is set to a non-nil value or if the command T (`cvs-mode-toggle-marks') is given immediately preceding the command, any marked files will not be considered to be selected.

Also, you can get a context- or unified diff by setting `cvs-diff-flags'. See section 6. Customization, and also 5.1 Setting flags for CVS commands.

5.14 Running ediff

e

This command uses ediff (or emerge depending on `cvs-idiff-imerge-handlers') to allow you to view diffs. If a prefix argument is give, pcl-cvs will prompt for a revision against which the diff should be made, else the default will be to use the BASE revision.

E

This command use ediff (or emerge, see above) to allow you to do an interactive 3-way merge.

Note: When the file status is `Merged' or `Conflict', CVS has already performed a merge. The resulting file is not used in any way if you use this command. If you use the q command inside `ediff' (to successfully terminate a merge) the file that CVS created will be overwritten.

5.15 Updating files

O

Update all selected files with status `Need-update' by running `cvs update' on them. This command is only meaningful after M-x cvs-status has been run. (cvs-mode-update).

5.16 Tagging files

t

Tag all selected files by running `cvs tag' on them. (cvs-mode-tag). It's usually preferable to tag directories at a time. Rather than selecting all files (which too often doesn't select all files but only the few that are displayed), clear the selection with M-DEL (cvs-mode-unmark-all-files), position the cursor on the directory you want to tag and hit t.

5.17 Miscellaneous commands

M-x cvs-mode-byte-compile-files

Byte compile all selected files that end in .el.

M-x cvs-mode-delete-lock

This command deletes the lock files that the *cvs* buffer informs you about. You should normally never have to use this command since CVS tries very carefully to always remove the lock files itself.

You can only use this command when a message in the *cvs* buffer tells you so. You should wait a while before using this command in case someone else is running a cvs command.

?

h

Show a summary of common command key bindings in the echo area. (cvs-help).

q

Quit pcl-cvs, killing the *cvs* buffer. (cvs-mode-quit).

This document was generated by XEmacs shared group account on December, 19 2009 using texi2html 1.65.