12.8. Individual VC Commands


We've already explained what the main command, vc-next-action, does. Now we'll describe each of VC's other commands in detail. We have chosen the order of these descriptions to take you from frequently used and simpler commands to rarer and more complex ones.

You can, accordingly, read to the end of chapter or bail out at any point if you think you've learned all you need to. But try to persevere because you may find that the descriptions of the less common commands give you some new ideas about how to track and organize your project files.

12.8.1 Working with Groups and Subtrees of Files

Usually, the projects you want to put under version control have more than one file; it's normal for them to contain all the files under a specific directory and subdirectory. Therefore, seeing a list of all version-controlled files beneath the current working directory is often useful. Being able to perform an operation on all of them en masse is even more useful.

VC mode supports this directly. The command C-x v d (for vc-directory) puts you in a buffer running a customized Dired (directory editing) mode, which lists all registered files under the current directory, indicating which, if any, are checked out and who has locked them. The status field in this listing is automatically kept up to date by check-in and check-out operations.

If you mark several files in this Dired buffer (with the ordinary Dired mark command described in Chapter 5) and then perform either a vc-next-action or vc-revert-buffer, VC performs that operation on all the marked files. The most common case in which you'll perform this procedure is when you want to check in changes to several files simultaneously. VC helps you out: it pops up a buffer for only one change comment, which it then applies to every revision the check-in creates.

The vc-revert-buffer design is a bit more conservative; normally, it prompts you once for each file to make sure you really want to discard its changes.

Some Dired commands are rebound in VC Dired to run version-control commands. The = keystroke, for example, runs vc-diff on the current file rather than a Dired diff. And g refreshes all the VC status fields in the directory.

12.8.2 Difference Reports

Earlier, we mentioned that version control systems help you generate difference reports between versions. VC's command for this is C-x v = (for vc-diff). This command normally shows you the difference between your work file and the last revision you checked in so that you can see exactly what changes you'll be committing if you check in again.

If you give this command a prefix argument, C-u C-x v =, it prompts you for a file name and two revision numbers and reports the difference between those revisions of the file. If the older revision number is empty (that is, you simply press Enter at that prompt), it defaults to the last checked-in revision. If the newer revision is empty, it defaults to the work file. So pressing Enter twice compares the work file with what was last checked in to the repository, a very common task.

It's also possible to get a difference report for a whole tree of project files. If the filename you give C-u C-x v = is actually a directory, you'll see the differences between your specified versions for every registered file underneath that directory.

By design, such a difference report can be shipped and mechanically applied as a patch using Larry Wall's patch utility (available on all modern Unixes). This is a tremendous help when you're cooperating on a software project by email; you can download sources, register them, make modifications and then, with one command, generate a complete patch set of your changes to mail to your collaborators.

The exact format of these reports varies somewhat between version control systems because VC uses each system's native difference reporter.[3] Generally, the output resembles that of the Unix diff command. We'll see how to customize the report later in this chapter. Finally, the last section of the chapter introduces Ediff, an alternate and powerful way to compare and resolve differences between multiple files or versions.

[3] This is a slight oversimplification. VC actually has its own script as a wrapper around SCCS's sccsdiff, in order to give it a calling sequence more like RCS's rcsdiff.

12.8.3 Retrieving Old Revisions

You can use the command C-x v ~ (for vc-version-other-window) to retrieve any saved revision of a file. The revision is retrieved into a work file with the same name as your file, except for a suffix that identifies its revision number (the suffix is actually a dot, followed by a tilde, followed by the revision number, followed by another tilde). So you can retrieve several revisions, and they won't step on each other. This command is useful when you want to eyeball the entire old version of a file, as opposed to just its changes from previous versions or its differences from later ones.

The version suffix format is very close to what Emacs generates for saved versions if you set the global Emacs Lisp variable version-control (which VC has made pretty much obsolete). For example, if you're visiting a file named foo.html and you retrieve version 1.3 by typing C-x v ~ 1 . 3 Enter, you will now be visiting a file named foo.html.~1.3~ (and because it ends with a tilde, Dired's command to flag backup files will mark it, as discussed in Chapter 5).

12.8.4 Viewing Change Histories

If you use C-x v l (for vc-print-log) on a registered file, VC pops up a buffer containing that file's change history. This command is most useful for viewing the change comments associated with each revision.

12.8.5 Registering a File

Normally, registering a file for version control with C-x v v (for vc-next-action) with a nonconcurrent version control system also checks out an editable copy. Occasionally it's useful to be able to just register a file without checking it out. The command C-x v i (for vc-register) does this. With modern concurrent version control systems, this distinction is fading away.

12.8.6 Inserting Version Control Headers

Most version control systems encourage you to embed in your file one or more magic strings that get automatically updated at check-in, check-out, and revert time. The purpose of these strings is to carry automatically inserted information about the current revision number of the file, who last modified it, and when it was last checked in.

These header strings largely duplicate within the file the version information that VC puts on the mode line and the rest of that information you can get with C-x v l (for vc-print-log). This feature might not seem very useful, but (in particular) embedding a version string can make it possible to mine version-control information out of a compiled binary program.

Further, you may frequently view version-controlled files through something other than Emacs. If so, you won't have an Emacs mode line displaying version control information, and there is some value in having the magic headers visible in the file. Accordingly, VC provides you with a command to insert them. (Note that what VC inserts are correctly formatted placeholders for the headers; the actual values get filled in by the underlying version control system each time you commit the file.)

