model.texi

linux subdivision ying gai ke yi le ba

@node Model
@chapter 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.

@menu
* Working Directories and Repositories::  
* Transactions and Revision Numbers::  
* How Working Directories Track the Repository::  
* Subversion Does Not Lock Files::  
* Properties::                  
* Merging and Ancestry::        
@end menu

@c -----------------------------------------------------------------------
@node Working Directories and Repositories
@section 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 @dfn{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 @dfn{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:
@example
/trunk/paint/Makefile
             canvas.c
             brush.c
       write/Makefile
             document.c
             search.c
@end example

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

To get a working directory, you must @dfn{check out} some subtree of the
repository.  If you check out @file{/trunk/write}, you will get a working
directory like this:
@example
write/Makefile
      document.c
      search.c
      .svn/
@end example
This working directory is a copy of the repository's @file{/trunk/write}
directory, with one additional entry --- @file{.svn} --- which holds the
extra information needed by Subversion, as mentioned above.

Suppose you make changes to @file{search.c}.  Since the @file{.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 @samp{commit} command:
@example
$ pwd
/home/jimb/write
$ ls -a
.svn/   Makefile   document.c    search.c
$ svn commit search.c
$
@end example

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

Suppose you have a collaborator, Felix, who checked out a working
directory of @file{/trunk/write} at the same time you did.  When you
commit your change to @file{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
@samp{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.
@example
$ pwd
/home/felix/write
$ ls -a
.svn/    Makefile    document.c    search.c
$ svn update
U search.c
$
@end example

The output from the @samp{svn update} command indicates that Subversion
updated the contents of @file{search.c}.  Note that Felix didn't need to
specify which files to update; Subversion uses the information in the
@file{.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.


@c -----------------------------------------------------------------------
@node Transactions and Revision Numbers
@section Transactions and Revision Numbers

A Subversion @samp{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 @dfn{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 @dfn{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 @var{n}
is the transaction which created revision @var{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:
@example
write/Makefile:4
      document.c:4
      search.c:4
@end example

At the moment, this working directory corresponds exactly to revision 4
in the repository.  However, suppose you make a change to
@file{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:
@example
write/Makefile:4
      document.c:4
      search.c:5
@end example
Suppose that, at this point, Felix commits a change to
@file{document.c}, creating revision 6.  If you use @samp{svn update} to
bring your working directory up to date, then it will look like this:
@example
write/Makefile:6
      document.c:6
      search.c:6
@end example
Felix's changes to @file{document.c} will appear in your working copy of
that file, and your change will still be present in @file{search.c}.  In
this example, the text of @file{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.


@c -----------------------------------------------------------------------
@node How Working Directories Track the Repository
@section How Working Directories Track the Repository

For each file in a working directory, Subversion records two essential
pieces of information:
@itemize @bullet
@item
what revision of what repository file your working copy is based on (this is called the file's @dfn{base revision}), and
@item
a timestamp recording when the local copy was last updated.
@end itemize

Given this information, by talking to the repository, Subversion can
tell which of the following four states a file is in:
@itemize @bullet
@item
@b{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.
@item
@b{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.
@item
@b{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.
@item
@b{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.
@end itemize


@c -----------------------------------------------------------------------
@node Subversion Does Not Lock Files
@section 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 @file{/trunk/write}, Subversion will allow
both of you to change @file{write/search.c} in your working directories.
Then, the following sequence of events will occur:
@itemize @bullet
@item
Suppose Felix tries to commit his changes to @file{search.c} first.  His
commit will succeed, and his text will appear in the latest revision in
the repository.
@item
When you attempt to commit your changes to @file{search.c}, Subversion
will reject your commit, and tell you that you must update
@file{search.c} before you can commit it.
@item
When you update @file{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.
@item
Once you have verified that Felix's changes and your changes have been
merged correctly, you can commit the new revision of @file{search.c},
which now contains everyone's changes.
@end itemize

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:
@itemize @bullet
@item
changes usually do not conflict, so Subversion's behavior does the right
thing by default, while locking can interfere with legitimate work;
@item
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,
@item
people often forget that they are holding locks, resulting in
unnecessary delays and friction.
@end itemize

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


@c -----------------------------------------------------------------------
@node Properties
@section Properties