It's time to move from the abstract to the concrete. In this section, we'll show real examples of Subversion being used.
Throughout this book, Subversion uses URLs to identify versioned files and directories in Subversion repositories. For the most part, these URLs use the standard syntax, allowing for server names and port numbers to be specified as part of the URL:
$ svn checkout http://svn.example.com:9834/repos …
But there are some nuances in Subversion's handling of URLs
        that are notable.  For example, URLs containing the
        file:// access method (used for local
        repositories) must, in accordance with convention, have either a
        server name of localhost or no server name at
        all:
$ svn checkout file:///var/svn/repos … $ svn checkout file://localhost/var/svn/repos …
Also, users of the file:// scheme on
        Windows platforms will need to use an unofficially
        “standard” syntax for accessing repositories
        that are on the same machine, but on a different drive than
        the client's current working drive.  Either of the two
        following URL path syntaxes will work, where
        X is the drive on which the repository
        resides:
C:\> svn checkout file:///X:/var/svn/repos … C:\> svn checkout "file:///X|/var/svn/repos" …
In the second syntax, you need to quote the URL so that the vertical bar character is not interpreted as a pipe. Also, note that a URL uses forward slashes even though the native (non-URL) form of a path on Windows uses backslashes.
You cannot use Subversion's file:// URLs
          in a regular web browser the way typical
          file:// URLs can.  When you attempt to view
          a file:// URL in a regular web browser, it
          reads and displays the contents of the file at that location
          by examining the filesystem directly.  However, Subversion's
          resources exist in a virtual filesystem (see the section called “Repository Layer”), and your browser
          will not understand how to interact with that
          filesystem.
Finally, it should be noted that the Subversion client will automatically encode URLs as necessary, just like a web browser does. For example, if a URL contains a space or upper-ASCII character as in the following:
$ svn checkout "http://host/path with space/project/españa"
then Subversion will escape the unsafe characters and behave as though you had typed:
$ svn checkout http://host/path%20with%20space/project/espa%C3%B1a
If the URL contains spaces, be sure to place it within quotation marks so that your shell treats the whole thing as a single argument to the svn program.
You've already read about working copies; now we'll demonstrate how the Subversion client creates and uses them.
A Subversion working copy is an ordinary directory tree on your local system, containing a collection of files. You can edit these files however you wish, and if they're source code files, you can compile your program from them in the usual way. Your working copy is your own private work area: Subversion will never incorporate other people's changes, nor make your own changes available to others, until you explicitly tell it to do so. You can even have multiple working copies of the same project.
After you've made some changes to the files in your working copy and verified that they work properly, Subversion provides you with commands to “publish” your changes to the other people working with you on your project (by writing to the repository). If other people publish their own changes, Subversion provides you with commands to merge those changes into your working copy (by reading from the repository).
A working copy also contains some extra files, created and
        maintained by Subversion, to help it carry out these commands.
        In particular, each directory in your working copy contains a
        subdirectory named .svn, also known as
        the working copy's administrative
        directory.  The files in each administrative
        directory help Subversion recognize which files contain
        unpublished changes, and which files are out of date with
        respect to others' work.
A typical Subversion repository often holds the files (or source code) for several projects; usually, each project is a subdirectory in the repository's filesystem tree. In this arrangement, a user's working copy will usually correspond to a particular subtree of the repository.
For example, suppose you have a repository that contains
        two software projects, paint and
        calc.  Each project lives in its own
        top-level subdirectory, as shown in Figure 1.6, “The repository's filesystem”.
To get a working copy, you must check
        out some subtree of the repository.  (The term
        check out may sound like it has something to do
        with locking or reserving resources, but it doesn't; it simply
        creates a private copy of the project for you.) For example,
        if you check out /calc, you will get a
        working copy like this:
$ svn checkout http://svn.example.com/repos/calc A calc/Makefile A calc/integer.c A calc/button.c Checked out revision 56. $ ls -A calc Makefile button.c integer.c .svn/
The list of letter As in the left
        margin indicates that Subversion is adding a number of items
        to your working copy.  You now have a personal copy of the
        repository's /calc directory, with one
        additional entry—.svn—which
        holds the extra information needed by Subversion, as mentioned
        earlier.
