Category: glossary

Sep 20 2010

Source Control System glossary of terms for the less-technical

Source control systems are used by software developer to manage source code for the software systems that we write.  They are also called Version Control or Revision Control systems. 

There are many advantages to using a source control system. One, the source code that you write is quickly moved to a shared, backed-up location where other developers can get to it.(This is called COMMITTING the code.)  Two, it allows other developers to get your code quickly. (This is called UPDATING or CHECKING OUT the code).  Three, in the event that two developers modify the same code,  source control systems let you quickly resolve the conflict.  Four, source control systems let you quickly see the changes you made to the code. (This is called DIFF'ing the code)This is just one of MANY advantages to using a source control system over using no source control. 

There are generally two kinds of source control systems…centralized and distributed.   This glossary is more about the centralized kind and is Subversion-oriented.

Source Control System
A client-server based software system for managing the source control of a software development project.  A Source Control System consists of a server application that manages the source control and a client application that is used by the developers to interact with the server. 

Repository
A repository is a specially created folder on the source control server that is used to manage the code for a project or a set of related projects.  The repository has to be created by using the Source Control software.

Checkout
A checkout is what a developer does when he wants to get source files from the source control server for the very first time.  This creates the working copy files and folders onto his machine at the designated location and creates a hard-link between the developers working copy and the repository from which the checkout occurred. 

Commit
Also called a checkin on some system, a commit is when a developer who has made changes to a system or part of a system and pushes those changes to the source control server.  A commit from a developer causes the source control system to create a new revision in the repository.

Update
An update is what a developer does he or she wants to get all of the most recent changes from the source control system onto their own computer.

Revert
A revert is what a developer does when he or she is unhappy with a change made to a source file or files and want to "rollback" the changes to the state that the file(s) had at the last commit.

Diff
Diff'ing is a way for a developer to see what has changed in the source file(s) he or she is working on since the last time a commit was made.

Merge
A merge is what the source control system does when two or more developers have made changes to the same file(s).  (Technically a merge happens at the individual file level although it can happen to many files all at once.)  A merge happens automatically when a developer does an update and a file that he or she is working on has been changed since the last update.  If the source control system is unable to determine how to merge the differences then a merge conflict occurs (see below).  It is a very good idea for the developer to do a commit immediately after a successul merge.

Merge Conflict
A merge conflict happens when two or more developers have made changes to the same file and the source control system is unable to merge the changes into a single new file.  For this to happens the developers generally need to modify the same file AND also modify the same part(s) of the code in the file.  Merge Conflicts have to be resolved manually. 

Revision
A revision represents a "snapshot" of all of the committed source code in a repository at a given point in time.  Revisions, taken together, provide a "history" of the source code development progress.  A revision is automatically created every time someone commits changes to the source control system.  

Log
Every time someone commits file(s) to the source control system, a log entry is created into the source control system's logging system.  Further, at the time of the commit, the developer can add a detailed (or not) note about the changes that are being made which is added to the log entry and makes understanding what happened during a revision a lot easier.  Source control systems have built-in ways of viewing the log entries.

Working Copy
The working copy are the source control files that are currently on a developers computer that were fetched from the source control system using either a checkout or an update.    At any moment the working copy represents the state of the files from a revision PLUS any changes that the developer has made to those files.   This is contrasted with the Working Base which is defined below.  (For Subversion, the working copy will contain hidden .SVN folders for every folder in the working copy which stores the metadata and state for the working copy.  These folders should never be deleted or manually modified.)

Working Base
The working base is the state of the source controlled files on the source control server at a given time.  The working base is changed whenever a developer commits code changes to the system.  A diff, put simply, compares the working copy to the working base and shows you what has changed between the two.  (This is a slight simplification because a diff does NOT need to communicate with the the server in order to happen.  The local system "knows" the state of the working base from the last commit by using the metadata that is stored in the .SVN folders.)

Subversion
Subversion
is a free, open-source source control systemSubversion is technically the server part of the software that manages the revisions, logging and other server side responsibilities.  A developer can still install this "server" component onto their own machine if they want to.  A "real" server is not required.  But in this configuration the server repository will not be shared with other developers.

TortoiseSVN
TortoiseSVN is one of many "client" applications for working with Subversion repositories.  (It widely considered the best client application for Subversion.)  It is free, open-source software.  It integrates with the "Windows Shell" to allow you to manage your source files using Windows Explorer.  It includes ICON OVERLAYS that allow you to see at a glance which files are changes, not-changed, or added.    You manage the source files (commit, update, diff, etc) by using the Windows Explorer context (right-click) menu. 

Repository Browser (Repo-Browser)
Repository Browser is the (aptly named) tool built into TortoiseSVN which lets you view all of the files and folders that exist in a given repository.  To activate Repository Browser you right click on a folder in your working copy and choose TortoiseSVN...Repo-Browser.  For the record, the ONLY way to browse the repository is with a tool like Repo-Browser.  Viewing the folders on the server does not show you anything about what is actually in a repository.

Branches, Projects, and Tags
If you were to Browse a repository using the TortoiseSVN Repository Browser tool, you would see that the root of most of the repositories contain three folders:   Branches, Projects, and Tags.  These folders are created as a CONVENTION and are not in any way enforced by Subversion.  (By convention I mean that it is recommended best practice but not required...but you find that most repositories do follow the convention.)

The Projects folder will usually contain the active development line in it.  In other words, when a developer does a update, commit, or checkout it is to that folder in the repository.  This is usually the case, but it can have, as implied by the name, multiple development lines and projects in it.

The Branches folder will usually contain experimental development lines in it.  It is a kind of sandbox where you can experiment with ideas and changes.  If the ideas work, the changes could be merged back into the main development line in Projects.

The Tags folder will usually contain SNAPSHOTS of the state of the code at a certain point in time.  Each of these snapshots is called a tag.  To create a tag you just copy the files from the main development line in Projects into a specially created tag folder in Tags.  You usually create a tag for each major release.  Once created, you generally would not want to make changes to the tag.  (As such, a developer will rarely want to checkout from a tag folder.  A tag is usually created using Repository Browser.)