Fedora Core 3 as a Multimedia Laptop OS

I recently upgraded my laptop, a Dell Inspiron 8200, to Fedora Core 3. Fedora Core 3 is a widely used Linux distribution that is the successor to RedHat Linux. If you are unfamiliar with Fedora, you can learn more at the following URLs:

  • http://fedora.redhat.com/

  • http://www.fedorafaq.org/

  • http://fedora.linux.duke.edu/fedorapeople/

This article is a review of Fedora Core 3, and takes the form of a description of my experiences upgrading my laptop machine. The experiences described here actually took place over the course of several days, but I will not always present an exact chronological sequence of events, but will instead smooth out the narrative some for the sake of clarity, while still giving you a fair sense of how long each stage took.

The big drama in this event was my desire to actually get a number of devices up and running on a laptop so that I could write this review. You should understand that Linux was originally a server OS, not a desktop OS. Furthermore, laptops present more challenges that do desktops. As a result, I was setting the bar high by asking Linux to perform not as a server, but as a multimedia workstation, and to run not on a desktop machine, but on a laptop.

In the past, I will confess that I often relied on Windows to perform certain tasks. For instance, if I couldn’t burn a CD, rip CDs, or play music on Linux, well, there was always a Windows machine around somewhere for those tasks. I just used the Linux desktop for programming and creating documents, tasks for which it was well suited. But my goal here was to write a review of Fedora Core 3 as a multimedia workstation, which meant I had to actually get my multimedia tools up and running on a Linux laptop.

Further impetus was provided by the fact that I also have been using my Linux laptop at work, where I really only have good access to one machine at a time. That meant my laptop was playing a larger role in my life than it had before. In other words, there was no Windows machine to turn to at work if things weren’t working for me.

The one final note I should add is that I am the sole Linux user in a very hardcore Windows shop. I had absolutely no one to turn to for advice. I had to figure everything out by taking strange and unusual steps like reading manuals and browsing the web.

So all bets were off this time. I was going to dedicate some time to seeing if I could get my laptop into a truly functional state using Linux, and Linux alone. As you will see, I ended up having a fair amount of success, but the price I paid was high. In short, I could do what I wanted to do, but it wasn’t easy.

Additional Caveats

Linux has always been a better server and networking platform than Windows. It has always been faster and more stable than Windows. For several years now it has had OpenOffice, a tool that opens, edits and saves Microsoft Office files and that competes reasonably well with Microsoft Office in terms of functionality. In the browser world, both Mozilla and Firefox are well ahead of Microsoft’s Internet Explorer. Just these features alone represent reason enough to leave Microsoft Windows and switch to Linux.

But my goals were not to test the tried and true features, but to push the envelope with the multimedia features. As a result, I don’t spend much time in this article talking about reliable, well tested features such as networking, OpenOffice and Mozilla, all of which work beautifully without any tweaking on the user’s part. Instead, I’m going to focus on the parts of Linux that still need work.

I should also add, that I was working with a machine that had limited disk space. As a result, I did not elect to install everything during the initial setup. This meant that there were some things that I had to install manually that the Fedora Anaconda installer might have done for me automatically. However, taking a similar step on Windows would not have been nearly as time consuming.

Some features that will interest many readers are not tested in this review. I think the most important omissions are wireless networking and scanning. Basic USB functionality is flawless with the new kernel, and I had no trouble using a USB mouse.

The Install

Because of disk space issues, I wanted to repartition my laptop. As a result, I began the process by creating a huge tarball of my entire user directory, wrapping up all of /home/charlie into one compressed file. I then used SSH to copy that file to another system. (An alternate technique would have been to to use NSF to connect two machines and then iteratively copy the home directory to the second machine, but it is generally simpler to create a big tarball.)

Once I had backed up my home directory, I downloaded the latest Fedora Core 3 ISO files from http://www.linuxiso.org. There was a DVD image of Fedora Core 3 on the site, but I do not have a DVD burner, so I opted to download all 4 CD images. I started the copy before I went to sleep and woke up in the morning to find all CD images had been downloaded to my Windows machine. I then used tools on my Windows box to burn all four ISO images to CD, and popped the first one in the CD ROM drive of my laptop and rebooted.

My system came back up automatically into the Fedora Core 3 install program welcome screen. More out of habit than any real need, I ran the install program in text mode. It has been years since I have had any trouble running a Linux install in graphics mode, but habit led me to type in the word text at the prompt on the first screen, and to then press enter to enter the install process proper in text mode.

