So, you’re in your basement listening to Pink Floyd albums on vinyl, and wearing a tinfoil hat, and writing a version control system.  Your version control system is going to fix the problems of the 783,711 version control systems – free and commercial – that already exist.

Mathematically, it stands to reason that you are going to overlook something.  We have already established that there are 783,711 version control systems available, yet there you are with the same Pink Floyd album side playing over and over writing #783,712.  Because all of them didn’t do it right.  So the odds are you won’t get it exactly right either.  Maybe you’re not quite as clever as you think, or maybe your foil isn’t quite thick enough.  Or maybe you just overlooked something I find very important.  So here we go (in no particular order):

  • Under NO circumstances should the default check-in behavior be to delete the local file.  I’m going way back on this one… but this one bugs me.  When I have to write support for a version control system, I try to use it’s default options as much as possible.  And in this case I did too.  However, I found it such a terrible default it bears mentioning here.  Perhaps it made sense to somebody at a point in time when hard drive space was measured in megabytes.   But not to me.
  • Let us suppose your version control system supports separate repositories at a pre-specified location.  For example you set an environment variable:

If you allow multiple repositories (or modules, herds, gaggles or whatever you choose to call them) to be stored at TINFOIL1,port:80, I should be able to list them all.  There should be a command I can run to see all of them.  If your version control system uses a URL where only one thing can exist:


then this does not apply to you.  I do not have an opinion about which one is better, although the URL method seems to be more modern.  But if there is more than one thing, let me see it – do not make a colleague of mine and I sit and try things until we notice that there is a command that you can run that gives an error message for each module, and we can get it that way. I shouldn’t have to do something wrong in order to stumble across a correct answer.

  • Let me view all versions of a file  across branches.  I won’t go into detail here because I covered this in Manifesto – Part 1 – Branching.  But it is important enough it bears mentioning again.
  • Let me get a file, and put it where I want it.  Do not make me get the whole directory.  Do not make me get the whole directory structure, with just one file in it.  Let me get any version of any file, from any branch, and put it anywhere I please.
  • Let me run any command and specify the output in XML, or some other regular format.  I am adding support for this version control system to SlickEdit after all.  I don’t want to use your API.  I want regular output written to a file I specify, or that I can redirect to a file.
  • When running a version control command, a history or log command for example, let me refer to the file any way available to me.
    • If I am on Windows, let me refer to the local file, using a relative or absolute path, OR using the URL (or whatever the remote specifier is).
    • Do not make me use forward slashes in relative paths while I am working on Windows.
    • Do not make me change to a directory that was checked out and use a relative path.
      • I should be able to sit in “c:\temp” and run “tinfoilvcs history c:\src\project1\file1.cpp”.
  • Let me checkout multiple copies of the same branch/module/whatever.  Most recent version control systems do not have issues with this.  But I often find myself in a situation where I need to fix a bug, but my copy of the branch I am working on is “too dirty”.  So I checkout a new copy, fix the bug, check it in, delete the new copy, and update the other copy.

For extra credit:

  • Let a user plug in a 3rd party GUI diff on their own – so if they would like to run vsdiff.exe to view differences even if they run your version control’s diff command from the command line, they may do so.
  • In the above paragraph, replace “diff” with “3-way merge”.

Now go flip the record over.