If you type C-x v h (for vc-insert-headers) while visiting a registered and editable file, VC tries to determine from the syntax of the file how to insert the version control header(s) as a comment and then do so. VC knows about C and Java code, and nroff/troff/groff code especially, and can usually deduce the right thing from Emacs' comment-start and comment-end global variables (set by each major mode) so it can insert HTML comments, for example. It falls back to #-to-\n comments (like those used by shell, awk, Perl, tcl, and many other Unix languages) if it can't figure out anything better to do. This command is also smart enough to notice if you already seem to have version control headers present in the file and will ask you for confirmation before inserting a redundant set.

One special behavior with respect to C code is worth mentioning. C files don't actually get version headers put in comments by default. Instead, Emacs generates a string initialization for a static dummy variable called vcid. This action is taken so the header will actually be generated into the corresponding object file as a string, and you can use the strings command (if you've got a Unix-like environment) to see which versions of its sources a binary was generated from.

12.8.7 Making and Retrieving Snapshots

A snapshot of a project is a set of revisions of the project files treated as a unit. Typically, releases are associated with points at which the project's product goes to a customer or other outside evaluator.

When you're working with a subtree of project files and want to define a release of a document or program, you may find it tedious to have to do it by remembering or storing long lists of file revision numbers. Accordingly, most version control systems give you the ability to associate a symbolic release name with all the revisions that make up a release, and then to use that symbolic name later on when naming revisions for retrieval or difference reports.

Bare RCS and CVS both provide this capability. Bare SCCS does not, but VC includes code to simulate it under SCCS. In practice, the difference between native symbolic names and VC's is next to invisible. The only drawback of VC's simulation is that the SCCS tools won't know about symbolic names when you call them outside VC. (Note that this concept doesn't really apply to Subversion, because in that environment every revision is a snapshot of the files and directories comprising the entire module.)

The C-x v s (for vc-create-snapshot) prompts you for a symbolic name. VC then associates this name with the current revision level of every registered file under the current directory.

The symbolic names you create with vc-create-snapshot are also valid arguments to any other VC command that wants a revision number. Symbolic names are especially useful with vc-diff; it means you can compare named releases with each other or with your checked-out work files. The C-x v r (for vc-retrieve-snapshot) command takes a symbolic name and checks out every registered file underneath the current working directory at the revision level associated with the name.

Both the snapshot commands will fail, returning an error and not marking or retrieving any files, if any registered file under the current directory is checked out by anyone. The vc-create-snapshot command fails in order to avoid making a snapshot that, when retrieved later, won't restore the current state completely. It also fails in order to avoid stepping on your work file changes before you've had the chance to check them in or revert them out.

12.8.8 Updating ChangeLog Files

The command C-x v a (for vc-update-change-log) helps VC work with some project-management conventions used by the Free Software Foundation. FSF projects generally have in each directory a file called ChangeLog that is supposed to contain timestamped modification comments for every file in that directory. The ChangeLog, historically, provided the change history, or audit trail, for which VC uses change comments.

Rather than make you enter every change comment twice (!), VC provides a hook that copies recent change comments out of masters beneath the current directory and appends them to a ChangeLog in the approved format.

12.8.9 Renaming Version-Controlled Files

Renaming version-controlled files can be tricky. In RCS or SCCS, you have to rename not just the work file but its associated master. Under CVS, for reasons too arcane to go into here, it's hard to do at all without breaking something.

The vc-rename-file tries to insulate you from the details and to catch and inform you about various error conditions that can arise. It simply prompts for old and new filenames, tries to do the right thing, and tells you if it cannot.

Renaming interacts badly with the simulated symbolic-name feature under SCCS. This is one of the better reasons to use RCS or CVS. And, actually, if you think you might need to rename or move files, you're best off investigating Subversion since one of its major design goals was to be the first version control system in which this task is straightforward.


12.8.10 When VC Gets Confused

The filesystem operations required to determine a file's version control state can be expensive and slow, especially in an NFS or other networked environment. VC goes to some pains to compensate (unless, as we'll see later on, you tell it not to).

It has two major methods: (1) caching per-file information (such as the locking user and current revision number) in memory rather than running version control utilities to parse it out of the relevant master every time, and (2) assuming that it can deduce a registered file's version control state from its write permissions. Specifically, VC assumes that a registered file that is writable is in the checked-out-and-locked state and that a registered file that is not writable is not a checked-out version being edited.

Multiuser environments being what they are, VC's cached information and assumptions about permissions occasionally lead it down the wrong path. This situation almost always occurs because someone has manually changed a file's permissions behind VC's back.

If you think that this situation has occurred, call vc-clear-context. This command forces VC to throw away all its cached-in-memory assumptions about the version control state of the files you are working with.

It is also theoretically possible for VC to get confused by a race condition between two or more VCs, or between VC and someone running the bare SCCS, RCS, or CVS utilities. This is not just a VC problem; the same sort of race is possible (though less likely) between two or more people running the bare utilities. However, this kind of race is very rare even in VC; the authors haven't heard of any instance in hundreds of thousands of programmer-hours in which it's known to have happened.

If you're concerned about this issue, the VC source code (vc.el in your Emacs Lisp source directory) includes a comment giving a careful and extensive analysis of potential multiuser conflict and race situations. VC is exactly as safe from them as the underlying utilities can be.



Learning GNU Emacs
Learning GNU Emacs, Third Edition
ISBN: 0596006489
EAN: 2147483647
Year: 2003
Pages: 161

flylib.com © 2008-2017.
If you may any questions please contact us: flylib@qtcs.net