For this article I am using Debian Etch which has version 1.4.2 available. Ubuntu LTS has version 1.3.1 and other distributions have different versions. The latest and greatest version (at the time of writing) is 1.4.5 and is available from source from the subversion website.
Let’s get stuck in and install subversion.
sudo aptitude install subversion
That’s it for the installation.
Create a repository
Let’s create a repository. I’m going to create a folder named ‘repository’ in my home directory. It can, of course, be named whatever you like and be located wherever you like:
cd ~ mkdir repository
If you have a look inside the repository folder, there is nothing there:
ls repository ...
Let’s create the skeleton structure subversion uses to control repositories:
svnadmin create /home/demo/repository
Take a look now:
ls repository/ conf/ dav/ db/ format hooks/ locks/ README.txt
Don’t change anything in the repository folder. We’ll learn how to add files and projects shortly.
Our first project
To import ‘something’ to our subversion repository and begin version control, that ‘something’ has to exist.
You can import whatever you like (there are a few exceptions, but not many). The most popular use for subversion is to manage projects, from small websites to very large, multi developer systems.
Let’s create a temporary folder for our project. We’ll call it ‘project1’
Now start the project by creating a text file:
I know that project1 is not incredibly realistic; you could have created a rails skeleton or the base of your php website or whatever you wanted, the point is to have something to import to the subversion system.
The recommended layout for a subversion project includes three folders called branches, tags and trunk. I’m not going to go into branches and tags here but concentrate on the ‘trunk’ of your project. Then name is very apt – think of it as the backbone of your project – this is where the main folders and files are placed.
To import project1, issue the command:
svn import /home/demo/project1/ file:///home/demo/repository/project1/trunk -m "Initial import of project1"
A couple of things to notice include the order of the command (source folder followed by destination) and the ‘-m’ which is short for ‘message’.
When you import a version of your project, always add a message describing what the import is. I can assure you that in a week, never mind a month, you will have no idea what version 127 was if you do not include a message.
The output of that command is:
Adding /home/demo/project1/hello.txt Committed revision 1.
Now we delete the original project1 as we don’t need it because we’ve imported it into the version control system.
So, delete the original:
rm -rf project1/
Check out a repository
The point of subversion is to control versions of a project.
To do this we need to ‘check out’ the initial project (this will be version 1). Once done, we can then adjust the project (add files, change files, etc) and at various points ‘check in’, or commit, any changes we have made. So the next ‘commit’ would make version 2 of the project and so on.
Assuming you are working on the same machine as your subversion repository (we’ll talk about remote manipulation in later articles), create a ‘work’ directory and check-out version 1 of project1:
mkdir work cd work svn co file:///home/demo/repository/project1/trunk project1
The output is:
A project1/hello.txt Checked out revision 1.
Move into your newly checked-out project1 and have a look:
cd project1 ls ... hello.txt
Look familiar? It’s the original project1 we imported a moment ago.
Let’s make a small change to project1 and add a folder and file (remember we changed directory so we are now working in the project1 folder):
mkdir goodbye touch goodbye/goodbye.txt
We need to add this change to subversion. This does not commit the change to a new version: it simply tells subversion there is a new file (or folder, etc) that has been added to the project and to include them when the next commit command is given:
svn add goodbye
The output will show that the directory and contents of ‘goodbye’ have been added:
A goodbye A goodbye/goodbye.txt
To actually commit this momentous change to project1 (thus creating version 2) issue the following:
svn commit -m "Added goodbye section in accordance with milestone 1"
The output shows what is happening:
Adding goodbye Adding goodbye/goodbye.txt Transmitting file data . Committed revision 2.
If you want to delete files or folders from the project, use the same syntax as shown above for ‘add’ but use ‘delete’ instead:
svn delete goodbye
The output shows:
D goodbye/goodbye.txt D goodbye
Again, this has not committed the changes. It has simply informed subversion that when there is a ‘commit’ command, to delete those files and folders.
So to actually commit the recent changes and create a new revision (version):
svn commit -m "Deleted goodbye section"
Deleting goodbye Committed revision 3.
So now we’re on version 3 of project1.
There is a great deal more you can do with subversion and one other skill you will probably require early on is how to check-out different versions. We’re on version 3 now, but let’s say we also want to check out version 2.
Using the same procedure as before and create a directory to work in. This time, when checking out project1, use the ‘-r’ option indicating the version you want to use:
cd ~/work mkdir project1-older svn co -r 2 file:///home/demo/repository/project1/trunk project1-older
This will checkout revision (version) 2 of project1 to the project1-older folder.
Although only an introduction, a fair amount has been covered here. You will get used to these basics very quickly and want more functionality within a very short time.
The next article will concentrate on serving the repository with svnserve so you can check out the project to your local workstation.