10 Tips for Mastering Version Control Systems

Version control systems are a great way to share source code between developers. They provide the ability for multiple people to simultaneously work on the same code base without the danger of sending files back and forth constantly. Make a mistake while developing and rest assured that the simple press of a button can roll back the code to a fresh square one. History has shown that working without a version control system is a disaster waiting to happen! Version control systems are an essential development tool and there are a number of tips for mastering and getting the most out of these systems.


Tip #1 – Commit Frequently

Embedded software at times takes on a life of its own and tends to have a temperamental attitude. A developer makes a few minor changes and the entire system destabilizes into frenzy. The developer has no fear and reverses the few changes he made and voila! The system is still broken. Without a version control system, the developer now scratches their head in panic and tries to understand what change they made that they don’t remember from 5 minutes ago! The engineer using version control on the other hand performs a right click and simply reverts back to the previous working version of the code and now cautiously moves forward. But what if the developer had gone days without committing his code? Days worth of effort could be lost which is why developers using version control should commit frequently! Complete a feature and commit. Get a partial feature working, commit. This will not only save the engineer time when things go wrong but also leave a nice trail in the version control system of the changes that were made.


Tip #2 – Fill in the commit log

It is great if an engineer commits their code changes frequently; however, it can prove to be a futile effort if sufficient information is not provided in the change log. Most version control tools will allow comments to be made at the time code is committed. Fill in the log with helpful and useful information! Don’t leave it blank or put cryptic information here! In the future, a bug may get introduced into the code and as the developer back tracks the versions, it will be essential that the log contain useful information on what changed. It takes only a few moments and will save many hours of frustration and headaches! Try and come up with a common log format that needs to be filled in before each commit.


SVN Commit Log


Tip #3 – Don’t forget to add files to the VCS

Version control systems have been known to play a trick or two on a developer. The biggest is when a developer thinks that he is committing code when he actually isn’t! How can this happen? Most systems require that when you create a file you add it to revision control. If this isn’t done then the system will happily commit and ignore those files that haven’t been added! So don’t forget to add files to the VCS!


SVN Add Files Dialog


Tip #4 – Define a commit process

It is really easy to forget to add files to revision control, properly log changes and a variety of tasks associated with a version control system. The best thing that can be done is to create a process for each of the different tasks that need to be performed. For example, create a commit process. It would look something like the following:


1) Update version log within the code base

2) Copy the changes

3) Add files to the VCS

4) Begin the commit process

5) Paste the change log into the commit comments and add any additional relevant comments

6) Complete the commit


Additional processes can be documented such as creating code branches, merging code branches with the main source trunk and creating official releases of code.


Tip #5 – Lock modules that are in process

There are times when multiple developers are working on a project and might need to modify the same module. Version control systems often have a feature that allows the programmer to lock a particular module for editing. This prevents another programmer from modifying the file at the same time and thus helps to prevent conflicts within the code base.


Tip #6 – Utilize the code comparison tools

There will inevitably come a time when a bug creeps into the code unnoticed. At some point it will be discovered and then the question will be asked, “What changed?”. The only way to know for sure is to compare different revision levels of the code. This could be a painful process if it weren’t for the fact that most version control systems include a difference tool. This tool allows a side by side comparison of files within the code across different versions of the code. These alterations are highlighted and can then be examined as the potential source of the bug.


SVN Difference Tool Dialogue


Tip #7 – Don’t fear merging code branches

The concept of branching the code into a separate version, making changes and then later merging it back into the main version trunk can be scary! What happens if something goes wrong? What if it isn’t merged properly and the main branch becomes corrupted? Beginners will often fear merging branches but do not be concerned! This is a common occurrence especially when multiple developers are involved in the project. If a mistake is made it is easy to go back a version and restart! The best way to get over this fear is to practice which will be discussed further in tip number ten.


Tip #8 – Integrate with tools like Trac

There are a number of tools available today that integrate nicely into a version control system. These tools can range from bug tracking to project management tools. Trac is a favorite that not only allows different versions of software to be planned, tracks bugs and even allows the code base stored in the repository to be browsed! This comes in very handy during code reviews and planning meetings! The best part is that the tool is free! It can be downloaded from http://trac.edgewall.org/




Tip #9 – Take advantage of continuous integration

There is a neat concept that is taking the world by storm known as continuous integration. There are a couple different versions of the idea but the one that is most interesting occurs when the developers commit their code. As part of the commit, the integration server will compile the code and also run unit testing! If any errors are found they are reported to the developers! The idea is that tests are developed along with the code and whenever a new version is created it is checked immediately for bugs! It is a unique concept that should be taken advantage of! There are a number of free continuous integration servers including one known as Hudson. They are worth taking a look at if at a minimum to understand the technology.


Tip #10 – Create a test repository and experiment

No matter how many tips and tricks one reads about nothing beats real world experience. The most commonly used version control system is SVN. Both client and server side applications can be downloaded for free. VisualSVN server is a good server side to use provided you don’t need a very large database. Once it reaches a certain size the user is required to start paying for it. On the client side Tortoise SVN is a great client! Download each and start experimenting! Before you know it you will be the master of VCS!