Note: This documentation comes from the PCL-CVS source distribution. I've rearranged the chapters in order of importance.
JeffreyHorner
This document assumes that you know what CVS is, and that you at least
knows the fundamental concepts of CVS. If that is not the case you
should read the man page for CVS.
Pcl-cvs is only useful once you have checked out a module. So before
you invoke it you must have a copy of a module somewhere in the file
system.
You invoke pcl-cvs by typing M-x cvs-update RET. If your emacs
responds with `[No match]' your system administrator has not
installed pcl-cvs properly. Try M-x load-library RET pcl-cvs RET.
If that also fails - talk to your root. If it succeeds you might put
this line in your `.emacs' file so that you don't have to type the
`load-library' command every time you wish to use pcl-cvs:
(autoload 'cvs-update "pcl-cvs" nil t)
The function cvs-update will ask for a directory. The command
`cvs update' will be run in that directory. (It should contain
files that have been checked out from a CVS archive.) The output from
cvs will be parsed and presented in a table in a buffer called
`*cvs*'. It might look something like this:
PCL-CVS release XXRELEASEXX.
In directory /users/ceder/FOO/test:
Updated bar
Updated file.txt
Modified ci namechange
Updated newer
In directory /users/ceder/FOO/test/sub:
Modified ci ChangeLog
---------- End -----
In this example the three files (`bar', `file.txt' and
`newer') that are marked with `Updated' have been copied from
the CVS repository to `/users/ceder/FOO/test/' since someone else
have checked in newer versions of them. Two files (`namechange'
and `sub/ChangeLog') have been modified locally, and needs to be
checked in.
You can move the cursor up and down in the buffer with C-n and
C-p or n and p. If you press c on one of the
`Modified' files that file will be checked in to the CVS
repository. See section 6.4 Committing changes. You can press x to get rid
of the "uninteresting" files that have only been `Updated' (and
don't require any further action from you).
You can also easily get a `diff' between your modified file and the
base version that you started from, and you can get the output from
`cvs log' and `cvs status' on the listed files simply by
pressing a key (see section 6.6 Getting info about files).
The display contains four columns. They contain, from left to right:
-
An asterisk when the file is marked (see section 5.2 Selected files).
-
The status of the file. See See section 5.1 File status, for more information.
-
A "need to be checked in"-marker (`ci').
-
The file name.
The `file status' field can have the following values:
- `Updated'
-
The file was brought up to date with respect to the repository. This is
done for any file that exists in the repository but not in your source,
and for files that you haven't changed but are not the most recent
versions available in the repository.
- `Modified'
-
The file is modified in your working directory, and there was no
modification to the same file in the repository.
- `Merged'
-
The file is modified in your working directory, and there were
modifications in the repository as well as in your copy, but they were
merged successfully, without conflict, in your working directory.
- `Conflict'
-
A conflict was detected while trying to merge your changes to file
with changes from the source repository. file (the copy in your
working directory) is now the output of the `rcsmerge' command on
the two versions; an unmodified copy of your file is also in your
working directory, with the name `.#file.version',
where version is the RCS revision that your modified file started
from. See section 6.11 Viewing differences, for more details.
- `Added'
-
The file has been added by you, but it still needs to be checked in to
the repository.
- `Removed'
-
The file has been removed by you, but it needs to be checked in to the
repository. You can resurrect it by typing a (see section 6.7 Adding and removing files).
- `Unknown'
-
A file that was detected in your directory, but that neither appears in
the repository, nor is present on the list of files that CVS should
ignore.
There are also a few special cases, that rarely occur, which have longer
strings in the fields:
- `Removed from repository'
-
The file has been removed from your directory since someone has removed
it from the repository. (It is still present in the Attic directory, so
no permanent loss has occurred). This, unlike the other entries in this
table, is not an error condition.
- `Removed from repository, changed by you'
-
You have modified a file that someone have removed from the repository.
You can correct this situation by removing the file manually (see
see section 6.7 Adding and removing files).
- `Removed by you, changed in repository'
-
You have removed a file, and before you committed the removal someone
committed a change to that file. You could use a to resurrect the
file (see see section 6.7 Adding and removing files).
- `Move away file - it is in the way'
-
For some reason CVS does not like the file file. Rename or remove
it.
- `This repository is missing! Remove this dir manually.'
-
It is impossible to remove a directory in the CVS repository in a clean
way. Someone have tried to remove one, and CVS gets confused. Remove
your copy of the directory.
Many of the commands works on the current set of selected files.
-
If there are any files that are marked they constitute the set of
selected files.
-
Otherwise, if the cursor points to a file, that file is the selected
file.
-
Otherwise, if the cursor points to a directory, all the files in that
directory that appears in the buffer are the selected files.
This scheme might seem a little complicated, but once one get used to
it, it is quite powerful.
See section 6.3 Marking files tells how you mark and unmark files.
This chapter describes all the commands that you can use in pcl-cvs.
- M-x cvs-update
-
Run a `cvs update' command. You will be asked for the directory in
which the `cvs update' will be run. The output will be parsed by
pcl-cvs, and the result printed in the `*cvs*' buffer (see
see section 5. Buffer contents for a description of the contents).
By default, `cvs-update' will descend recursively into
subdirectories. You can avoid that behavior by giving a prefix
argument to it (e.g., by typing C-u M-x cvs-update RET).
All other commands in pcl-cvs requires that you have a `*cvs*'
buffer. This is the command that you use to get one.
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 doesn't disappear you can delete them
with M-x cvs-mode-delete-lock RET.
- g
-
This will run `cvs update' again. It will always use the same
buffer that was used with the previous `cvs update'. Give a prefix
argument to avoid descending into subdirectories. This runs the command
`cvs-mode-update-no-prompt'.
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).
Pcl-cvs works on a set of selected files (see section 5.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).
- c
-
All files that have a "need to be checked in"-marker (see section 5. Buffer contents) can be checked in with the c command. It checks in all
selected files (see section 5.2 Selected files) (except those who lack the
"ci"-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: XemacsPclCvs.txt,v 1.1 2004/04/09 15:45:00 JeffreyHorner Exp www-data $' 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-after-commit' is set to
`nil'.
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 ignore any marked
files.
- f
-
Find the file that the cursor points to. Run `dired'
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 of the file the cursor points to.
(
cvs-mode-add-change-log-entry-other-window).
Both of the following commands can be customized.
See section 7. 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).
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 see section 5.1 File status). The status of the file will change to
`Added', and you will have to use c (`cvs-mode-commit', see
see section 6.4 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 5.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 6.4 Committing changes) to commit the removal.
The command that is run is
cvs-mode-remove-file.
- 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.
- x
-
This command allows you to remove all entries that you have processed.
More specifically, the lines for `Updated' files (see section 5.1 File status and files that have been checked in (see section 6.4 Committing changes)
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).
- 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.
- d
-
Display a `cvs diff' between the selected files and the RCS version
that they are based on. See section 7. Customization describes how you can send
flags to `cvs diff'. If cvs-diff-ignore-marks is set to a
non-
nil value or if a prefix argument is given (but not both) any
marked files will not be considered to be selected.
(cvs-mode-diff-cvs).
- b
-
If CVS finds a conflict while merging two versions of a file (during a
`cvs update', see section 6.1 Updating the directory) 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'. You can get a
context- or Unidiff by setting `cvs-diff-flags' -
see section 7. Customization. This command only works on files that have
status `Conflict' or `Merged'.
If cvs-diff-ignore-marks is set to a non-
nil value or if a
prefix argument is given (but not both) any marked files will not be
considered to be selected. (cvs-mode-diff-backup).
- e
-
Invoke `emerge' on one file. This command works slightly different
depending on the file status.
- `Modified'
-
Run `emerge-files' with your working file as file A, and the latest
revision in the repository as file B.
- `Merged'
-
- `Conflict'
-
Run `emerge-files-with-ancestor' with your working file (as it was
prior to your invocation of `cvs-update') as file A, the latest
revision in the repository as file B, and the revision that you based
your local modifications on as ancestor.
Note: 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 `emerge' (to successfully terminate the merge) the
file that CVS created will be overwritten.
- R
-
If you are editing (or just viewing) a file in a buffer, and that file
is changed by CVS during a `cvs-update', all you have to do is type
R in the cvs buffer to read in the new versions of the
files.
All files that are `Updated', `Merged' or in `Conflict'
are reverted from the disk. Any other files are ignored. Only files
that you were already editing are read.
An error is signalled if you have modified the buffer since it was last
changed. (
cvs-mode-revert-updated-buffers).
- 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.
- q
-
Bury the cvs buffer. (
bury-buffer).
If you have an idea about any customization that would be handy but
isn't present in this list, please tell me! See section 9. Bugs (known and unknown) for info on how
to reach me.
- `cvs-erase-input-buffer'
-
If set to anything else than
nil the edit buffer will be erased
before you write the log message (see section 6.4 Committing changes).
- `cvs-inhibit-copyright-message'
-
The copyright message that is displayed on startup can be annoying after
a while. Set this variable to `t' if you want to get rid of it.
(But don't set this to `t' in the system defaults file - new users
should see this message at least once).
- `cvs-diff-flags'
-
A list of strings to pass as arguments to the `cvs diff' and
`diff' programs. This is used by `cvs-mode-diff-cvs' and
`cvs-mode-diff-backup' (key b, see section 6.11 Viewing differences). If
you prefer the Unidiff format you could add this line to your
`.emacs' file:
(setq cvs-diff-flags '("-u"))
- `cvs-diff-ignore-marks'
-
If this variable is non-
nil or if a prefix argument is given (but
not both) to `cvs-mode-diff-cvs' or `cvs-mode-diff-backup'
marked files are not considered selected.
- `cvs-log-flags'
-
List of strings to send to `cvs log'. Used by `cvs-mode-log'
(key l, see section 6.6 Getting info about files).
- `cvs-status-flags'
-
List of strings to send to `cvs status'. Used by `cvs-mode-status'
(key s, see section 6.6 Getting info about files).
- `cvs-auto-remove-handled'
-
If this variable is set to any non-
nil value
`cvs-mode-remove-handled' will be called every time you check in
files, after the check-in is ready. See section 6.9 Removing handled entries.
- `cvs-auto-revert-after-commit'
-
If this variable is set to any non-`nil' value any buffers you have
that visit a file that is committed will be automatically reverted.
This variable is default `t'. See section 6.4 Committing changes.
- `cvs-update-prog-output-skip-regexp'
-
The `-u' flag in the `modules' file can be used to run a command
whenever a `cvs update' is performed (see cvs(5)). This regexp
is used to search for the last line in that output. It is normally set
to `"$"'. That setting is only correct if the command outputs
nothing. Note that pcl-cvs will get very confused if the command
outputs anything to `stderr'.
- `cvs-cvsroot'
-
This variable can be set to override `CVSROOT'. It should be a
string. If it is set then everytime a cvs command is run it will be
called as `cvs -d cvs-cvsroot...' This can be useful if
your site has several repositories.
- `TMPDIR'
-
Pcl-cvs uses this environment variable to decide where to put the
temporary files it needs. It defaults to `/tmp' if it is not set.
- `cvs-commit-buffer-require-final-newline'
-
When you enter a log message in the `*cvs-commit-message*' buffer
pcl-cvs will normally automatically insert a trailing newline, unless
there already is one. This behavior can be controlled via
`cvs-commit-buffer-require-final-newline'. If it is `t' (the
default behavior), a newline will always be appended. If it is
`nil', newlines will never be appended. Any other value causes
pcl-cvs to ask the user whenever there is no trailing newline in the
commit message buffer.
- `cvs-sort-ignore-file'
-
If this variable is set to any non-`nil' value the
`.cvsignore' will always be sorted whenever you use
`cvs-mode-ignore' to add a file to it. This option is on by
default.
Go to the first, previous, next, last section, table of contents.