Suppose you make changes to button.c.
        Since the .svn directory remembers the
        file's original modification date and contents, Subversion can
        tell that you've changed the file.  However, Subversion does
        not make your changes public until you explicitly tell it to.
        The act of publishing your changes is more commonly known as
        committing (or checking
        in) changes to the repository.
To publish your changes to others, you can use Subversion's svn commit command:
$ svn commit button.c -m "Fixed a typo in button.c." Sending button.c Transmitting file data . Committed revision 57.
Now your changes to button.c have
        been committed to the repository, with a note describing your
        change (namely, that you fixed a typo).  If another user
        checks out a working copy of /calc, she
        will see your changes in the latest version of the
        file.
Suppose you have a collaborator, Sally, who checked out a
        working copy of /calc at the same time
        you did.  When you commit your change to
        button.c, Sally's working copy is left
        unchanged; Subversion modifies working copies only at the
        user's request.
To bring her project up to date, Sally can ask Subversion to update her working copy, by using the svn update command. This will incorporate your changes into her working copy, as well as any others that have been committed since she checked it out.
$ pwd /home/sally/calc $ ls -A Makefile button.c integer.c .svn/ $ svn update U button.c Updated to revision 57.
The output from the svn update command
        indicates that Subversion updated the contents of
        button.c.  Note that Sally didn't need to
        specify which files to update; Subversion uses the information
        in the .svn directory as well as further
        information in the repository, to decide which files need to
        be brought up to date.
An svn commit operation publishes changes to any number of files and directories as a single atomic transaction. In your working copy, you can change files' contents; create, delete, rename, and copy files and directories; and then commit a complete set of changes as an atomic transaction.
By atomic transaction, we mean simply this: either all of the changes happen in the repository, or none of them happens. Subversion tries to retain this atomicity in the face of program crashes, system crashes, network problems, and other users' actions.
Each time the repository accepts a commit, this creates a new state of the filesystem 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 0 and consists of nothing but an empty root directory.
Figure 1.7, “The repository” illustrates a nice way to visualize the repository. Imagine an array of revision numbers, starting at 0, stretching from left to right. Each revision number has a filesystem tree hanging below it, and each tree is a “snapshot” of the way the repository looked after a commit.
It's important to note that working copies 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 copy from a repository whose most recent revision is 4:
calc/Makefile:4
     integer.c:4
     button.c:4
At the moment, this working directory corresponds exactly
        to revision 4 in the repository.  However, suppose you make a
        change to button.c, and commit that
        change.  Assuming no other commits have taken place, your
        commit will create revision 5 of the repository, and your
        working copy will now look like this:
calc/Makefile:4
     integer.c:4
     button.c:5
Suppose that, at this point, Sally commits a change to
        integer.c, creating revision 6.  If you
        use svn update to bring your working copy
        up to date, it will look like this:
calc/Makefile:6
     integer.c:6
     button.c:6
Sally's change to integer.c will
        appear in your working copy, and your change will still be
        present in button.c.  In this example,
        the text of Makefile is identical in
        revisions 4, 5, and 6, but Subversion will mark your working
        copy of Makefile with revision 6 to
        indicate that it is still current.  So, after you do a clean
        update at the top of your working copy, it will generally
        correspond to exactly one revision in the repository.
For each file in a working directory, Subversion records
        two essential pieces of information in the
        .svn/ administrative area:
