At this point, you should understand how each commit creates a new state of the filesystem tree (called a “revision”) in the repository. If you don't, go back and read about revisions in the section called “Revisions”.
Let's revisit the example from
      Chapter 1, Fundamental Concepts.  Remember that you and your
      collaborator, Sally, are sharing a repository that contains two
      projects, paint and
      calc.  Notice that in Figure 4.2, “Starting repository layout”, however, each project
      directory now contains subdirectories named
      trunk and branches.
      The reason for this will soon become clear.
As before, assume that Sally and you both have working
      copies of the “calc” project.  Specifically, you
      each have a working copy of /calc/trunk.
      All the files for the project are in this subdirectory rather
      than in /calc itself, because your team has
      decided that /calc/trunk is where the
      “main line” of development is going to take
      place.
Let's say that you've been given the task of implementing a
      large software feature.  It will take a long time to write, and
      will affect all the files in the project.  The immediate problem
      is that you don't want to interfere with Sally, who is in the
      process of fixing small bugs here and there.  She's depending on
      the fact that the latest version of the project (in
      /calc/trunk) is always usable.  If you
      start committing your changes bit by bit, you'll surely break
      things for Sally (and other team members as well).
One strategy is to crawl into a hole: you can stop sharing information for a week or two, gutting and reorganizing all the files in your private working copy but not committing or updating until you're completely finished with your task. There are a number of problems with this, though. First, it's not very safe. Should something bad happen to your working copy or computer, you risk losing all your changes. Second, it's not very flexible. Unless you manually replicate your changes across different working copies or computers, you're stuck trying to make your changes in a single working copy. Similarly, it's difficult to share your work-in-progress with anyone else. A common software development “best practice” is to allow your peers to review your work as you go. If nobody sees your intermediate commits, you lose potential feedback and may end up going down the wrong path for weeks before another person on your team notices. Finally, when you're finished with all your changes, you might find it very difficult to merge your completed work with the rest of the company's main body of code. Sally (or others) may have made many other changes in the repository that are difficult to incorporate into your working copy when you eventually run svn update after weeks of isolation.
The better solution is to create your own branch, or line of development, in the repository. This allows you to save your not-yet-completed work frequently without interfering with others' changes and while still selectively sharing information with your collaborators. You'll see exactly how this works as we continue.
Creating a branch is very simple—you make a copy of
        your project tree in the repository using the svn
        copy command.  Since your project's source code is
        rooted in the /calc/trunk directory, it's
        that directory that you'll copy.  Where should the new
        copy live?  Wherever you wish.  The repository location in
        which branches are stashed is left by Subversion as a matter
        of project policy.  Finally, your branch will need a name to
        distinguish it from other branches.  Once again, the name you
        choose is unimportant to Subversion—you can use whatever
        name works best for you and your team.
Let's assume that your team (like most) has a policy of
        creating branches in the branches
        directory that is a sibling of the project's trunk
        (the /calc/branches directory in our
        scenario).  Lacking inspiration, you settle
        on my-calc-branch as the name you wish to
        give your branch.  This means that you'll create a new
        directory, /calc/branches/my-calc-branch,
        which begins its life as a copy
        of /calc/trunk.
You may already have seen svn copy used to copy one file to another within a working copy. But it can also be used to do a remote copy—a copy that immediately results in a newly committed repository revision and for which no working copy is required at all. Just copy one URL to another:
$ svn copy http://svn.example.com/repos/calc/trunk \
           http://svn.example.com/repos/calc/branches/my-calc-branch \
      -m "Creating a private branch of /calc/trunk."
Committed revision 341.
$
        This command causes a near-instantaneous commit in the
        repository, creating a new directory in revision 341.  The new
        directory is a copy of /calc/trunk.  This
        is shown in Figure 4.3, “Repository with new copy”.[25]  While
        it's also possible to create a branch by using svn
        copy to duplicate a directory within the working
        copy, this technique isn't recommended.  It can be quite slow,
        in fact!  Copying a directory on the client side is a
        linear-time operation, in that it actually has to duplicate
        every file and subdirectory within that working copy directory
        on the local disk.  Copying a directory on the server,
        however, is a constant-time operation, and it's the way most
        people create branches.
