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.
6 Comments
> There are only a couple of keybindings to remember
[followed by a list of six keybindings]
Story of the problem with Emacs, sigh…
But thanks for the heads up and the nice table/API summary.
Thanks! I had heard about the reimplementation (at last–no more file-based VC) but hadn’t seen much by way of explaination. It does look like Info has been updated with the new system, which is cool. But an overview like this is always helpful.
One less thing to drop into the shell for; woot.
I am running 23.0.1 on a Mac, but can’t see any mention of git or Hg:
Ceesaxp,
The build I used to write the article on is actually a CVS build from the branch EMACS_22_BASE, it is actually the only one which works/compiles nicely for Mac OS X Leopard. (http://cvs.savannah.gnu.org/viewvc/emacs/?root=emacs&pathrev=EMACS_22_BASE)
My 22.1.50.1 has the following supported backends:
C-h v vc-handled-backends RET
vc-handled-backends is a variable defined in `vc-hooks.el’.
Its value is
(RCS CVS SVN SCCS Arch MCVS)
If you’re a subversion user, it’s not clear to me that version control is a good fit at all. In particular, the “next action” is simply not well-defined on a file-by-file basis. Most likely the true next action will be to commit a changeset that is a coherent set of changes to multiple files. Now, cvs can’t do that, so VC is an ok fit for it, but for svn, this seems like a Bad Thing.
Don’t forget the ‘f’ binding in vc-annotate to visit the revision in question.
One Trackback
[...] does version control!. And if you’re tunneling your version control through SSH, you should probably set up those [...]