Source Control Checkins


fix that bug," using the word "checkin" to include any of the following types of changes to the repository:

  • Create a new folder
  • Add a file
  • Rename a file or folder
  • Delete a file or folder
    Move a file or folder

It may seem odd to refer to these operations using the word "checkin," because there is no corresponding "checkout" step.  However, this looseness is typical of the way people use the word "checkin," so you'll get used to it.

I will take this opportunity to say a few things about how these operations behave.  If we conceptually think of a folder as a list of files and subfolders, each of these operations is actually a modification of a folder.  When we create a folder inside folder A, then we are modifying folder A to include a new subfolder in its list.  When we rename a file or folder, the parent folder is being modified.

Just as the version number of a file is incremented when we modify it, these folder-level changes cause the version number of a folder to be incremented.  If we ask for the previous version of a folder, we can still retrieve it just the way it was before.  The renamed file will be back to the old name.  The deleted file will reappear exactly where it was before.

It may bother you to realize that the "delete" command in your SCM tool doesn't actually delete anything.  However, you'll get used to it.

Atomic Transactions
I've been talking mostly about the simple case of making a change to a single source code file.  However, most programming tasks require us to make multiple repository changes.  Perhaps we need to edit more than one file to accomplish our task.  Perhaps our task requires more than just file modifications, but also folder-level changes like the addition of new files or the renaming of a file.

When faced with a complex task that requires several different operations, we would like to be able to submit all the related changes together in a single checkin operation.  Although tools like SourceSafe and CVS do not offer this capability, some source control systems (like Vault and Subversion) do include support for "atomic transactions."

Best Practice: Group your Checkins Logically
I recommend that each transaction you check into the repository should correspond to one task. A "task" might be a bug fix or a feature. Include all of the repository changes which were necessary to complete that task, and nothing else. Avoid fixing multiple bugs in a single checkin transaction.The concept is similar to the behavior of atomic transactions in a SQL database.  The Vault server guarantees that all operations within a transaction will stay together.  Either they will all succeed, or they will all fail.  It is impossible for the repository to end up in a state with only half of the operations done.  The integrity of the repository is assured.

To ensure that a transaction can contain all kinds of operations, Vault supports the notion of a pending change set.  Essentially, the Vault client keeps a running list of changes you have made which are waiting to be sent to the server.  When you invoke the Delete command, not only will it not actually delete anything, but it doesn't even send the command to the server.  It merely adds the Delete operation to the pending change set, so that it can be sent later as part of a group.

In the following screen dump, my pending change set contains three operations.  I have modified libsgdcore.cpp.  I have renamed libsgdcore.h to headerfile.h.  And

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.