Using Working Folders in Version Control

Source Control HOWTO - Chapter 5

a writable state, so they simply open their text editor or their IDE and begin making changes.  At the appropriate time, the SCM tool will notice the change and add that file to the pending change set.

Users who prefer "checkout-edit-checkin" actually have a somewhat more consistent rule for their work.  The SCM tool must be explicitly informed of all changes to the working folder.  All files in their working folder are usually marked read-only.  The SCM tool's Checkout command not only informs the server of the checkout request, but it also flips the bit on the working file to make it writable.
Review Changes

One of the most important features provided by a working folder is the ability to review all of the changes I have made.  For SCM tools that do keep track of a pending change set (Vault, Perforce, Subversion), this is the place to start.  The following screen dump shows the pending change set pane from the Vault client, which is showing me that I have currently made two changes in my working folder:

The pending change set view shows all kinds of changes, including adds, deletes, renames, moves, and modified files.  It is helpful to keep an eye on the pending change set as I work, verifying that I have not forgotten anything.

However, for the case of a modified file, this visual display only shows me which files have changed.  To really review my changes, I need to actually look inside the modified files.  For this, I invoke a diff tool.  The following screen dump is from a popular Windows diff tool called Beyond Compare :

This picture is fairly typical of the visual diff tool genre, showing both files side-by-side and highlighting the parts that are different.  There are quite a few tools like this.  The following screen dump is from the visual diff tool which is provided with Vault:

Best Practice: Run Diff Just Before you Checkin, Every Time

Never checkin your changes without giving them a quick review in some sort of a diff tool.

The left panel shows version 21 of sgdmgui_props.cpp, which is the current version in the repository.  The right panel shows my working file.  The colored regions show exactly what has changed:

  • On line 33 I changed the type of this function from long to short.
  • At line 35 I inserted a one-line comment.

Note that SourceGear's diff tool shows inserted lines by drawing lines in the center gap to indicate exactly where the insertion occurs.  In contrast, Beyond Compare is showing a dead region on the left side across from the inserted line on the right.  This particular issue is a matter of personal preference.  The latter approach does have the benefit that identical lines are always across from each other.

Both of these tools do a nice job on the modification to line 33, showing exactly which part of the line was changed.  Most of the recent visual diff tools support this ability to highlight intraline differences.

Visual diff tools are indispensable.  They give me a way to quickly review exactly what has changed.  I strongly recommend you make a habit of reviewing all of your changes just before you checkin.  You can catch a lot of silly mistakes by taking the time to be sure that your changes look the way you think they look.

Undo Changes

Sometimes I make changes which I simply don't intend to keep.  Perhaps I tried to fix a bug and discovered that my fix introduced five new bugs that are worse than the one I started with.  Or perhaps

About the author

AgileConnection is a TechWell community.

Through conferences, training, consulting, and online resources, TechWell helps you develop and deliver great software every day.