Subversion: Miscellaneous Documentation

Now check out a fresh “working copy” of your project. To do this, we specify a URL to the exact directory within the repository that we want. The parameter after the URL allows us to name the working copy we check out.

$ svn checkout file:///absolute/path/to/myrepos/trunk/someproject wc
A  wc/foo
A  wc/bar
A  wc/baz
A  wc/baz/gloo
A  wc/baz/bloo
      

Now we have a working copy in a local directory called wc, which represents the location /trunk/someproject in the repository (assuming the repository's root is file:///absolute/path/to/myrepos.)

For the sake of example, let's duplicate the working copy, and pretend it belongs to someone else:

$ cp -R wc wc2
      

From here, let's make some changes within our original working copy:

$ cd wc
$ echo "new text" >> bar     # change bar's text
$ svn propset color green foo      # add a metadata property to foo
$ svn delete baz                   # schedule baz directory for deletion
$ touch newfile    
$ svn add newfile                  # schedule newfile for addition

That's a lot of changes! If we were to leave and come back tomorrow, how could we remember what changes we'd made? Easy. The status command will show us all of the “local modifications” in our working copy:

$ svn status                   # See what's locally modified
M   ./bar
_M  ./foo
A   ./newfile
D   ./baz
D   ./baz/gloo
D   ./baz/bloo
      

According to this output, three items are scheduled to be (D)eleted from the repository, one item is scheduled to be (A)dded to the repository, and two items have had their contents (M)odified in some way. For more details, be sure to read about svn status in Chapter 3 of the Subversion Book.

Now we decide to commit our changes, creating Revision 2 in the repository:

$ svn commit -m "fixed bug #233"
Sending    bar
Sending    foo
Adding     newfile
Deleting   baz
Transmitting data...
Committed revision 2.
      

The -m argument is a way of specifying a log message: that is, a specific description of your change-set sent to the repository. The log message is now attached to Revision 2. A future user might peruse repository log messages, and now will know what your Revision 2 changes were for.

Finally, pretend that you are now Felix, or some other collaborator. If you go wc2 (that other working copy you made), it will need the svn update command to receive the Revision 2 changes:

$ cd ../wc2                # change to the back-up working copy

$ svn update               # get changes from repository
U   ./bar
_U  ./foo
A   ./newfile
D   ./baz
      

The output of the svn update command tells Felix that baz was (D)eleted from his working copy, newfile was (A)dded to his working copy, and that bar and foo had their contents (U)pdated.

If for some reason bar contained some local changes made by Felix, then the server changes would be merged into bar: that is, bar would now contain both sets of changes. Whenever server changes are merged into a locally-modified file, two possible things can happen:

In the real world, we're not always so perfect. Formatting preferences may change over time, or we may just make mistakes. There are things you can do to minimize the problems of reformatting.

These are good guidelines to follow:

Here's an example of a sweeping reformat:

$ svn co file:///repo/path/trunk indent_wc
$ indent -gnu indent_wc/src/*.[ch]
$ svn commit -m 'Ran indent -gnu src/*.[ch]' indent_wc
        

This follows all rules: there were no semantic changes mixed in (no files were changed other than through indent). The indent commandline was given, so the changes can be very easily duplicated. All the reformatting was done in a single revision.

Let's say these changes occurred to the trunk at revision 26. The head revision is now 42. You created a branch at revision 13 and now want to merge it back into the trunk. Ordinarily you'd do this:

$ svn co file://repo/path/trunk merge_wc
$ svn merge -r 13:head file://repo/path/branches/mybranch merge_wc
… # resolve conflicts
$ svn commit -m 'Merged branch'
      

But with the reformatting changes, there will be many, many conflicts. If you follow these rules, you can merge more easily:

$ svn co -r 25 file://repo/path/trunk merge_wc
$ svn merge -r 13:head file://repo/path/branches/mybranch merge_wc
… # resolve conflicts
$ indent -gnu src/*.[ch]
$ svn up
… # resolve conflicts
$ svn commit -m 'Merged branch'
      

In English, the procedure is:

When viewing differences between revisions, you can customize svn diff output to hide whitespace changes. The -x argument passes arguments through to GNU diff. Here are some useful arguments:

The commit emails always show whitespace-only changes. commit-email.pl uses svnlook diff to get differences, which doesn't support the -x option.

Different platforms (Unix, Windows, Mac OS) have different conventions for marking the line endings of text files. Simple editors may rewrite line endings, causing problems with diff and merge. This is a subset of the formatting problems.

Subversion has built-in support for normalizing line endings. To enable it, set the svn:eol-style property to ``native''. See Properties in the Subversion book for more information.

Subversion does not have any way to merge or view differences of binary files, so it's critical that these have accurate log messages. Since you can't review your changes with svn diff immediately before committing, it's a particularly good idea to write the log entry as you go.

This is the first part of the “Greg Hudson” problem, so named because he was the first one to bring it up and define it well. :-)

Suppose our working copy has directory DIR:1 containing file foo:1, along with some other files. We remove foo and commit.

Already, we have a problem: our working copy still claims to have DIR:1. But on the repository, revision 1 of DIR is defined to contain foo—and our working copy DIR clearly does not have it anymore. How can we truthfully say that we still have DIR:1?

One answer is to force DIR to be updated when we commit foo's deletion. Assuming that our commit created revision 2, we would immediately update our working copy to DIR:2. Then the client and server would both agree that DIR:2 does not contain foo, and that DIR:2 is indeed exactly what is in the working copy.

This solution has nasty, un-user-friendly side effects, though. It's likely that other people may have committed before us, possibly adding new properties to DIR, or adding a new file bar. Now pretend our committed deletion creates revision 5 in the repository. If we instantly update our local DIR to 5, that means unexpectedly receiving a copy of bar and some new propchanges. This clearly violates a UI principle: ``the client will never change your working copy until you ask it to.'' Committing changes to the repository is a server-write operation only; it should not modify your working data!

Another solution is to do the naive thing: after committing the deletion of foo, simply stop tracking the file in the .svn administrative directory. The client then loses all knowledge of the file.

But this doesn't work either: if we now update our working copy, the communication between client and server is incorrect. The client still believes that it has DIR:1—which is false, since a “true” DIR:1 contains foo. The client gives this incorrect report to the repository, and the repository decides that in order to update to revision 2, foo must be deleted. Thus the repository sends a bogus (or at least unnecessary) deletion command.

After deleting foo and committing, the file is not totally forgotten by the .svn directory. While the file is no longer considered to be under version control, it is still secretly remembered as having been “deleted”.

When the user updates the working copy, the client correctly informs the server that the file is already missing from its local DIR:1; therefore the repository doesn't try to re-delete it when patching the client up to revision 2.

Again, suppose our working copy has directory DIR:1 containing file foo:1, along with some other files.

Now, unbeknownst to us, somebody else adds a new file bar to this directory, creating revision 2 (and DIR:2).

Now we add a property to DIR and commit, which creates revision 3. Our working-copy DIR is now marked as being at revision 3.

Of course, this is false; our working copy does not have DIR:3, because the “true” DIR:3 on the repository contains the new file bar. Our working copy has no knowledge of bar at all.

Again, we can't follow our commit of DIR with an automatic update (and addition of bar). As mentioned previously, commits are a one-way write operation; they must not change working copy data.

Let's enumerate exactly those times when a directory's local revision number changes:

In this light, it's clear that our “overeager directory” problem only happens in the second situation—those times when we're committing directory propchanges.

Thus the answer is simply not to allow property-commits on directories that are out-of-date. It sounds a bit restrictive, but there's no other way to keep directory revisions accurate.