Model
*****

This chapter explains the user's view of Subversion --- what ``objects'' you interact with, how they behave, and how they relate to each other.

Working Directories and Repositories
====================================

Suppose you are using Subversion to manage a software project.  There are two things you will interact with: your working directory, and the repository.

Your working directory is an ordinary directory tree, on your local system, containing your project's sources.  You can edit these files and compile your program from them in the usual way.  Your working directory is your own private work area: Subversion never changes the files in your working directory, or publishes the changes you make there, until you explicitly tell it to do so.

After you've made some changes to the files in your working directory, and verified that they work properly, Subversion provides commands to publish your changes to the other people working with you on your project.  If they publish their own changes, Subversion provides commands to incorporate those changes into your working directory.

A working directory contains some extra files, created and maintained by Subversion, to help it carry out these commands.  In particular, these files help Subversion recognize which files contain unpublished changes, and which files are out-of-date with respect to others' work.

While your working directory is for your use alone, the repository is the common public record you share with everyone else working on the project.  To publish your changes, you use Subversion to put them in the repository.  (What this means, exactly, we explain below.)  Once your changes are in the repository, others can tell Subversion to incorporate your changes into their working directories.  In a collaborative environment like this, each user will typically have their own working directory (or perhaps more than one), and all the working directories will be backed by a single repository, shared amongst all the users.

A Subversion repository holds a single directory tree, and records the history of changes to that tree.  The repository retains enough information to recreate any prior state of the tree, compute the differences between any two prior trees, and report the relations between files in the tree --- which files are derived from which other files.

A Subversion repository can hold the source code for several projects; usually, each project is a subdirectory in the tree.  In this arrangement, a working directory will usually correspond to a particular subtree of the repository.

For example, suppose you have a repository laid out like this:

     /trunk/paint/Makefile
                  canvas.c
                  brush.c
            write/Makefile
                  document.c
                  search.c

In other words, the repository's root directory has a single subdirectory named trunk, which itself contains two subdirectories: paint and write.

To get a working directory, you must check out some subtree of the repository.  If you check out /trunk/write, you will get a working directory like this:

     write/Makefile
           document.c
           search.c
           .svn/

This working directory is a copy of the repository's /trunk/write directory, with one additional entry --- .svn --- which holds the extra information needed by Subversion, as mentioned above.

Suppose you make changes to search.c.  Since the .svn directory remembers the file's modification date and original contents, Subversion can tell that you've changed the file.  However, Subversion does not make your changes public until you explicitly tell it to.

To publish your changes, you can use Subversion's commit command:

     $ pwd
     /home/jimb/write
     $ ls -a
     .svn/   Makefile   document.c    search.c
     $ svn commit search.c
     $

Now your changes to search.c have been committed to the repository; if another user checks out a working copy of /trunk/write, they will see your text.

Suppose you have a collaborator, Felix, who checked out a working directory of /trunk/write at the same time you did.  When you commit your change to search.c, Felix's working copy is left unchanged; Subversion only modifies working directories at the user's request.

To bring his working directory up to date, Felix can use the Subversion update command.  This will incorporate your changes into his working directory, as well as any others that have been committed since he checked it out.

     $ pwd
     /home/felix/write
     $ ls -a
     .svn/    Makefile    document.c    search.c
     $ svn update
     U search.c
     $

The output from the svn update command indicates that Subversion updated the contents of search.c.  Note that Felix didn't need to specify which files to update; Subversion uses the information in the .svn directory, and further information in the repository, to decide which files need to be brought up to date.

We explain below what happens when both you and Felix make changes to the same file.

Transactions and Revision Numbers
=================================

A Subversion commit operation can publish changes to any number of files and directories as a single atomic transaction.  In your working directory, you can change files' contents, create, delete, rename and copy files and directories, and then commit the completed set of changes as a unit.

In the repository, each commit is treated as an atomic transaction: either all the commit's changes take place, or none of them take place. Subversion tries to retain this atomicity in the face of program crashes, system crashes, network problems, and other users' actions.  We may call a commit a transaction when we want to emphasize its indivisible nature.

Each time the repository accepts a transaction, this creates a new state of the tree, called a revision.  Each revision is assigned a unique natural number, one greater than the number of the previous revision. The initial revision of a freshly created repository is numbered zero, and consists of an empty root directory.

Since each transaction creates a new revision, with its own number, we can also use these numbers to refer to transactions; transaction N is the transaction which created revision N.  There is no transaction numbered zero.

