Source Control Checkins


This month, I will explore the various situations wherein a repository is modified, starting with the simplest case of a single developer making a change to a single file.

Editing a Single File

Consider the simple situation where a developer needs to make a change
to one source file.  This case is obviously rather simple:

  1. Checkout the file
  2. Edit the working file as needed
  3. Checkin the file

I won't talk much about step 2 here, as it doesn't really involve the SCM tool directly.  Editing the file usually involves the use of some other tools, like an integrated development environment (IDE). But I do want to explore steps 1 and 3 in greater detail.

Step 1: Checkout

Checking out a file has two basic affects:

  • On the server, the SCM tool will remember the fact that you have the file checked out so that others may be informed.On your client, the SCM tool will prepare your working file for editing by changing it to be writable.

The server side of checkout

File checkouts are a way of communicating your intentions to others.  When you have a file checked out, other users can be aware and avoid making changes to that file until you are done with it.  The checkout status of a file is usually displayed somewhere in the user interface of the SCM client application.  For example, in the following screendump from Vault, users can see that I have checked out libsgdcore.cpp:

Best Practice: Use checkouts and locks carefully

It is best to use checkouts and locks only when you need them. A checkout discourages others from modifying a file, and a lock prevents them from doing so. You should therefore be careful to use these features only when you actually need them.

Don't checkout files just because you think you might need to edit them.

Don't checkout whole folders. Checkout the specific files you need.

Don't checkout hundreds or thousands of files at one time.

Don't hold exclusive locks any longer than necessary.

Don't go on vacation while holding exclusive locks on files.

This screendump also hints at the fact there are actually two kinds of checkouts.  The issue here is the question of whether two people can checkout a file at the same time.  The answer varies across SCM tools.  Some SCM tools can be configured to behave either way.

Sometimes the SCM tool will allow multiple people to checkout a file at the same time.  SourceSafe and Vault both offer this capability as an option.  When this "multiple checkouts" feature is used, things can get a bit more complicated.  I'll talk more about this later.

If the SCM tool prevents anyone else from checking out a file which I have checked out, then my checkout is "exclusive" and may be described as a "lock."  In the screendump above, the user interface is indicating that I have an exclusive lock on libsgdcore.cpp.  Vault will allow no one else to checkout this file.

The client side of checkout

On the client side, the effect of a checkout is quite simple:  If necessary, the latest version of the file is retrieved from the server.  The working file is then made writable, if it was not in that state already.

All of the files in a working folder are made read-only when the SCM tool retrieves them from the repository.  A file is not made writable until it is checked out.  This prevents the developer from accidentally editing a file.

Undoing a checkout

Normally, a checkout ends when a checkin happens.  However, sometimes we checkout a file and subsequently decide that we did not need to do so.  When this happens, we "undo the checkout."  Most SCM tools have a command which offers this functionality.  On the server side, the command will remove the checkout and release any exclusive lock that was being held.  On the client side, Vault offers the user three choices for


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.