Subversion and TortoiseSVN

Subversion uses a central database which contains all your version-controlled files with their complete history. This database is referred to as the repository. The repository normally lives on a file server running the Subversion server program, which supplies content to Subversion clients (like TortoiseSVN) on request.  While the repository stores information in the form of a normal filesystem tree consisting of files and directories, it also remembers every change ever written to it: every change to every file, and even changes to the directory tree itself, such as the addition, deletion, and rearrangement of files and directories.

When a client reads data from the repository, it normally sees only the latest version of the filesystem tree. But the client also has the ability to view previous states of the filesystem. For example, a client can ask historical questions like, “ what did this directory contain last Wednesday? ”, or “ who was the last person to change this file, and what changes did they make? ” These are the sorts of questions that are at the heart of any version control system: systems that are designed to record and track changes to data over time.

We have SVN installed on our departmental server at physics.wku.edu. This server hosts a source-code control repository that will be used by the class for all assignments and project submissions.  The root address for our SVN repository is 

svn://physics.wku.edu/phys318/

A Subversion working copy is an ordinary directory tree on your local system, containing a collection of files. This is where you do the real work. Every developer (student in this course) has his/her own working copy, sometimes known as a sandbox, on their local computer. You can pull down the latest version from the repository, work on it locally without affecting anyone else, then when you are happy with the changes you made commit them back to the repository. Subversion will never incorporate other people’s changes, nor make your own changes available to others, until you explicitly tell it to do so.

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 directory (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, your working copy contains a (normally hidden) subdirectory named .svn, also known as the working copy administrative directory . The files in this administrative directory help Subversion recognize which files contain unpublished changes, and which files are out-of-date with respect to others’ work.

A Subversion command which creates a local working copy in an empty directory by downloading versioned files from the repository.  When you checkout a directory you will notice that every file has a green check mark in the bottom left corner. These are TortoiseSVN’s status icons which are only present in a working copy. The green state indicates that the file is unchanged from the version in the repository.

This Subversion command is used to pass the changes in your local working copy back into the repository, creating a new repository revision.

A svn commit operation can publish 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 the complete set of changes as a unit.

In the repository, each commit is treated as an atomic transaction: either all the commits changes take place, or none of them take place. Subversion retains 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 zero, and consists of nothing but an empty root directory.

This Subversion command pulls down the latest changes from the repository into your working copy, merging any changes made by others with local changes in the working copy.

All files in a freshly checked out working copy have a green checkmark as overlay. That means the Subversion status of the file in the working copy is normal.  As long as a file is not edited in the working copy its status will continue to be normal and the overlay will continue to be the green checkmark.  However, the relationship of the working copy file to its counterpart at the repository isn’t known or described by the green checkmark status icon.  It could be in either of the two following states.

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 working revision. A commit of the file will do nothing, and an update of the file will do nothing.

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. A commit of the file will do nothing, and an update of the file will fold the latest changes into your working copy.

As soon as you start editing a file, its status changes to modified and the icon overlay then changes to a red exclamation mark. That way you can easily see which files were changed since you last updated your working copy and need to be committed.  Again, the relationship of the working copy file to its counterpart in the repository isn’t described by the modified status icon, but it could be in either of the two following states.

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, thus a commit of the file will succeed in publishing your changes, and an update of the file will do nothing.

Locally Changed and Out-of-Date

The file has been changed both in the working directory, and in the repository. A commit of the file will fail with an out-of-date error. The file should be updated first; an 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.

If and update results in conflicts between local changes and changes downloaded from the repository, then the icon changes to a yellow exclamation mark and the file status is said to be conflicted.

The Added overlay is simply used to represent the added status when an item has been added to version control.  This status indicates that this file is new to version control meaning that it only exists in the working copy and not in the repository.  It will be copied to the repository during the next commit.

The Unversioned overlay is used to represent an item which is in the unversioned state. This is an item in a versioned folder, but which is not under version control itself. This overlay is optional and may not show up on your system.