Unlike those of many other systems, Subversion's revision numbers apply to an entire tree, not individual files.  Each revision number selects an entire tree.

It's important to note that working directories do not always correspond to any single revision in the repository; they may contain files from several different revisions.  For example, suppose you check out a working directory from a repository whose most recent revision is 4:

     write/Makefile:4
           document.c:4
           search.c:4

At the moment, this working directory corresponds exactly to revision 4 in the repository.  However, suppose you make a change to search.c, and commit that change.  Assuming no other commits have taken place, your commit will create revision 5 of the repository, and your working directory will look like this:

     write/Makefile:4
           document.c:4
           search.c:5

Suppose that, at this point, Felix commits a change to document.c, creating revision 6.  If you use svn update to bring your working directory up to date, then it will look like this:

     write/Makefile:6
           document.c:6
           search.c:6

Felix's changes to document.c will appear in your working copy of that file, and your change will still be present in search.c.  In this example, the text of Makefile is identical in revisions 4, 5, and 6, but Subversion will mark your working copy with revision 6 to indicate that it is still current.  So, after you do a clean update at the root of your working directory, your working directory will generally correspond exactly to some revision in the repository.

How Working Directories Track the Repository
============================================

For each file in a working directory, Subversion records two essential pieces of information:

  * what revision of what repository file your working copy is based on (this is called the file's base revision), and

  * a timestamp recording when the local copy was last updated.

Given this information, by talking to the repository, Subversion can tell which of the following four states a file is in:

  * Unchanged, and current.  The file is unchanged in the working directory, and no changes to that file have been committed to the repository since its base revision.

  * Locally changed, and current.  The file has been changed in the working directory, and no changes to that file have been committed to the repository since its base revision.  There are local changes that have not been committed to the repository.

  * Unchanged, and out-of-date.  The file has not been changed in the working directory, but it has been changed in the repository.  The file should eventually be updated, to make it current with the public revision.

  * Locally changed, and out-of-date.  The file has been changed both in the working directory, and in the repository.  The file should be updated; Subversion will attempt to merge the public changes with the local changes.  If it can't complete the merge in a plausible way automatically, Subversion leaves it to the user to resolve the conflict.

Subversion Does Not Lock Files
==============================

Subversion does not prevent two users from making changes to the same file at the same time.  For example, if both you and Felix have checked out working directories of /trunk/write, Subversion will allow both of you to change write/search.c in your working directories. Then, the following sequence of events will occur:

  * Suppose Felix tries to commit his changes to search.c first.  His commit will succeed, and his text will appear in the latest revision in the repository.

  * When you attempt to commit your changes to search.c, Subversion will reject your commit, and tell you that you must update search.c before you can commit it.

  * When you update search.c, Subversion will try to merge Felix's changes from the repository with your local changes.  By default, Subversion merges as if it were applying a patch: if your local changes do not overlap textually with Felix's, then all is well; otherwise, Subversion leaves it to you to resolve the overlapping changes.  In either case, Subversion carefully preserves a copy of the original pre-merge text.

  * Once you have verified that Felix's changes and your changes have been merged correctly, you can commit the new revision of search.c, which now contains everyone's changes.

Some version control systems provide ``locks'', which prevent others from changing a file once one person has begun working on it.  In our experience, merging is preferable to locks, because:

  * changes usually do not conflict, so Subversion's behavior does the right thing by default, while locking can interfere with legitimate work;

  * locking can prevent conflicts within a file, but not conflicts between files (say, between a C header file and another file that includes it), so it doesn't really solve the problem; and finally,

  * people often forget that they are holding locks, resulting in unnecessary delays and friction.

Of course, the merge process needs to be under the users' control. Patch is not appropriate for files with rigid formats, like images or executables.  Subversion allows users to customize its merging behavior on a per-file basis.  You can direct Subversion to refuse to merge changes to certain files, and simply present you with the two original texts to choose from.  (Or, someday, you can direct Subversion to merge using a tool which respects the semantics of the file format.)

Properties
==========

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 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:

  * Clients can use properties to store file attributes, as described above.

  * The Subversion server uses properties to hold attributes of its own, and allow clients to read and modify them.  For example, someday a hypothetical svn-acl property might hold an access control list which the Subversion server uses to regulate access to repository files.

  * 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.

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.

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 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 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:

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

The ancestor set of A:5 is:

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

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:

       { A:1-5 }

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:

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

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

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

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

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

or more compactly:

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

(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

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

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

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

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

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

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 { A:1-8 } plus any local changes.  After committing, A:10's ancestry set is

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

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 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:

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

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 (see Future).