model.texi

linux subdivision ying gai ke yi le ba

Files generally have interesting attributes beyond their contents:
mime-types, executable permissions, EOL styles, and so on.  Subversion
attempts to preserve these attributes, or at least record them, when
doing so would be meaningful.  However, different operating systems
support very different sets of file attributes: Windows NT supports
access control lists, while Linux provides only the simpler
traditional Unix permission bits.

In order to interoperate well with clients on many different operating
systems, Subversion supports @dfn{property lists}, a simple,
general-purpose mechanism which clients can use to store arbitrary
out-of-band information about files.

A property list is a set of name / value pairs.  A property name is an
arbitrary text string, expressed as a Unicode UTF-8 string, canonically
decomposed and ordered.  A property value is an arbitrary string of
bytes.  Property values may be of any size, but Subversion may not
handle very large property values efficiently.  No two properties in a
given a property list may have the same name.  Although the word `list'
usually denotes an ordered sequence, there is no fixed order to the
properties in a property list; the term `property list' is historical.

Each revision number, file, directory, and directory entry in the
Subversion repository, has its own property list.  Subversion puts these
property lists to several uses:
@itemize @bullet
@item
Clients can use properties to store file attributes, as described above.
@item
The Subversion server uses properties to hold attributes of its own,
and allow clients to read and modify them.  For example, someday a
hypothetical @samp{svn-acl} property might hold an access control list
which the Subversion server uses to regulate access to repository
files.
@item
Users can invent properties of their own, to store arbitrary information
for use by scripts, build environments, and so on.  Names of user
properties should be URI's, to avoid conflicts between organizations.
@end itemize

Property lists are versioned, just like file contents.  You can change
properties in your working directory, but those changes are not visible
in the repository until you commit your local changes.  If you do commit
a change to a property value, other users will see your change when they
update their working directories.


@c -----------------------------------------------------------------------
@node Merging and Ancestry
@section Merging and Ancestry

[WARNING:  this section was written in May 2000, at the very beginning
of the Subversion project.  This functionality probably will not exist
in Subversion 1.0, but it's planned for post-1.0.  The problem should
be reasonably solvable by recording merge data in 'properties'.]

Subversion defines merges the same way CVS does: to merge means to take
a set of previously committed changes and apply them, as a patch, to a
working copy.  This change can then be committed, like any other change.
(In Subversion's case, the patch may include changes to directory trees,
not just file contents.)

As defined thus far, merging is equivalent to hand-editing the working
copy into the same state as would result from the patch application.  In
fact, in CVS there @emph{is} no difference -- it is equivalent to just
editing the files, and there is no record of which ancestors these
particular changes came from.  Unfortunately, this leads to conflicts
when users unintentionally merge the same changes again.  (Experienced
CVS users avoid this problem by using branch- and merge-point tags, but
that involves a lot of unwieldy bookkeeping.)

In Subversion, merges are remembered by recording @dfn{ancestry sets}.
A revision's ancestry set is the set of all changes "accounted for" in
that revision.  By maintaining ancestry sets, and consulting them when
doing merges, Subversion can detect when it would apply the same patch
twice, and spare users much bookkeeping.  Ancestry sets are stored as
properties.

In the examples below, bear in mind that revision numbers usually refer
to changes, rather than the full contents of that revision.  For example,
"the change A:4" means "the delta that resulted in A:4", not "the full
contents of A:4".

The simplest ancestor sets are associated with linear histories.  For
example, here's the history of a file A:

@example
@group

 _____        _____        _____        _____        _____
|     |      |     |      |     |      |     |      |     |
| A:1 |----->| A:2 |----->| A:3 |----->| A:4 |----->| A:5 |
|_____|      |_____|      |_____|      |_____|      |_____|

@end group
@end example

The ancestor set of A:5 is:

@example
@group

  @{ A:1, A:2, A:3, A:4, A:5 @}

@end group
@end example

That is, it includes the change that brought A from nothing to A:1, the
change from A:1 to A:2, and so on to A:5.  From now on, ranges like this
will be represented with a more compact notation:

@example
@group

  @{ A:1-5 @}

@end group
@end example

Now assume there's a branch B based, or "rooted", at A:2.  (This
postulates an entirely different revision history, of course, and the
global revision numbers in the diagrams will change to reflect it.)
Here's what the project looks like with the branch:

@example
@group

 _____        _____        _____        _____        _____        _____
|     |      |     |      |     |      |     |      |     |      |     |
| A:1 |----->| A:2 |----->| A:4 |----->| A:6 |----->| A:8 |----->| A:9 |
|_____|      |_____|      |_____|      |_____|      |_____|      |_____|
                \
                 \
                  \  _____        _____        _____
                   \|     |      |     |      |     |
                    | B:3 |----->| B:5 |----->| B:7 |
                    |_____|      |_____|      |_____|

@end group
@end example

If we produce A:9 by merging the B branch back into the trunk

@example
@group

 _____        _____        _____        _____        _____        _____
