Source Control Management Systems

TL;DR: It lets you make significant code and structural changes without fear, experiment features safely and much more.

This post is a bit different from the rest of the posts in this blog. It is aimed towards developers in their starting stages (typically), primarily single developers working on even the smallest project. But the ideas apply to everyone, and experienced developers might learn a thing or two, so it’s worthwhile for them to continue reading as well.

The need

Developers, especially in the beginning of their journey, don’t understand what an SCM is (SCM is an abbreviation to Source Control Management software, things like Subversion, Mercurial, GIT, Perforce and so on; sometimes called “Revision Control”) or don’t always realize its importance. When I began programming, my most advanced “version control” practice was copying & pasting the whole project to a folder aside, making changes, and then DIFFing the copied folder with the current working folder. Backup meant sending myself the project directory structure by email.

If you don’t know the basics of SCM systems, just take some small amount of time and learn it (links at the bottom of this post). Everyone loves GIT; I love GIT And Mercurial, although GIT is much more in fashion these days. But I think Subversion (SVN) is much more straight-forward to use when you’re a single developer. Its Windows tooling, if you’re using Windows, is no doubt better than the others, and I’ve used at least four different SCMs til now.

Even the simplest “Hello, world” program these days consists of external libraries or packages besides your own code. Adding a package is an action that throws in multiple server and client files, in multiple locations, in addition to configuration changes scattered in XML or JSON files. Often you want to add a feature package, test it and if it doesn’t work OK just remove it. Tracking what files and configuration snippets a package adds, without an SCM of some kind, is a real hassle. You basically have to copy all your project aside, add the package, save everything and DIFF the old package with the new one. Then if you indeed want to wipe it out by manually restoring everything, you find that it is a tedious and error-prone work. Yes, development frameworks do allow you to uninstall a package but there are always leftovers.

Sometimes you suspect that some files are not really needed, or are auto-generated. You want to clean up your project. With an SCM it’s easy. Just delete these files with no fear and test the results. No good? just revert and the files are back in their place.

Another often overlooked benefit of an SCM is that it allows you to track image file changes. (Not user-generated image files; I’m talking about images that are actually part of your app.) You can apply image compression and easily diff the “before” and “after” to watch for any details loss, then easily revert if needed and try again with a different compression tool. If you hook a good file diff tool (like Beyond Compare) to your SCM you’ll be able to do all sorts of file comparisons, including comparisons of binary files of certain types (images, PDF, DOC and more).

My SCM usage workflow with a new project

My usual workflow with small projects is this (it is still true for bigger ones, with or without other team members, but this time I apply additional SCM practices like branching – but that’s beyond the scope of this post):

  1. I start with a fresh, stock boilerplate / scaffolded project. In .NET it’s the File -> New Project wizard, which at the end creates a whole project structure with config files, server packages, code files, sample CSS etc. In NodeJS+Express it’s any express app command and with Yeoman it’s yo generator. Whatever your environment is, it probably has some baseline project to begin with.

  2. I then immediately and before anything else create a repository (I use GIT but as I said before, Mercurial or Subversion are perfectly fine as well) and do a first commit with the message: “Initial commit”.

  3. At this stage I build the first code (if needed) and make sure it’s working and displaying some meaningful output. Depends on the project and the sophistication of the scaffold, this can be anything between nothing to a full sample HTML page. What’s important here is to make sure there are no errors whatsoever, because if there are – then you should recheck your initial project initialization procedure for any mistakes. It even happened to me more than once that there was actually a bug in the tool I used itself.

    This step is highly critical. In case of any error arising at this stage, you can be sure that if you followed the project initialization / scaffold instructions carefully, then the error does not result in you having done something wrong but rather with the tool you’ve used itself or with the files it generates.

  4. At this point you should go ahead and iteratively add your code, validating your project functionality often. Whenever you have a new functional chunk, commit it (again, there are other important stuff like testing but we’re not covering it here right now). But in particular, make sure your commits are atomic – that is, each commit should only change one thing in your project. If, while coding, you’re fixing code indents, whitespace etc. – commit them in a commit of its own, without any functional changes. If you rename variables or do any other refactoring – commit it on its own. If you’re adding a package – first commit the package addition itself, and only then commit new code that uses the package.

Working this way is awesome. I’m using SCMs for 10 years now and can’t imagine how I lived before. Creating copies of root directories? sending ZIP files to myself? OMG.

And it’s so easy to jump on and use an SCM.

There are even more scenarios where an SCM really shines. When I code some feature, very often I experiment things and try. I’d quickly create temporary code, probing code and debug statements, I’d comment blocks here and there, sometimes I’d even not bother naming variables appropriately if all I want to see is some proof that some technique I’m using is really functioning. Since I keep my commits atomic (isolated), I don’t get these experiments mixed up with other stuff. Then at the end, when I’m happy with the functionality, I just use GIT to show me the code differences between now and the last “stable”/”committed” version and I start cleaning up the junk, probably renaming variables and class/method names, deleting all debug statements etc. and what I commit to GIT is a very clean version of the code.

I could continue with more examples but I want to keep this post not too long. Hopefully I’ve covered the bigger advantages for using an SCM.