I ran across my first problem when I ran the media check on the first CD. It came back reporting that there was something wrong with the CD. I tried it again, and got the same result. So I downloaded the MD5 SUM value for the CD image I had downloaded and used md5summer.exe to confirm that I had downloaded a valid image. The image was okay, so I assumed the problem was in the burn of the CD. To fix the problem, I burned the CD a second time, but when I tested the new CD I found that I had the same problem. By that point I was out of patience, and so I elected to go ahead with the install, regardless of the report on the CD image. Since the install then proceeded flawlessly, I suspect that there may be a bug in the CD media check application.

Because I wanted to repartition, I completely reformatted my hard drive, and installed an entirely new image. The process went smoothly, and in 30 or 40 minutes I was up and running with Fedora Core 3. I then copied back the tarball of my home directory, and restored most of it. This allowed me to preserve all my settings for things like my email and web browser. As a result, I was up and running in a fully functional state in a very short order.

First Impressions and Updating

My first impression was good. When I first signed in, the Gnome desktop was active. I still prefer KDE, though the differences have become much less stark. So I ran SwitchDesk from the shell prompt to switch over to KDE. I booted up smoothly into KDE with everything looking fine.

The next step was to make sure everything was up to date. To update the system, I found it simplest to go to the command line and and use yum:

yum update

Of course, before running update you should download an up to date yum.conf file. I got mine by heading first to http://www.fedorafaq.org/, where I found a link pointing to the latest yum.conf file, which I copied over the existing one in my /etc directory. This process was eased considerably by the presence of FireFox as the default browser. FireFox has a fantastic facility for searching through the contents of a web site. The little search prompt that appears on a status bar at the bottom of the browser offers a significant improvement over the search dialogs in Mozilla, or in the Evil Empire’s browser.

Taking a Look Around

With the system installed and updated, I was ready to take a look around. I soon found out that all my major apps were running perfectly. The browser and mail settings were preserved perfectly. OpenOffice ran smoothly. Compilers such as gcc and Python were installed and in perfect working order. In short, were I not trying to use the machine as a multimedia desktop, I would have been happily up and running in very short order. The Linux install and the basic desktop functionality was in perfect working order. If you left the multimedia business out of it, Linux and Windows were on a par in terms of ease of use and functionality.

The next thing I noticed was that there was a nice little icon on the system tray showing the state of the battery for my laptop. For some reason, this gave me a sense of comfort, as if there were thoughtful programmers working somewhere who had actually considered the possibility that users might be running Linux on a laptop.

Beneath the battery icon was a tool called KwikDisk. From inside this tool, I could launch KDiskFree, a tool that enabled me to get a graphical report on free disk space and also to mount floppies and cdroms.

The whole process of mounting floppies and cdroms on Fedora Core 3 confused me, since their mount point is no longer /mnt/floppy and /mnt/cdrom, but /media/floppy and /media/cdrecorder. This seems like a simple enough change on the surface, but it was very confusing to me when I went to the /mnt and found only an empty directory, with no familiar floppy and cdrom subdirectories. It seems like a small thing, but I was stumped at first, and had done silly things like issuing arcane mount commands such as: mount /dev/hdb /mnt/cdrom. This worked well enough, but it was not a very satisfying experience. Now that I had found KwikDisk, this mystery was resolved, and I found it easy to use floppies and CDROMS and to work from the /media rather than the /mnt directory.

The next step was to pop in a CDROM and see if I could play some music. I put in the Garden State soundtrack, and a moment later I was listening to ColdPlay sing Don’t Panic. Looking around a bit more, I saw that there was a tool under the Sound & Video menu called Sound Juicer. A few moments later I was using Sound Juicer to rip the CD to the default OGG file format. There were also options to rip to MP3.

If you want to play MP3 files in xmms (Sound & Video | Audio Player), enter the following command:

yum install xmms-mp3

I also installed mplayer so that I could watch Quicktime movies and listen to music stored in Microsoft formats. Finally I added the Linux version of RealPlayer10, which allowed me to view yet more movies and listen to yet more online music. You can also use the Package Management tool to install the HelixPlayer, which is nearly identical to, and which forms the basis for, RealPlayer10. You can access the Package Management tool through the System Settings | Add Remove Applications menu.

