14.6.2 Editing with Version Control

When you visit a file that is maintained using version control, the mode line displays ‘RCS’ or ‘SCCS’ to inform you that version control is in use, and also (in case you care) which low-level system the file is actually stored in. Normally, such a source file is read-only, and the mode line indicates this with ‘%%’. With RCS, the mode line also indicates the number of the head version, which is normally also the version you are looking at.

These are the commands for editing a file maintained with version control:

C-x C-q

Check the visited file in or out.

C-x v u

Revert the buffer and the file to the last checked in version.

C-x v c

Remove the last-entered change from the master for the visited file. This undoes your last check-in.

C-x v i

Register the visited file in version control.

(C-x v is the prefix key for version control commands; all of these commands except for C-x C-q start with C-x v.)

When you want to modify a file maintained with version control, type C-x C-q (vc-toggle-read-only). This checks out the file, and tells RCS or SCCS to lock the file. This means making the file writable for you (but not for anyone else).

When you are finished editing the file, type C-x C-q again. When used on a file that is checked out, this command checks the file in. But check-in does not start immediately; first, you must enter the log entry—a description of the changes in the new version. C-x C-q pops up a buffer for you to enter this in. When you are finished typing in the log entry, type C-c C-c to terminate it; this is when actual check-in takes place.

Once you have checked in your changes, the file is unlocked, so that other users can lock it and modify it.

Emacs does not save backup files for source files that are maintained with version control. If you want to make backup files despite version control, set the variable vc-make-backup-files to a non-nil value.

Normally the work file exists all the time, whether it is locked or not. If you set vc-keep-workfiles to nil, then checking in a new version with C-x C-q deletes the work file; but any attempt to visit the file with Emacs creates it again.

It is not impossible to lock a file that someone else has locked. If you try to check out a file that is locked, C-x C-q asks you whether you want to “steal the lock.” If you say yes, the file becomes locked by you, but a message is sent to the person who had formerly locked the file, to inform him of what has happened. The mode line indicates that a file is locked by someone else by displaying the login name of that person, before the version number.

If you want to discard your current set of changes and revert to the last version checked in, use C-x v u (vc-revert-buffer). This cancels your last check-out, leaving the file unlocked. If you want to make a different set of changes, you must first check the file out again. C-x v u requires confirmation, unless it sees that you haven’t made any changes since the last checked-in version.

C-x v u is also the command to use if you lock a file and then don’t actually change it.

You can cancel a change after checking it in, with C-x v c (vc-cancel-version). This command discards all record of the most recent checked in version, so be careful about using it. It requires confirmation with yes. By default, C-x v c reverts your workfile and buffer to the previous version (the one that precedes the version that is deleted), but you can prevent the reversion by giving the command a prefix argument. Then the buffer does not change.

This command with a prefix argument is useful when you have checked in a change and then discover a trivial error in it; you can cancel the erroneous check-in, fix the error, and repeat the check-in.

Be careful when invoking C-x v c, as it is easy to throw away a lot of work with it. To help you be careful, this command always requires confirmation with ‘yes’.

You can register the visited file for version control using C-x v i (vc-register). If the variable vc-default-back-end is non-nil, it specifies which version control system to use; otherwise, this uses RCS if it is installed on your system and SCCS if not. After C-x v i, the file is unlocked and read-only. Type C-x C-q if you wish to edit it.

By default, the initial version number is 1.1. If you want to use a different number, give C-x v i a prefix argument; then it reads the initial version number using the minibuffer.

If vc-initial-comment is non-nil, C-x v i reads an initial comment (much like a log entry) to describe the purpose of this source file.

To specify the version number for a subsequent checkin, use the command C-u C-x v v. C-x v v (vc-next-action) is the command that C-x C-q uses to do the “real work” when the visited file uses version control. When used for checkin, and given a prefix argument, it reads the version number with the minibuffer.