What revision your working file is based on (this is called the file's working revision)
A timestamp recording when the local copy was last updated by the repository
Given this information, by talking to the repository, Subversion can tell which of the following four states a working file is in:
The file is unchanged in the working directory, and no changes to that file have been committed to the repository since its working revision. An svn commit of the file will do nothing, and an svn update of the file will do nothing.
The file has been changed in the working directory, and no changes to that file have been committed to the repository since you last updated. There are local changes that have not been committed to the repository; thus an svn commit of the file will succeed in publishing your changes, and an svn update of the file will do nothing.
The file has not been changed in the working directory, but it has been changed in the repository. The file should eventually be updated in order to make it current with the latest public revision. An svn commit of the file will do nothing, and an svn update of the file will fold the latest changes into your working copy.
The file has been changed both in the working directory and in the repository. An svn commit of the file will fail with an “out-of-date” error. The file should be updated first; an svn update command will attempt to merge the public changes with the local changes. If Subversion can't complete the merge in a plausible way automatically, it leaves it to the user to resolve the conflict.
This may sound like a lot to keep track of, but the svn status command will show you the state of any item in your working copy. For more information on that command, see the section called “See an overview of your changes”.
As a general principle, Subversion tries to be as flexible as possible. One special kind of flexibility is the ability to have a working copy containing files and directories with a mix of different working revision numbers. Unfortunately, this flexibility tends to confuse a number of new users. If the earlier example showing mixed revisions perplexed you, here's a primer on why the feature exists and how to make use of it.
One of the fundamental rules of Subversion is that a “push” action does not cause a “pull,” nor vice versa. Just because you're ready to submit new changes to the repository doesn't mean you're ready to receive changes from other people. And if you have new changes still in progress, svn update should gracefully merge repository changes into your own, rather than forcing you to publish them.
The main side effect of this rule is that it means a working copy has to do extra bookkeeping to track mixed revisions as well as be tolerant of the mixture. It's made more complicated by the fact that directories themselves are versioned.
For example, suppose you have a working copy entirely at
          revision 10.  You edit the
          file foo.html and then perform
          an svn commit, which creates revision 15
          in the repository.  After the commit succeeds, many new
          users would expect the working copy to be entirely at
          revision 15, but that's not the case!  Any number of changes
          might have happened in the repository between revisions 10
          and 15.  The client knows nothing of those changes in the
          repository, since you haven't yet run svn
          update, and svn commit doesn't
          pull down new changes.  If, on the other hand,
          svn commit were to automatically download
          the newest changes, it would be possible to set the
          entire working copy to revision 15—but then we'd be
          breaking the fundamental rule of “push”
          and “pull” remaining separate actions.
          Therefore, the only safe thing the Subversion client can do
          is mark the one
          file—foo.html—as being at
          revision 15.  The rest of the working copy remains at
          revision 10.  Only by running svn update
          can the latest changes be downloaded and the whole working
          copy be marked as revision 15.
The fact is, every time you run
          svn commit your working copy ends up
          with some mixture of revisions.  The things you just
          committed are marked as having larger working revisions than
          everything else.  After several commits (with no updates
          in between), your working copy will contain a whole mixture
          of revisions.  Even if you're the only person using the
          repository, you will still see this phenomenon.  To examine
          your mixture of working revisions, use the svn
          status command with the --verbose option (see the section called “See an overview of your changes” for more
          information).
Often, new users are completely unaware that their working copy contains mixed revisions. This can be confusing, because many client commands are sensitive to the working revision of the item they're examining. For example, the svn log command is used to display the history of changes to a file or directory (see the section called “Generating a List of Historical Changes”). When the user invokes this command on a working copy object, he expects to see the entire history of the object. But if the object's working revision is quite old (often because svn update hasn't been run in a long time), the history of the older version of the object is shown.
If your project is sufficiently complex, you'll discover that it's sometimes nice to forcibly backdate (or update to a revision older than the one you already have) portions of your working copy to an earlier revision; you'll learn how to do that in Chapter 2, Basic Usage. Perhaps you'd like to test an earlier version of a submodule contained in a subdirectory, or perhaps you'd like to figure out when a bug first came into existence in a specific file. This is the “time machine” aspect of a version control system—the feature that allows you to move any portion of your working copy forward and backward in history.
However you make use of mixed revisions in your working copy, there are limitations to this flexibility.
First, you cannot commit the deletion of a file or directory that isn't fully up to date. If a newer version of the item exists in the repository, your attempt to delete will be rejected to prevent you from accidentally destroying changes you've not yet seen.
Second, you cannot commit a metadata change to a directory unless it's fully up to date. You'll learn about attaching “properties” to items in Chapter 3, Advanced Topics. A directory's working revision defines a specific set of entries and properties, and thus committing a property change to an out-of-date directory may destroy properties you've not yet seen.