All of the steps described here took time to perform, but none of them were particularly troublesome. As a rule, I was able to perform each task for the first time in under 15 minutes. This is much longer than it would have been in Windows, but not particularly painful. Probably the most complicated single step was installing mplayer. After doing some research, I went to the command prompt, became root, and typed:

yum install mplayer-gui
yum install mplayerplug-in

After doing that, I went to the following site and watched a video:

http://www.apple.com/trailers/

I was also able to listen to music streamed for the Microsoft Media player. For instance, I could listen to the short previews you find for CD tracks on Amazon. In general, I found that mplayer worked, and provided a valuable service, but that it was a bit unstable when shown in a browser. In particular, attempting to move off a web page while mplayer was running tended to result in nearly disabling my GUI for a period of several minutes. After a time, I was able to kill the browser, and everything returned to normal. However, I found that it was wisest to open a browser in its own desktop when using mplayer. That way the browser did not get hidden behind other windows, and I could more easily kill it if it locked up. When run in standalone mode, mplayer was more stable, but still not as efficient as other Linux tools, such as Rhythmbox or xmms. However, it does provide a very valuable service in terms of giving you access to a wide range of multimedia content.

As a final step, I successfully and quickly installed FlashPlayer 7. I will not detail that process as it has been working smoothly on Linux for years.

After testing multimedia features such as streaming, video and playing music, the next logical step would have been to see if I could burn a CD. However, I just wasn’t mentally ready for that yet, so instead I set about updating my graphics capability. This should have been a simple step, but there was considerable drama awaiting me in this area.

High Performance Graphics

The trouble I had with my graphics card was the most extreme that I encountered while working with Fedora Core. I had no problem with graphics at home, after my initial install. Nor do I have trouble with graphics on my desktop (non-laptop) FC2 and Mandrake machines. But I did have problems when I took my laptop to work. There I had trouble plugging into an emachines monitor (eview 171). There was no trouble if I wanted to use my LCD screen only, but trying to switch over to the emachines’ monitor after working with my Sylvania F97 monitor at home sent my screen output into blurry or pattern strewn fits.

As mentioned before, my laptop uses an Nvidia video card. As many readers know, Nvidia has not released the specs for their card. As a result, the drivers for Nvidia cards are supplied separately, and in binary form only, by Nvidia. This breaks the whole open source Linux philosophy, and means that the problems outlined here are due to the proprietary nature of Nvidia’s license, and not to problems with Linux itself. Nevertheless, the problems do exist, and many users encounter them.

I struggled with my monitor problems off and on for about two weeks, and fairly quickly found a painful, but effective work around. But a workaround is not a real solution. The real fix was to install the Nvidia drivers, a step which did not work properly for me on Fedora Core 2 when I downloaded the drivers directly from the Nvidia web site and attempted to install them using their easy to use custom install utility. In that case the install went smoothly, but the problem was not fixed. This time I avoided the Nvidia website and instead used Yum to update the drivers, issuing the following command:

yum install kernel-module-nvidia-2.6.9-1.681_FC3 

Installing the drivers this way solved my problems. I was able to type startx and bring up X11 (the xorg version) with no troubles both at home and at work. If you are working with a different kernel, or if you have a different type of machine, you can type the following command to get a hint as to what you want to download:

yum info kernel-module-nvidia*

At this point, I thought all my troubles were past. But I got an error when I booted back up into KDE and tried to run tuxracer. When I tried to run tuxracer from the menu, the application closed suddenly without explaining what was wrong. I could not see the error message until I ran tuxracer from the command prompt. The error explained that I needed to read the following file:

cat /usr/share/doc/nvidia-glx-1.0.6629/README | less

Inside that file I learned I must edit this file:

/etc/security/console.perms

In particular, console.perms contains the following line which needs to be deleted:

=/dev/nvidia* /dev/3dfx*

Finally, I needed to issue the following commands:

chmod 0666 /dev/nvidia* 
chown root /dev/nvidia*

The end result was that I was able to switch back and forth between my two monitors, and I was able to run high performance 3D games such as TuxRacer.

Though I was now up and running, I still had troubles logging into my machine as myself, rather than as root. The best solution I could find was to restore the console.perms to original state, but to run the following command as root before accessing any high performance graphcs applications such as tuxracer:

chmod 0666 /dev/nvidia*

This means that with my machine in its current state I can log in and use both monitors with no trouble, but I have to run the chmod command once if I want to play any games that use high performance graphics. Hopefully this issue will be resolved soon. If it is, I will post a solution.

Burning a CD

