With the release of Emacs 22 on June 2nd a new set of version control (vc for short) modes was released as well. The Emacs Tour briefly touches on it, however it fails to point out the geniusness of this feature.
As of 22.1.1 the following version control backends are supported: RCS, CVS, SVN, SCCS, Bzr, Git, Hg, Arch and MCVS. All commands work the same for all backends.
First, lets start with a link to the full documentation of this feature, the Emacs manual pages. These pages contain all the info in this blogpost, as well as a lot more!
Now, lets take a look at the global keybindings. These keybindings are usable whenever you are visiting a version controlled file (Copied over from EmacsWiki).
| Key combo |
function — description |
| C-x v i |
vc-register — add a new file to version control |
| C-x v v |
vc-next-action — same thing, check in or out, depending on the current state |
| C-x v ~ |
vc-version-other-window — look at other revisions |
| C-x v = |
vc-diff — diff with other revisions |
| C-x v u |
vc-revert-buffer — undo checkout |
| C-x v c |
vc-cancel-version — delete the latest revision (often it makes more sense to look at an old revision and check that in again!) |
| C-x v d |
vc-directory — show all files which are not up to date |
| C-x v g |
vc-annotate — show when each line in a cvs file was added and by whom |
| C-x v s |
vc-create-snapshot — tag all the files with a symbolic name |
| C-x v r |
vc-retrieve-snapshot — undo checkouts and return to a snapshot with a symbolic name |
| C-x v l |
vc-print-log — show log (not in ChangeLog format) |
| C-x v a |
vc-update-change-log — update ChangeLog |
| C-x v m |
vc-merge |
| C-x v h |
vc-insert-headers |
| M-x vc-resolve-conflicts — pop up an ediff-merge session on a file with conflict markers |
There are only a couple of keybindings to remember for day to day usage; C-x v i, C-x v v, C-x v =, C-x v l, C-x v m and C-x v g
Adding files
When you are adding a new file to your project, the C-x v i keybinding takes care of doing it properly for you.
The next action thing
The keybinding C-x v v performs the ‘next action’, this means it will look at the context of the file and will determine the next probable action for the file. When using SVN for instance, after I edit a file, the ‘next action’ will be to do a commit of that file. Some backends checkout their files in read only mode and thus the ‘next action’ is to unlock them and after that the ‘next action’ would be to commit the changes.
It turns out to be a very intuitive way of working with vc and it removes any problem you might have with learning new commands to do the same thing in different backends.
The revision log
The keybinding C-x v l will split the window and will show you a buffer with the revision history of the file. All in all not too exciting, until you read what you can actually do in that buffer. Inside the buffer the keys p and n move you to the ‘previous’ and the ‘next’ entry in the revision log. Pressing d on a revision will show you the Unified Diff of that revision compared to the previous one, so you can see exactly what changed in that revision. The diff feature turns out to be extremely usefull when working in large projects with many people.
Updating a file
If your file is out of sync with your repository just press C-x v m and you can update the file to the latest revision, just press RET. If you pass along a branch number to update to, then all changes from that branch are pulled in.
Seeing changes
To quickly see the changes you have made locally compared to the latest version in the repository, just press C-x v = and a unified diff will pop up.
Who is to blame?
My personal favorite feature of them all, the annotation. Pressing C-x v g will bring up a buffer annotating the current file. By default it will colorize the output depending on age, 18 colors for 20 day steps. So the older the line, the darker the color (default reddish to blue), with steps of 20 days.
There are several keys you can press in this buffer:
| Key |
Description |
| P |
Annotate the previous revision, that is to say, the revision before the one currently annotated. A numeric prefix argument is a repeat count, so C-u 10 P would take you back 10 revisions. |
| N |
Annotate the next revision–the one after the revision currently annotated. A numeric prefix argument is a repeat count. |
| J |
Annotate the revision indicated by the current line. |
| A |
Annotate the revision before the one indicated by the current line. This is useful to see the state the file was in before the change on the current line was made. |
| D |
Display the diff between the current line’s revision and the previous revision. This is useful to see what the current line’s revision actually changed in the file. |
| L |
Show the log of the current line’s revision. This is useful to see the author’s description of the changes in the revision on the current line. |
| W |
Annotate the workfile version-the one you are editing. If you used P and N to browse to other revisions, use this key to return to your current version. |
Version Control is probably one of the cooler features of the new Emacs (22.1) and it deserves a lot more attention then it is getting at the moment.