Meaning of "revision" (basis for a BOOK PATCH?)

Mark Watts wrote (in thread "Subversion Questions/Defects"):
> what if I know that I only want to merge in the changes from revision 9 -12
> and 14-17. Revision 13 was a trunk change that I just don't want at this
> time and I also don't want other trunk changes after revision 17.

This is another example of a very common misunderstanding over the meaning of "revision".

The English noun "revision" can mean the ACTION of revising something or the RESULT of revising something. Subversion's convention is normally to use the latter meaning. In Subversion, a "revision" normally means the "state" or "version" that exists after making a change, not the change itself.

But sometimes, as in the output of "svn log", a change is explicitly associated with the revision produced by that change. E.g. part of the output of "svn log -v" in one of my projects is:
------------------------------------------------------------------------
rev 3: julianfoad | 2003-04-10 21:30:05 +0100 (Thu, 10 Apr 2003) | 1 line
Changed paths:
   A /globcomplete/README

Added README.
------------------------------------------------------------------------

The "Changed paths" section always states the changes from the previous revision. The user's comment at the end often describes the changes from the previous revision rather than the absolute state of the new revision. So in this situation, the notation "revision 3" is actually referring to the change between revision 2 and revision 3.

To clarify the relationship between changes and revisions, and the terminology used, here is a chronological sequence of events (+) and descriptions of the current state (-).

+ I create an empty repository to store successive versions of a project.

- The empty state of the project in the repository is called "revision 0".

+ I add files to my working copy, forming the first non-empty version of my project.

- My working copy is now different from the repository. My working copy does not have a revision number to identify it. Revision numbers are only used to identify revisions that already exist in the repository.

+ I commit my changed working copy to the repository.

- The state of the project in the repository is called "revision 1". My working copy is identical to revision 1, and I can say "my working copy is AT revision 1".

- It is easy to think that the CHANGE that created revision 1 from revision 0 should be called "revision 1"; but that is not so in Subversion. The change is called "the change between revision 0 and revision 1", abbreviated "r0:1". The repository contains two revisions (0 and 1), but only one change (r0:1).

+ I change my working copy, by adding, modifying, deleting files or whatever.

+ I commit this change.

- The state of the project in the repository is called "revision 2".

- The repository contains three revisions (0,1,2), but only two changes (r0:1 and r1:2). From revision X to revision Y there are (Y minus X) changes.

+ I decide that revision 2 of the project is worse than revision 1 was, so I add/change/delete files in such a way as to make my working copy identical to revision 1. I could do this manually, or I could use the command "svn update -r1".

+ I commit this change.

- My working copy is now identical to revision 1 and also identical to revision 3. I can say "my working copy is at revision 3", or "is at the head" because the head of the repository is currently revision 3. I could also say "my working copy is at revision 1" but that is probably not a very useful way to describe it, depending on what I intend to do next.

- The change from r1 to r2 (diff -r1:2) is reversed by the change from r2 to r3, so "diff -r1:3" shows no change.

- The next time I commit a change, revision 4 will be created, and so on.

The Subversion book does state the conventions, but probably not strongly or explicitly enough to give a clear understanding to a reader who has not already thought about the ambiguity and possible interpretations. Perhaps something like the text above could be added near the beginning of the book. Improvements to this attempt at documentation are welcome. For example, the addition of "svn log" to the sequence above, and actual commands to turn this sequence into a worked example.

- Julian

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Received on Sat May 3 00:49:09 2003