I had never burned a CD from a LinuxBox before, and I approached this step with considerable trepidation, which turned out to be fully warranted.

I began by making sure that K3b, the excellent GUI front end for cdrecorder, was installed. If K3b is not available on your system, you can use the Add/Remove Applications tool from System Settings menu to install it, or else type the following command as root:

yum install k3b-mp3

To make a very long story short, K3b is easy to use, but it did not work on my system because the underlying cdrecorder application that ships with FC3 was broken on my machine. I fixed the problem by downloading the original version of cdrecorder by author Jorg Schilling from his site. The version that ships with Fedora has the word Clone in its version number:

Cdrecord-Clone 2.01-dvd. 

Schilling’s version, however, does not:

Cdrecord 2.0 (i686-pc-linux-gnu) Copyright (C) 1995-2002 J�g Schilling

Unfortunately, Schilling’s version did not work correctly with K3b. This meant I had to do my work from the command line. To proceed, I first created an ISO image of the files I wanted to burn to my CD. I did this with the mkisofs program:

mkisofs -r -o GardenState.iso Garden_State/*

This produced a file called GardenState.iso. This file contained an image of the directory containing all my OGG files from the Garden State soundtrack.

I then mounted the iso file to be sure that it actually did, in point of fact, contain the OGG files from my Garden State CD:

mount -t iso9660 -o ro,loop=/dev/loop0 GardenState.iso bar/

I then ran the following command to burn my CD:

cdrecord -v speed=4 dev=/dev/hdb -data GardenState.iso

To my utter surprise, this worked flawlessly. I burned all the OGG files to my CD as data files. I then mounted the CD and played the songs successfully. You could have knocked me over with a feather.

Networking: Samba and NSF

I haven’t used Samba in years, and had trouble with it in FC2, so I was hesitant to test this functionality. Figuring that I had to make an effort for this review, I first went to the command line, and typed:

smbclient -L 192.168.1.7

I was then prompted for a password, entered it, and immediately got a list of shares from my local Windows machine. Emboldened by this success, I brought up the well designed Konquerer, and typed smb://192.168.1.7 in the address field. I was immediately presented with a hierarchical view of the shares on my Windows machine. Browsing through the shared folders was fast and simple. For instance, there was no perceptible delay from the time I pressed the plus next to the word SharedDocs and the time when I saw a list of folders and files in the SharedDocs directory.

 

I then proceeded to copy a file from my Windows machine to my Linux laptop, and to copy a file from my Linux laptop to a share on my Windows machine that allowed writing. I did all of this with a series of right clicks and copy and paste operations between two convenient tabs in Konquerer. In Figure 1 you can see the tabs which allowed my to move back and forth between a view of my home Linux directory (charlie) and the Windows shares (smb://192.168.1.7).

Next I wanted to test NFS, the file system that allows one of several methods of sharing data between Linux machines. I opened my /etc/exports file and typed in the following:

/home -r 192.168.1.61

The command shown here states that I want to share my /home directory in read only mode with any machine that has the IP address 192.168.1.61. Then I started my NFS service, which I normally keep shutdown because of security reasons:

/etc/init.d/nfs start

Finally, I went to the System Settings menu and opened my easy to use GUI based Security Level tool and turned off my firewall.

I then went to my Linux machine with IP address 192.168.1.61, and typed:

mount 192.168.1.62:/home /mnt/share

I was immediately connected to the share on my remote Linux machine. Acting as a user with the same UID as the shared user directory on my FC3 machine, I was able to access the files on my FC3 machine and copy some of them to the local machine. Because I had set permissions to read only (-r), I was not able to copy files back.

Satisfied that all was working correctly, I unmounted the shared drive, turned the firewall back on, and stopped the NFS service.

I won’t detail the process here, but I also had success when using the much more secure SSH protocol to move files back and forth between machines. In general, for security reasons, I much prefer to use SSH rather than NFS.

Obviously I have included this section to remind everyone that the non-multimedia features in Linux usually work smoothly out of the box. Even many of the multimedia features run smoothly out of the box. The problem I was facing was getting them to run smoothly on a laptop.

Summary

In the end I have mixed feelings about Fedora Core 3. I’m very pleased that I can have easy access to a powerful office suite like OpenOffice, and to all of Linux’s advanced networking capability, to its astounding stability, to its fine browsers and to its mail servers and clients. The addition of yum to the Fedora Core distribution has also been a major breakthrough. Many troubling install problems are now resolved quickly and easily with yum.

I am also amazed that I am finally able to watch movies, listen to music, and burn CDs on my Linux box. This is a huge accomplishment.

Unfortunately, I believe that the key multimedia features in Fedora Core 3 still need work. A non-technical person would have little chance of getting them up and running, and even a talented user from the Windows world would find it a challenging and time consuming process. I’ve been working with Linux for years, and it took me well over eight hours to get the right movie clients, music clients, and video drivers installed. Better problem solving skills would have helped me, as would more experience with Linux, yet still this is not a good situation. I am well aware that my experiences should help make the process much easier the next time through, but the first time through was a bit of a challenge.

The bottom line is this: if you are a power user, or a developer, you will be able to get Fedora Core 3 and everything you want. If you want to watch movies, rip CDs, listen to music, browse the web, create documents, or develop software, then you will find all the tools you need on Fedora Core 3. There is no longer any need to feel that you have to stick to Windows just to get the full range of features from your computer. However, Fedora Core 3 is still not ready for the mass market. In that world, computers are a commodity, and they are expected to work smoothly out of the box. An experienced user can get Fedora Core 3 to run smoothly, but it doesn’t occur automatically just out of the box.

Creating Projects in Subversion: Trunk, Tags, Branches

This article explains how to create projects and repositories in a free, open source version control system called Subversion. The online documentation for Subversion is excellent, but the information found here may help people who are still getting up to speed with the product. I will assume that you have already installed Subversion and TortoiseSVN.

I run Subversion on a Linux box, but frequently use it from Windows. However, in this article I will describe how to create both the repository and your projects while running on Windows or on Linux. In general, any commands you give from the command line will work on both Wndows and Linux, while the commands you give from inside TortoiseSVN will work only on Windows. This is not a shortcoming in TortoiseSVN, but simply reflects the fact that TortoiseSVN is a Windows only tool which runs as a shell extension to the Windows Explorer.

If you want to learn both how to create a repository, and how to create a project in the repository, then read this whole article. If your repository already exists, and all you want to do is create a project inside the repository, then please skip ahead to the section of this article on adding projects to a repository. There you will learn about the trunk, tag and branch directories and why they should be part of all Subversion projects.

This article also describes the svn, svnadmin and svnserve command line programs that ship with the default installation of Subversion. If you are running on Linux or if the Subversion\bin directory is on your path, you should have no trouble running these programs from the command line. I discuss none of the programs in detail, but the context in which they are discussed in this article should make their purpose clear to you. In particular, if you want to access Subversion from the client side, then you should be sure to read carefully the sections of this text that describe the svn program. The other two programs are server side tools.

Creating the Repository

Repositories are created by a user who has direct access to the server. If you are using Windows as a server, then the simplest way to create the repository is with TortoiseSVN. Open the Windows Explorer, browse to the place where you want to create the repository. Use the explorer to create the directory where you repository will reside. Right click on the new directory and choose TortoiseSVN | Create repository here. The Create Repository dialog will appear, as shown in Figure 1. Select the default Native FileSystem (FSFS) option and click the OK button. The repository will be automatically created.

csc_svn_01_01

Figure 1: Choose the Native file system for best performance. If you like working with databases, then you can choose Berkeley DB.

If you want to create the repository from the command line on Windows, simply type something similar to the following:

svnadmin create c:\MyRepository

This command will first create the directory called MyRepository, and then set it up properly as a Subversion repository. On Linux, you might issue this command:

svnadmin create /usr/local/repository

Regardless of whether you created the repository with TortoiseSVN or with svnadmin, the end result is a directory with the following structure:

10/26/2005  15:39         <DIR>    conf
10/26/2005  15:39         <DIR>    dav
10/26/2005  15:39         <DIR>    db
10/26/2005  15:39         <DIR>    hooks
10/26/2005  15:39         <DIR>    locks
10/26/2005  15:39               2  format
10/26/2005  15:39             388  README.txt

To start the Subversion service running on your machine, go to any directory on the drive on which you created the repository, and type svnserve -d. For instance, if you created your repository on the C drive, then move to any directory on the C drive, and type svnserve -d. It might make a certain sense to start svnserve from inside your repository, but that is not necessary.

Now go to another machine and try to access your repository. Assuming you created your repository in C:\MyRepository, then you might type something like this:

svn info svn://MyServer/MyRepository

If you created your repository in the D:\Temp\Info\MyRepository directory, then you would start svnserve on the D drive, and type something like this:

svn info svn://MyServer/Temp/Info/MyRepository

The point is that svnserve will look on the drive in which it is started for your repository. There is no need to specify a drive letter. In fact, I have never had any luck trying to pass drive information via svn. Instead, I just start svnserve on the appropriate drive, and then assume the path to the repository automatically references the relavant drive. Needless to say, all this talk about drives is not relevant if you are running the server on Linux.

The result of the svn info command should be something at least vaguely like the following:

[D:\temp\Tort2]svn info svn://rohan/usr/local/repository/CodeFez
Path: CodeFez
URL: svn://rohan/usr/local/repository/CodeFez
Repository Root: svn://rohan/usr/local/repository
Repository UUID: b062d7d2-2303-0410-96a2-dd3f728f4100
Revision: 13
Node Kind: directory
Last Changed Author: Charlie
Last Changed Rev: 13
Last Changed Date: 2005-10-16 16:28:59 -0700 (Sun, 16 Oct 2005)

If you get an error when you run svn info, then it is possible that your firewall is blocking port 3690. If you are using the standard Windows built in firewall, then the install of Subversion should have opened up the port for you. However, if you have an external firewall, then you may need to punch a hole in it.

NOTE: If the info command returns absolutely nothing, then the repostory is probably fine. Subversion is simply saying that there is nothing to report. Had there been an error to report, it would have been reported. If you are querying a repository that already has at least one project in it, you can try issueing the list command instead. If there is something in your repository, then you should get a list of the contents. In general, however, Subversion is a well behaved Linux application that returns nothing if everything is okay, and an error message if there is a problem. Immediately after you create a respository, however, you should get a listing like the one shown above.

At this stage, you should have your repository set up correctly and you should be able to access it. The next step will be to set up permissions in your repository.

Setting up Permissions in Your Repository

By default, you will be able to read your repository, but not write to it. Here are the steps necessary to give password protected, read or write access to your repository. In the conf directory of your repository, you will find a file called svnserve.conf. You should edit this file so that it looks like this:

[general]
anon-access = read
auth-access = write
password-db = users
realm = My First Repository

The actual file on your drive will have some comments demarcated by ### signs. I have omitted those comments here so as to make it easy for you to see the important parts of this file. In your version of the file, you will want to keep the comments, as they are useful. But be sure to remove the comments in front of the lines shown above.

NOTE: Change anon-access=read to auth-access=read if you want the user to have to sign in before reading from the repository. Otherwise, anyone will be able to read from the repository, but only those with proper rights will be able to write to it.

The next to the last line in svnserve.conf looks like this:

password-db = users

This line represents a contract with Subversion in which you promise to create a file called users, placed in the conf directory, with the following format:

[users]
user1 = foobar
user2 = foobar

The name of the subversion user is on the left, and the password for the user is on the right. When you attempt to write to this subversion repository, you will automatically be prompted for a user name and password. In this case, if you entered user1 as the name, and foobar as the password, then you would be granted permission to write to the repository.

Adding Projects: Branches, Tags and Trunk.

Subversion supports advanced version control features called branching and tagging. In this article, I will not have room to explain the simple steps for branching or tagging your source in Subversion. Nevertheless, I will take a moment to make sure you understand what a branch is, and what it means to tag a version of your source.

  • Tagging: You might tag your project when you reach Version 1.0. Then you can go on making changes to your project, but if you need to get back to Version 1.0, you can always use the tagged version of your project to retrieve all the source files exactly as they looked when your reached Version 1.0.
  • Branching: If you are working on a project, and want to try some experiments, but you aren’t sure you want to keep them, then you can branch the project. After branching, you will have two copies of your project: the main trunk, and the branched version. Work can then continue on both the main trunk, and the branch. Changes to the branch will not be seen in the main trunk, and changes to the trunk will not appear in the branch. Both branches of the code will have acecss to any changes that occurred before the project was branched. As I will explain below, branching is handled in a way to insure that only a minimum amount of server side disk space will be used.

Now that you understand branching and tagging, you are ready to create a project. Here are the basic steps to add a project to a repository when working from the command line:

$ mkdir MyProject
$ mkdir MyProject/trunk
$ mkdir MyProject/branches
$ mkdir MyProject/tags
svn import MyProject svn://rohan/usr/local/repository/MyProject -m "info"

As you can see, you create three directories under your main project branch. These directories are called branches, trunk and tags. You then create the repository itself by issuing the svn command shown in the last line.

svn import MyProject svn://rohan/usr/local/repository/MyProject -m "info"

The last bit of this code, that reads -m "info," is simply a place for you to enter a comment that will be recorded in the log. If you don’t provide this information, then Subversion will prompt you to load an editor and write a comment inside of it. I definitely prefer to add the -m command to my import statements so as to avoid any unnecessary fuss with an editor.

It is nearly as simple to create a project using TortoiseSVN as it is to create it from the command line. First open up the Windows Explorer. Now create an empty directory. Give the directory the name of your project, such as MyProject. Inside the directory create three subdirectories called trunk, branches and tags. Now select the MyProject directory, right click, and choose TortoiseSVN/Import from the menu. A dialog like the one shown in Figure 2 will appear. In this dialog, type in the URL of the project you want to create in the repository. Add a message that explains something about your import. This last step parallels the -m "info" portion of the command line import statement shown above.

csc_svn_01_02

Figure 2: Importing a project into the repository using TortoiseSVN. Specify the complete URL where you want to place the repository, and add a brief comment in the Message section.

In the URL section, I have included both the path to the repository, and the name of the project that I want to create in the repository. Don’t be fooled into thinking that because you right-clicked on the name of directory you wanted to import, that a directory of that name will be created for you automatically. Instead, specify the name of the project in the URL.

NOTE: In the examples I show, I prefer to put the name of the repository in the URL. However, you could also create a series of nested directories, and end up with much the same result. In short, there is more than one way to achieve the result shown here. It seems to me that neither technique is perfect, but the one shown here is most intuitive to me. In any case, if you don’t like the structure you created in the repository, just delete those directories and try again. It is easy to delete directories in the repository browser, shown in Figure 3. Later in this article I will describe how to launch the Repository Browser.

When you are done with your import, the repository should have a structure that looks like the image shown in Figure 3.

csc_svn_01_03

Figure 3: Viewing the structure of your project in the repository. I will show you how to pop up this dialog later in this article.

Don’t put the files directly in the MyProject directory, instead them in MyProject/trunk:

MyProject/trunk/File1.cs
MyProject/trunk/File2.cs
etc.

If you want to branch or tag your project, then you will use the directories called branches or tags:

MyProject/trunk/File1.cs
MyProject/branches/branch01
MyProject/branches/branch02 
MyProject/tags/version10
MyProject/tags/version20

NOTE: Subversion makes a "light" copy for the branched and tagged versions of your source. It doesn’t really copy all the files, it only copies the changes to the branches directory. So that keeps the repository small. From the client point of view, however, it appears that the branches and tags directories contain full copies of your project.

Checking Files into the Repository

You now have access to both a repository and a project. Unfortunately, your project is currently empty, and contains no files.

To put files in your project, you need to take a step which is somewhat counter-intuitive: you need to check out the project that you just created. The MyProject directory that you created in the previous section is no longer useful. To get your hands on blessed, completely approved, and fully loaded Subversion directory, you need to check it out from your repository.

From the command line, navigate to the place in your system where you want to place your project. For instance, if you want the project to be in C:\Src\MyProject, then you should navigage to C:\Src. Now type the following command:

svn co svn://rohan/usr/local/repository/MyProject 

The project will be checked out into the C:\Src\MyProject directory.

If you prefer to work from TortoiseSVN, the process is equally straightforward. If you want your project to be in D:\temp\MyProject, then use the Windows Explorer to navigate to D:\temp. Right click on the temp directory, and choose SVN checkout. A dialog will appear, as shown in Figure 4. Fill in the URL of your repository: svn://rohan/usr/local/repository/MyProject.Also fill in the name of the directory where you want the project to reside.

csc_svn_01_04

Figure 4: Checking out from the repository. But the URL of the project you want to check out on top, and the directory where you want the project to reside beneath it.

When you are done, you should have directory called C:\Src\MyProject that contains three subdirectories called tags, branches and trunk.

To copy files into your repository, either create the files one by one in the c:\Src\MyProject\trunk directory, or else copy the whole source tree of an existing project into the trunk directory. You are now ready to check your source files into the repository.

Suppose you added a complex directory called dbo that had many subdirectories to your c:\Src\MyProject\trunk directory. From the command line, navigate to the C:\Src\MyProject\trunk directory and issue the following command:

C:\SrcMyProject\trunk]svn add dbo 

NOTE: In the command shown here, you no longer need to specify the path to your directory when calling svn. The information about the path to your server and your repository is kept in a series of hidden directories inside your project called .svn. You need not concern yourself with those directory in most cases. But if you want to explore them, just go the command line, enter a directory of your project, and type cd .svn. You will find yourself in a directory where the information about your subversion repository is stored in a series of files and directories.

After add the files to the repository, you need to commit your work:

[C:\Src\MyProject\trunk]svn commit -m "" 

Now the dbo directory, and all the files in it, will be added to your repository.

You can also add files to a repository from inside the Windows Explorer by navigating to the C:\Src\MyProject\trunk directory and right clicking on the dbo directory. Choose TortoiseSVN/Add from the pop up menu. The dialog shown in Figure 5 will appear. You can check or uncheck the files listed in this dialog depending on whether or not you actually want to place them in the repository. When you have things set up they way you want, click the OK button.

csc_svn_01_05

Figure 5: Adding files to the repository using TortoiseSVN.

After adding the files to the repository, right click again in the Windows Explorer and choose SVN commit. The dialog shown in Figure 6 will appear.

csc_svn_01_06

Figure 6: The commit dialog prompts you for a short string that will be added to the repository as a log message. In the lower window you can specify which files you wish to commit by ensuring that there is a check mark before them.

You now know two ways to add files or directory trees to your repository. It probably comes as no surprise to learn you could have added files during the initial import process described in the previous section. However, I wanted to show you the process of adding files to a repository after you had created a project.

If you make any changes to the files that you have added to the repository, then they will have a little red icon next to their name in the Windows Explorer. Just choose SVN Commit from TortoiseSVN to post your changes. Choose SVN Update from TortoiseSVN to check files out of the the repository that may have been changed by other users. Needless to say, the command line versions of these commands are svn commit and svn update. More details on managing files that are part of a repository will be explained in future articles. But these simple commands should be enough to get you up and running.

You now know how to create a repository, add a project to it, and how to add one or more files to the project in your repository. In the final section of this article. I will add a few useful tips, most of which concern viewing the files in your repository.

Viewing the Repository, A Comment on the Repository

To view your repository and its projects, use the list command:

[D:\]svn list svn://rohan/usr/local/repository/trunk/MyProject32trunk
dbo/

Here we see the listing of the MyProject2/trunk directory. As you can see, it contains one directory, called dbo. If you do the same thing in TortoiseSVN, you get a somewhat clearer view of what is going on. Select the directory on your system that you want to browse in the repository. Right click and choose TortoiseSVN/Repo-Browser, the dialog shown in Figure 7 appears.

csc_svn_01_07

Figure 7. The TortoiseSVN/Repo-Browser option gives you good view of your repository and its contents.

In the image shown in Figure 7, you can see the URL input control at the top of the dialog. In this case, the information in this control was filled in automatically because I picked a directory on my system that was checked out from a Subversion repository. Had I just brought up the browser from a random location on my harddrive, I probably would have had to type in the URL, or else pick it from the drop down list.

I want to end by explaining one peculiarity of Subversion. Each time the repository is changed, the version number of all the files in the repository is updated. In other words, the version number of your project as a whole gets updated, not just the version number of a particular file. This behavior is a bit odd, but there is at least some form of reason behind it. In a project, if one source file changes, it can affect the whole project. So the version number of the whole project is updated if even one file changes. For detailed information about the history of a particular file, right click on it in TortoiseSVN, and choose TortoiseSVN | Revision Graph.

Here is quote from the TortoiseSVN manual: "For unrelated projects you may prefer to use separate repositories. When you commit changes, it is the revision number of the whole repository which changes, not the revision number of the project. Having two unrelated projects share a repository can mean large gaps in the revision numbers. The Subversion and TortoiseSVN projects appear at the same host address, but are completely separate repositories allowing independent development, and no confusion over build numbers."

Summary

In this article you have had a chance to see how Subversion works. You have learned how to create repositories, how to create projects, how to check in code, and how to view the code you have checked in. I also briefly discussed updating files that have been changed. I have tried to lay things out here as clearly as possible, if you have more questions, the docs give a good overview of these subjects and provide more detail than I give here. In future articles I will discuss subjects such as branching and tagging, as well as techniques for updating your source and running diff operations on files that have been changed by two users.

Subversion is an excellent version control system that provides all the tools that most programmers will need to manage their code. This article hopefully gives you enough information to get over some of the initial hurtles that can confuse new users.