|     |      |     |      |     |      |     |      |     |      |     |
| A:1 |----->| A:2 |----->| A:4 |----->| A:6 |----->| A:8 |---.->| A:9 |
|_____|      |_____|      |_____|      |_____|      |_____|  /   |_____|
                \                                            |
                 \                                           |
                  \  _____        _____        _____        /
                   \|     |      |     |      |     |      /
                    | B:3 |----->| B:5 |----->| B:7 |--->-'
                    |_____|      |_____|      |_____|

@end group
@end example

then what will A:9's ancestor set be?

@example
@group

  @{ A:1, A:2, A:4, A:6, A:8, A:9, B:3, B:5, B:7@}

@end group
@end example

or more compactly:

@example
@group

  @{ A:1-9, B:3-7 @}

@end group
@end example

(It's all right that each file's ranges seem to include non-changes;
this is just a notational convenience, and you can think of the
non-changes as either not being included, or being included but being
null deltas as far as that file is concerned).

All changes along the B line are accounted for (changes B:3-7), and so
are all changes along the A line, including both the merge and any
non-merge-related edits made before the commit.

Although this merge happened to include all the branch changes, that
needn't be the case.  For example, the next time we merge the B line

@example
@group

 _____     _____     _____     _____     _____      _____      _____
|     |   |     |   |     |   |     |   |     |    |     |    |     |
| A:1 |-->| A:2 |-->| A:4 |-->| A:6 |-->| A:8 |-.->| A:9 |-.->|A:11 |
|_____|   |_____|   |_____|   |_____|   |_____| |  |_____| |  |_____|
             \                                  /          |
              \                                /           |
               \  _____     _____     _____   / _____      |
                \|     |   |     |   |     | / |     |    /
                 | B:3 |-->| B:5 |-->| B:7 |-->|B:10 |->-'
                 |_____|   |_____|   |_____|   |_____|

@end group
@end example

Subversion will know that A's ancestry set already contains B:3-7, so
only the difference between B:7 and B:10 will be applied.  A's new
ancestry will be

@example
@group

  @{ A:1-11, B:3-10 @}

@end group
@end example

But why limit ourselves to contiguous ranges?  An ancestry set is truly
a set -- it can be any subset of the changes available:

@example
@group

 _____        _____        _____        _____        _____        _____
|     |      |     |      |     |      |     |      |     |      |     |
| A:1 |----->| A:2 |----->| A:4 |----->| A:6 |----->| A:8 |--.-->|A:10 |
|_____|      |_____|      |_____|      |_____|      |_____| /    |_____|
                |                                          /
                |                ______________________.__/
                |               /                      |
                |              /                       |
                \           __/_                      _|__
                 \         @{    @}                    @{    @}
                  \  _____        _____        _____        _____
                   \|     |      |     |      |     |      |     |
                    | B:3 |----->| B:5 |----->| B:7 |----->| B:9 |----->
                    |_____|      |_____|      |_____|      |_____|

@end group
@end example

In this diagram, the change from B:3-5 and the change from B:7-9 are
merged into a working copy whose ancestry set (so far) is @w{@{ A:1-8
@}} plus any local changes.  After committing, A:10's ancestry set is

@example
@group

  @{ A:1-10, B:5, B:9 @}

@end group
@end example

Clearly, saying "Let's merge branch B into A" is a little ambiguous.  It
usually means "Merge all the changes accounted for in B's tip into A",
but it @emph{might} mean "Merge the single change that resulted in B's
tip into A".

Any merge, when viewed in detail, is an application of a particular set
of changes -- not necessarily adjacent ones -- to a working copy.  The
user-level interface may allow some of these changes to be specified
implicitly.  For example, many merges involve a single, contiguous range
of changes, with one or both ends of the range easily deducible from
context (i.e., branch root to branch tip).  These inference rules are
not specified here, but it should be clear in most contexts how they
work.

Because each node knows its ancestors, Subversion never merges the same
change twice (unless you force it to).  For example, if after the above
merge, you tell Subversion to merge all B changes into A, Subversion
will notice that two of them have already been merged, and so merge only
the other two changes, resulting in a final ancestry set of:

@example
@group

  @{ A:1-10, B:3-9 @}

@end group
@end example

@c Heh, what about this:
@c
@c    B:3 adds line 3, with the text "foo".
@c    B:5 deletes line 3.
@c    B:7 adds line 3, with the text "foo".
@c    B:9 deletes line 3.
@c
@c The user first merges B:5 and B:9 into A.  If A had that line, it
@c goes away now, nothing more.
@c 
@c Next, user merges B:3 and B:7 into A.  The second merge must
@c conflict.
@c
@c I'm not sure we need to care about this, I just thought I'd note how
@c even merges that seem like they ought to be easily composable can
@c still suck. :-)

This description of merging and ancestry applies to both intra- and
inter-repository merges.  However, inter-repository merging will
probably not be implemented until a future release of Subversion.