Who Should Read This
Read on if you are new to change control, or believe that change control only applies to software, or that it is only meant for large projects.
If you are a software pro working with large software projects, you can still read this if you want a gentle introduction to Subversion or svn as it is called.
We have all heard those trite remarks about change -- “... change is the only constant ...”, or similar ones, especially before an unpleasant corporate announcement. These overused remarks about change are unfortunately true. During the course of a day, we make numerous (hopefully!) interrelated changes, updates, or transformations to our work products to reach specific project goals. Needless to say, these changes need to be tracked along with the rationale behind each if we are to prevent ourselves from repeating mistakes, or simply want to recall why we did what we did one month ago! Note that we are not talking about only code or documents here; your work products could be a portfolios of photographs, animations, or some arbitrary binary format.
A change control discipline also gives you additional advantages such as being able to develop simultaneous versions of work products for different purposes or clients, rolling back to a previous arbitrary version, or setting up trial development in a so-called branch to bring it back to the main work stream after due review. You also have a running history of how your work product has evolved over time and features. Fetching from a change managed repository also prevents you from creating those fancifully named multiple copies of a file just to keep track of its versions. To reiterate: we use the words 'work product' and 'development' in the broadest sense and not just as applied to software. You might as well be creating a banner ad for your client as much as a Firefox plugin.
In the rest of this article we will see how to build a simple personal change control discipline for your day-to-day work using a version control tool. As you will note, 'control' and 'management' have been used interchangeably, though a little hair splitting will yield rich dividends in terms of how different these terms are.
Subversion is version control system available on the Linux (and similar) platforms. If you are trapped in a proprietary world by choice, circumstance, or compulsion, you should try TortoiseSVN. Here, we confine ourselves to the Linux platform.
Subversion works by creating a time line of your work products from their inception (or from the point they are brought under version control) to the present point in time, by capturing snapshots of your work products at discrete points that you decide. Each snapshot is a version. You can traverse this time line and extract specific versions for use.
How does subversion do it? It versions entire directories. A new version of your directory will be created even if you change one file in it. Don't worry; this does not lead to an explosion of file size with each version.
Explaining some terminology, albeit informally, should make the going easier from here. Subversion stores your project(s) in a repository. For the purpose of this article, our repository will stay on the local machine. A revision is nothing but a particular snapshot of the project directory. A working directory is your sandbox. This is where you check out a particular version of your project directory from the repository, make any modifications to it, and then do a check in back into the repository. Revision numbers are bumped up with each check in. You can revert a configuration item, which is like undoing any changes you made. If all this sounds a little abstruse, don't worry, because we will shortly set up our repository so that you can try things out. A commit is when you...., well commit a change done to a file into the repository.
Subversion is mostly bundled with a Linux distribution. Find out if you have yours with a 'man svn' or 'svn -h' or a 'whereis svn' command.
Setting up Your Repository
You can set up your repository in your home directory if you are working on a shared environment. If you have a machine to yourself, you might want to create an 'svn' account with /sbin/nologin (politely refuses logins) as the shell. Your repository might then be '/home/svn/repos'.
Subversion is a command line tool. But the only command you will ever issue for the purpose of this article will be to set up your repository:
$ svnadmin create /path/to/your/repository
The rest, as they say, is GUI!
Let Us Get Visual
A GUI for subversion is a great tool for learning and working even if you decide to settle for the command line once you get more proficient. eSvn (http://zoneit.free.fr/esvn/) is a Qt-based graphical front end for Subversion. Follow the instructions with the download to compile and install eSvn. Run esvn and this is how it will look with the File | Options... dialog open. Make sure you enter the correct path to svn if not for the other items.
Structuring Your Project Directories
There is a recommended way to structure files in your project directory that goes very well with a particular working methodology we will briefly dwell up on later. Create the following directories:
$ mkdir /path/to/import/into/svn/trunk
$ mkdir /path/to/import/into/svn/branches
$ mkdir /path/to/import/into/svn/tags
The 'trunk' directory could be called 'main' or 'head' or whatever else you feel signifies the main line of work product development. Your project file tree goes under 'trunk'. Keep the 'branches' and 'tags' directories for now; their significance will become clear later on. If you choose a different structure and want to change to above structure later, it is also possible to copy or move things around. But since we are on a learning curve, let us stick to the instructions.
With your project files under .../trunk and the empty .../branches and .../tags directories, you are all set to import your project into svn.
Importing Your Project into svn
The rest of this article uses a contrived example to illustrate basic operations of version control.
Our repository is /home/svn/repos. We created it using the svnadmin command we mentioned earlier.
Under /tmp we create a myproject directory, and under /tmp/myproject the directories trunk, branches, and tags respectively. Under trunk we have three files a.txt, b.txt, and c.txt. These might be .jpg or .mov or .odt or even a directory tree for all we care, but we look at .txt files for the moment.
The directories will show up as follows:
[/tmp]$ ls -RF myproject/
branches/ tags/ trunk/
a.txt b.txt c.txt
Run the esvn GUI if you do not have it running already. Bring up the File | Import... dialog. For URL enter file:///home/svn/repos/myproject and for Local path enter /tmp/myproject. Note svn's way of specifying a local URL with three slashes. Provide a message that says this is the initial version. svn should report that it has successfully added your project files.
Checking out Your First Version
Once your initial version is created, you should check it out into a working directory to start working on it. Remember the sand box we spoke of earlier? Create a directory that you would like to be your working directory. You will 'check out' files from the repository into this working directory, make any modifications to the files, and check them back in. svn automatically bumps up the revision number and moves your entire directory tree one step ahead on the version time line after every commit.
Create a working directory in your home directory. We will call it 'wd'. Go to the File | Checkout dialog. For the URL, enter file:///home/svn/repos/myproject and for the working directory enter /home/your-user-id/wd. Here is how it looks for me.
Once you have checked out your repository into your working directory, refresh your view (View | Refresh Local...) and you should see the working directory tree in the left pane; click on 'trunk' and you should see files in the right. All files appear green because they are 'up-to-date'. We will now work exclusively in our working directory.
Typical Working Cycle
Let us illustrate a typical working cycle with some simple actions – adding a file and modifying another. Create a new file d.txt in the trunk of your working directory – the same directory where you have the files a.txt, b.txt, and c.txt. Next, open a.txt in your favorite editor and type in “Hello, World” or similar interesting text – the idea is to modify this file. Refresh your esvn interface and note what you see.
You will see that d.txt is represented by a query shaped icon because svn does not know about this file. 'a.txt' appears red, meaning that it has been modified and is out-of-date with the repository. The two files b.txt and c.txt continue to appear green since they are still in sync with the repository.
To bring d.txt under version control, you need to make svn aware of it first. Do this by clicking the second mouse button on it and selecting 'Add'. The icon for d.txt turns red signifying that it is registered with the repository now but out-of-date. Time to commit these files to the repository.
For a commit, select a.txt with the second mouse button and select 'Commit...' from the context menu. You can provide comments in the commit dialog that become part of the change control log. Commit d.txt similarly with the comment that this is the initial version. You can also commit both the files together by clicking on 'trunk' while doing the commit. All files are now green and in sync with the repository.
If you committed the files individually, you will note that a.txt is at revision 2 and d.txt is at revision 3. The revision number is always the number of the latest commit. This is svn's way of telling you that three snapshots exist for your files: the first is the initial one, the second is the one in which a.txt changed, and the third is the one in which d.txt was added. It is a good idea to bring your working directory to the latest revision though it may not always be necessary. To do this, click on 'trunk' with Mouse-2 and select 'Update'. You will note that the 'Revision' column bumps up to 3 and the 'Last revision' column shows the last revision when a particular file changed. For instance a.txt is at revision 3 but it was last changed at revision 2 and has not changed since.
You can examine change log of a file or a folder using the Query | Log command. As you keep working with the eSVN, you will find the tool bars very convenient to use.
Among the features that support advanced usage are 'Branches' and 'Tags'. Branches are needed when you have a main line (or flow) of development but need to create a slightly different version on a temporary or permanent basis for a specific purpose.
To branch at the current revision, just copy your 'trunk' to a destination named 'branch/branch-name'. Recall that we already have a 'branch' directory as part of our repository structure. To create a 'demo' branch: select the root of the working directory ('wd' in out case), bring up the Modify | Copy(local) dialog, enter 'wd/trunk' for source and 'wd/branches/demo' for the destination. You will see a folder 'demo' appear under the 'branches' directory. 'Commit' this folder and its content to create the 'demo' branch. From this point, you can make independent changes to the files in the trunk and the branch.
Tags are nothing but branches that will (and should) never grow. If you have a particular state of your repository that you want to release or preserve, you can copy it to the 'tags' branch. You might want to create a tag named 'Version-1' of a web site that is out for review even as you continue working on it.
You can always check out a particular tagged version or a branch from the repository. You can 'merge' branches or delete them altogether after their job is done.
It is always a good idea to check out only the trunk or a particular branch into a working directory rather than the entire project tree which might be huge.
Try It Out
If you have not followed a change control discipline for your personal work, this may sound difficult at first. However, a change control discipline will also give you rewards commensurate with the intricacy and complexity of your work.