[svn.haxx.se] · SVN Dev · SVN Users · SVN Org · TSVN Dev · TSVN Users · Subclipse Dev · Subclipse Users · this month's index

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

From: Sander Roobol <phy_at_wanadoo.nl>
Date: 2003-05-13 14:10:01 CEST

Filed as issue #1309.


On Fri, May 02, 2003 at 11:54:50PM +0100, Julian Foad wrote:
> 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

To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Received on Tue May 13 14:11:03 2003

This is an archived mail posted to the Subversion Dev mailing list.

This site is subject to the Apache Privacy Policy and the Apache Public Forum Archive Policy.