If you’re looking for a good recommendation for a starter, I wouldn’t necessarily recommend GIT although as I said I use it, and many people will argue with me on that. Subversion is much more useful for single-developer scenarios, and its Windows tooling are superb, much better than GIT’s and Mercurial’s, in my opinion. Note: eventually you’d progress to using command-line for SCM actions but really don’t worry about it now.

Links

Two useful links to begin with:

  1. A Visual Guide to Version Control – explains the ideas regardless of any specific SCM or platform. Skim through it quickly at least. It’s nicely worded and shown many graphical illustrations to explain the various points.

  2. The 10 commandments of good source control management – true for every environment but mostly focussed on Subversion, Windows and .NET so if that’s your environment I wouldn’t skip this one.

and one great Kindle eBook:

Good luck!

The logos at the beginning of this post are courtesy of: GIT: Jason Long; Mercurial: Matt Mackall; Subversion: Tyrus Christiana

Why You Should Use a Source Control Management System for Even the Simplest, Single-Developer Project
  • Nice post!nnIn addition, I’d like to point out JetBrains WebStorm IDE, which already contains a local history feature:nhttps://www.jetbrains.com/webstorm/features/nnIt’s a very powerful feature, and I think that modern IDEs should include it out of the box.

    • It’s a really nice feature I didn’t know about (I don’t use WebStorm). Nevertheless, an SCM has other huge benefits and even WebStorm itself integrates them nicely into its IDE so really there’s no reason not to use it 🙂

  • TheBuzzSaw

    Every developer everywhere should use SCM for every personal project!nnMastering Git has changed the way I write software. Using SCM for even the smallest projects allows me to code without fear. Already, Git has rescued me because I was able to diagnose my problem by diff’ing my code with my previous commit (which I knew to be stable).nnI used to believe that branching was only for teams. NOPE! I branch when I am alone now. It lets me go crazy with an experimental implementation of some subsystem but still be able to return to the stable build and continue “regular” development. This is particularly helpful when the time comes to show off a working build to a friend/colleague. You never know when that opportunity pops up. Without a proper SCM, you’d have to scramble around your mess to get it working again!nnLong Live SCM

  • Yoav

    I beg to differ on the tooling aspect – at least free tooling – git’s tooling on windows surpass SVN’s BY FAR!nntl;dr : https://github.com/gitextensions/gitextensions/releasesnnI'm an intermediate developer in a big company, working solo for almost 4 years now, with hands-on experience in TFS, git and SVN.nmy previous project used git (with gitextensions frontend) and no central repository (so basically svn, right?) but the current project forces me to use SVN (Tortoise SVN frontend), and must I say – nnwhat a downgrade! The “contextual” user-experience of Tortoise SVN is virtually non-existent, as you are forced to navigate blindly through heaps of changes, only to bulk-commit everything in sheer frustration after losing track of what is what.nnI can even see my colleagues’ – many of them much more experienced than I am – struggling with maintaining their SVN-based project history meaningful (easily branchable, revertable, etc.)nngit has been my savior – nothing less – as I had to branch my way through naive(read: dumb) managerial decisions and secretly keep track of 6 branches of the product, cherry-pick (same commit across several branches)left-and-right and merge core functionality whenever the official build hit a brick wall. In the end, the client chose to use one of my home-brewed branches instead of the official build which fully-complied to the requirements.nnmoreover, I’ve successfully integrated gitextensions into the workflows of numerous engineers,scientists and students – all with no SCM background whatsoever – and after a brief “small commits make happy merges” lecture they were good to go!nnhappy mergingnhttp://devopsreactions.tumblr.com/post/50800607139/how-an-svn-user-sees-git-workflow

  • Great article, i’ve just come across your blog and will be subscribing!nnI completely agree about the need for SCM. I work by myself 95% of the time, but I have never looked back from my decision to start using SCM for ALL my projects, even my “play” projects for practicing things.nnI chose Git because of it’s branching, which IMO is much better than anything SVN offtered in comparison). I combine TortoiseGit and command line (using GitBash) depending on what I’m doing, and find both to be very powerful. Using SVN on a few projects that I do with other people, I personally find it far less powerful, and more errors come up in it than i’ve ever had with Git.nnI use branches for any feature requests, and this allows me to continue making changes and releasing them for production in the meantime. This was actually the original thing that made me decide to set up SCM (back then using the awful Visual SourceSafe, cringe), because I was working on some major changes to a site that i’m the sole developer on, and they needed a change to production in the meantime, and suddenly things got HAIRY.nnI also use SCM for my documents (proposals, design files, files from clients etc), because it makes me feel safer knowing that I always have an old version of anything I change.nI recently started moving all my repositories to BitBucket, rather than having them on my local server, can highly recommend it.

    • Thanks for that Bron! Indeed Git (or any other SCM) is great for all sorts of version tracking, even with documents and other files that are not software code. And yes – GIT branching and merging is better than SVN etc.nnnLooking forward to seeing you in my mailing list 🙂

Enter my mailing list to get high quality full-stack updates directly to your inbox. Just pure content.

I will never spam you and never share your email address.

x