Filed as issue #1309.
Sander
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