Now that you've created a branch of the project, you can check out a new working copy to start using it:
$ svn checkout http://svn.example.com/repos/calc/branches/my-calc-branch A my-calc-branch/Makefile A my-calc-branch/integer.c A my-calc-branch/button.c Checked out revision 341. $
There's nothing special about this working copy; it simply
        mirrors a different directory in the repository.  When you
        commit changes, however, Sally won't see them when she
        updates, because her working copy is of
        /calc/trunk.  (Be sure to read the section called “Traversing Branches” later in this chapter: the
        svn switch command is an alternative way of
        creating a working copy of a branch.)
Let's pretend that a week goes by, and the following commits happen:
You make a change to
            /calc/branches/my-calc-branch/button.c,
            which creates revision 342.
You make a change to
            /calc/branches/my-calc-branch/integer.c,
            which creates revision 343.
Sally makes a change to
            /calc/trunk/integer.c, which creates
            revision 344.
Now two independent lines of development (shown
        in Figure 4.4, “The branching of one file's history”) are happening on
        integer.c.
Things get interesting when you look at the history of
        changes made to your copy of integer.c:
$ pwd /home/user/my-calc-branch $ svn log -v integer.c ------------------------------------------------------------------------ r343 | user | 2002-11-07 15:27:56 -0600 (Thu, 07 Nov 2002) | 2 lines Changed paths: M /calc/branches/my-calc-branch/integer.c * integer.c: frozzled the wazjub. ------------------------------------------------------------------------ r341 | user | 2002-11-03 15:27:56 -0600 (Thu, 07 Nov 2002) | 2 lines Changed paths: A /calc/branches/my-calc-branch (from /calc/trunk:340) Creating a private branch of /calc/trunk. ------------------------------------------------------------------------ r303 | sally | 2002-10-29 21:14:35 -0600 (Tue, 29 Oct 2002) | 2 lines Changed paths: M /calc/trunk/integer.c * integer.c: changed a docstring. ------------------------------------------------------------------------ r98 | sally | 2002-02-22 15:35:29 -0600 (Fri, 22 Feb 2002) | 2 lines Changed paths: A /calc/trunk/integer.c * integer.c: adding this file to the project. ------------------------------------------------------------------------
Notice that Subversion is tracing the history of your
        branch's integer.c all the way back
        through time, even traversing the point where it was copied.
        It shows the creation of the branch as an event in the
        history, because integer.c was implicitly
        copied when all of /calc/trunk/ was
        copied.  Now look at what happens when Sally runs the same
        command on her copy of the file:
$ pwd /home/sally/calc $ svn log -v integer.c ------------------------------------------------------------------------ r344 | sally | 2002-11-07 15:27:56 -0600 (Thu, 07 Nov 2002) | 2 lines Changed paths: M /calc/trunk/integer.c * integer.c: fix a bunch of spelling errors. ------------------------------------------------------------------------ r303 | sally | 2002-10-29 21:14:35 -0600 (Tue, 29 Oct 2002) | 2 lines Changed paths: M /calc/trunk/integer.c * integer.c: changed a docstring. ------------------------------------------------------------------------ r98 | sally | 2002-02-22 15:35:29 -0600 (Fri, 22 Feb 2002) | 2 lines Changed paths: A /calc/trunk/integer.c * integer.c: adding this file to the project. ------------------------------------------------------------------------
Sally sees her own revision 344 change, but not the change you made in revision 343. As far as Subversion is concerned, these two commits affected different files in different repository locations. However, Subversion does show that the two files share a common history. Before the branch copy was made in revision 341, the files used to be the same file. That's why you and Sally both see the changes made in revisions 303 and 98.
You should remember two important lessons from this section. First, Subversion has no internal concept of a branch—it knows only how to make copies. When you copy a directory, the resultant directory is only a “branch” because you attach that meaning to it. You may think of the directory differently, or treat it differently, but to Subversion it's just an ordinary directory that happens to carry some extra historical information.
Second, because of this copy mechanism, Subversion's
        branches exist as normal filesystem
        directories in the repository.  This is different
        from other version control systems, where branches are
        typically defined by adding
        extra-dimensional “labels” to collections of
        files.  The location of your branch directory doesn't matter
        to Subversion.  Most teams follow a convention of putting all
        branches into a /branches directory, but
        you're free to invent any policy you wish.
[25] Subversion does not support copying between different repositories. When using URLs with svn copy or svn move, you can only copy items within the same repository.