As promised, a post about subversion workflow, but first some basic concepts.

Commit

Remember being taught journalism in high school English class? A good story must provide answers to four questions: “Who?”, “What?”, “When?”, and “Where?” Or so we were taught.

When you commit a change, subversion records four pieces of information:

1. Subversion records WHO committed the change
2. Subversion records WHAT the change was (a description of the change)
3. Subversion records WHEN the change was committed
4. Subversion records WHERE the change was made (which files or directories in your working copy were changed)

With each change, subversion increments the revision number of the repository. You can then diff against a particular revision or retrieve a particular revision as you like.

The command:

svn commit --message "Description of change" foo.txt

will record your change to foo.txt in your working copy and the “Who?”, “What?”, “When?”, and “Where?” of this change to your subversion repository.

Update

Not only will you want to sync revisions in your working copy to your repository, but sync revisions in your repository to your working copy. The command:

svn update

allows you to do just that. Suppose that foo.txt has been changed since your last update, and it is the seventeenth revision of the repository, then the command will yield:

U foo.txt
Updated to revision 17

This means that your working copy has been modified to reflect the changes to foo.txt and that it now reflects revision 17 of the repository. The letter code U is one of several codes that can be issued. These include:

• U foo—file foo has been updated
• A foo—file or directory foo has been added
• D foo—file or directory has been deleted
• G foo—file foo has been updated but you have made local changes in your working copy not reflected in the repository but these changes do not intersect
• C foo—file foo in your working copy has changes that conflict with the changes to foo in the reposiroty

Cha-Cha-Cha-Changes

So far we have discussed committing changes to the repository, and updating the working copy to reflect the changes to the repository, but how do we make these changes.

There are two kinds of changes:

1. Changes to individual files
2. Changes to the structure of the directory

Changes to individual files is easy. Just make the changes in the appropriate editing program. You don’t need to issue in any subversion specific commands.

Changes to the structure of the directory, however, requires subversion’s help. Fortunately, the relevant commands are easy to understand.

The command:

svn add foo

schedules the file or directory foo to be added to the repository next time you make a commit.

The command:

svn delete foo

schedules the file or directory foo for deletion from the repository next time you commit.

The command:

svn copy foo bar

creates a copy of foo called bar and bar is scheduled for addition to the repository next time you commit

The command:

svn move foo bar

creates a copy of foo called bar and schedules bar for addition and schedules foo for deletion.

Reviewing Changes

Before committing your changes, it is a good idea to review the changes you made. Helpfully, subversion has provided some useful tools for ding this.

First up is the command:

svn status

If this command is issued at the root of your working copy it will yield a description of all the changes that you have made since last updating. The command yields a list of files and directories preceded by letter codes indicating the nature of the changes made. These include:

• M foo—foo has been modified since last updating
• A foo—foo is scheduled for addition
• D foo—foo is scheduled for deletion
• C foo—foo has conflicts with an update
• ? foo—subversion doesn’t know about foo. You may want to add it or remove it.

If svn status indicates that foo.txt has been modified, you may want to examine these changes in detail in order to write a helpful commit message. The command:

svn diff

run at the root of the working copy will print out a list of changes to modified files in diff format. As I observed in a previous post, diff format displays line differences, not word differences. This is not great for prose since paragraphs in text files are long lines so multiple differences in a paragraph will not be adequately represented. Fortunately, subversion allows you to use external diff programs. I will make a separate post about this later.

One more tool. The command:

svn revert foo

will roll back the changes you made to foo to the state foo was in when the working copy was last updated.

The Workflow

With these basic concepts in mind, we can now describe your workflow:

1. Update your working copy
2. Make changes to your working copy
3. Review your changes
4. Resolve any conflicts (to be described in a separate post)
5. Commit your changes.

Subversion was designed for multiple programmers to work on a given project. What benefits does all this provide the single user? Besides providing a database of all changes and a record of these, the workflow really comes into its own when working from multiple locations. Suppose you are working both at home and at work on different machines. Adhering to this workflow will make sure that you are always in sync. This is a vastly more efficient and non-ad hoc framework for keeping your mission critical files in sync than emailing them or keeping them on a flash drive. These methods are helpful, yes. But their ad hoc nature is ultimately a recipe for confusion.

One final thought. GUI front ends such as svnX are helpful, but you should try to master the command line basics. And always remember, the command:

svn help

is your friend.