Web Dev Intensive

The following is a brief example of working within a Subversion version control setup.  In this case, we will assume that some overworked server administrator (i.e. me)  has set up a repository where a large amount of source code magically is stored and backed up by Subversion, a popular version control system.  In our case, the source code is all the example files from this course.

Read the overview of Subversion concepts in the post linked above before proceeding.

The hypothetical setup

The under appreciated developers (i.e. you), just need a way to checkout (i.e. download) the latest copy of the code from the repository (i.e. the server), make some changes to some of the code, and then commit (i.e. upload) your changes back to the repository.  You do this so that we can track the changes made to the files and so that everyone else can download new-and-improved version of the source code that you created at their leisure.

Using source control keeps the source code safe from being accidentally deleted, prevents two developers from overwriting the same file at the same time, and it keeps a record of who changed what and when they did it so that your manager (i.e. me) can make sure his minions (i.e. you) are doing their assigned jobs in a timely manner.

Think of it as a backup system with benefits.

The Subversion client

To interface with our Subversion repository, we use a Subversion client application.  Just as we use web browser clients to surf web pages on the server, and we use file transfer clients to browse files on the server, we also use Subversion clients to manipulate version-controlled files on the Subversion server.

The popular client applications for Subversion provide nice graphical user interfaces for you to use so you don’t have to manually send Subversion commands to our Subversion repository on the Linux server.  Popular Subversion clients that I currently recommend are TortoiseSVN for the PC and SvnX for the Mac.  Both add extra Subversion-related options to the context menu (right click menu on PC; control-click on the Mac) within Windows Explorer and Mac Finder, respectively.

Make sure you have one of these clients installed before following the instructions below.

Getting a working copy of the code

To get a “working copy” of the code, meaning to download the latest version of all the code from the Subversion server, you make a folder on your client machine where you want to store your copy of the code.

a folder to hold our working copy of the code

Right click on the folder name and select “Checkout” from the new options that the Subversion client added to your context menu.

Subversion checkout

Enter the URL of the repository: “http://svn.onepotcooking.com/webdev/trunk” and the usual username/password in the screen that pops up.

Checkout settings

Successfully logging in will checkout (i.e. download)  a full copy of all the latest source code in the repository and put it into the selected folder on your client.  You will see that the folder and files on your computer have special icons next to them indicating their version control status.

Everything's good

The green checkmark icon means that you have not modified any of the files in this folder since last downloading the files from the Subversion server.

You’re now ready to make changes to some code.

Make some changes

Go into the source code you just checked out on your client and open up the file class12/subversion/index.html in your text editor of choice and make some changes to that file.

Update the code

You’re almost ready to “commit” (i.e. upload) your changes back to the repository.  But first you have to make sure nobody else changed the same files as you between the time you last downloaded them from the repository and the time you finished editing them.

If two people edit the same file at the same time, you wouldn’t want one person to overwrite the other’s work.  So Subversion automatically checks for conflicts.  If they are easy to solve, such as if one person edited the top of a file while the other person edited the bottom, Subversion merges the two copies of the file automatically.  If the conflicts are complicated, Subversion will as you to manually merge the two versions of the conflicted file.

So update your working copy with a fresh copy of the latest code from the repository by using the Subversion client’s update command on the project folder.  This will update everything inside of the folder and check for conflicts between the changes you have made and the changes others have made.

Subversion update

Commit your changes

Once any conflicts have been resolved, you are ready to commit your code to the repository.

Use the Subversion client’s commit option to upload your copy of the entire folder to the repository for safe keeping.  You can also just commit specific  files rather than the whole folder, but for now we’ll upload any changes we made to any files in the folder to keep things simpler.  Subversion is smart enough to only upload the files that have been modified anyway.

Subversion commit

Add a file

Now let’s say you want to add a new file to this project.  On your client computer, create a new file in the class12/subversion folder called <your_name>.html, where <your_name> is replaced with your first name and last initial, of course.

By creating this file on your client machine, it is not yet added into the version control system unless you make it so.  To add it to the Subversion repository, you need to use the Subversion “add” command.  So right-click on the file and click the Subversion add command.

Subversion add

Adding a new file is just like making any other change, whether it be adding, deleting, or modifying a file on your client.  The changes you make on your client are not uploaded to the server repository until you commit them using Subversion’s commit command.

So now go ahead and commit the changes you’ve made.

Subversion commit

The next time anyone else updates their “working copy” of the code using the Subversion update command, they will see this new file has been added.  In other words, if I don’t see your file the next time I update, I will know you didn’t follow this tutorial!  I should have forced you to use this technology from the beginning of this course.

Further changes

From this point onward, always download the latest copy of all files using Subversion’s update command on the project folder before you make major changes.  This reduces the chance that your work will have a conflict with another developer’s work, and it will reduce any chance that you are working on an outdated copy of a file.

Here are some of the most common Subversion commands that you may one day run on the server, which uses a Linux operating system.  Most of the time, your SVN client, like TortoiseSVN or SvnX, will handle these things for you.  But here are the commands for your reference anyway, in case you one day consider yourself something of a server administrator.

Note 1: These examples use “$SVNREP_DIR” in place of the full path from the server root to the folder on the server where your repository is stored.  And “myproject” is in place of your project’s name.

Note 2: Also, these examples show how to run the commands on the same server that stores the repository.  If for some reason, you are running them on a different computer than the one that stores the repository, you can replace the file:///somefolder/ urls with an absolutely http://someurl.com/somefolder/ path.

//command to create a repository
svnadmin create $SVNREP_DIR/myproject

//command to create the layout of the repository
svn mkdir -m "layout creation" file:///$SVNREP_DIR/myproject/trunk file:///$SVNREP_DIR/myproject/tags file:///$SVNREP_DIR/myproject/branches

//do an initial import of your project into the repository
cd ~/myproject
svn import -m "initial import" . file:///$SVNREP_DIR/myproject/trunk

//check to make sure all files were imported
svn ls file:///$SVNREP_DIR/myproject/trunk/

//move your original project folder to a backup folder
mv myproject myproject.origin

//checkout the project from the repository
svn co file:///$SVNREP_DIR/myproject/trunk myproject

//make sure the files checked out successfully
ls myproject

When projects require several developers (i.e. designers, developers, html coders, etc), they may run into situations where multiple people try to edit the same file at the same time. This could be problematic, since one developer could easily overwrite another’s work.

To prevent one person from overwriting another’s work, most teams of coders use some form of version control. Version control software allows multiple people to simultaneously work on the same files while not overwriting each other’s work.

Subversion is probably the most popular version control software:
http://subversion.tigris.org/

You can find the Subversion online manual here.

The Repository

Subversion uses a type of client/server architecture.  The permanent location of all files is on the server, in what is called a Repository.

The Repository has the current version of all files, as well as all the older versions of the files stored in a nicely organized way. It keeps a permanent record of any changes to the project.

Clients can always get the latest copy of the files by copying them from the Repository.  So developers generally make changes to files on their local machines, and then upload them to the Repository so that other developers can get the lastest version of the files.

Internally, the Repository in Subversion has three subfolders: “trunk”, “branches”, and “tags”.

The “trunk” is the main folder that always has the latest copy of the main version of the code.

The “branches” folder is used if you decide to fork your code and simultaneously work on two or more different variations (or branches) of your code.

The “tags” folder allows you to give nicknames to prior versions of the code for easier access later on: for example, you may decide to call revision #12 the “gold_release” with a tag so that it is easier to remember than a number.

In general, for a simple project, you will work with code in the “trunk”, unless you are an advanced user.

The Client

Your local computer runs a Subversion client that automates the common tasks that you will need to do when using version control. The recommended client for Windows is TortoiseSVN. For Mac, you should check out SvnX.

Any client will easily allow you to run the basic Subversion commands:

• checkout - this command is used to get all the files from the repository at once and download them to your client.  You usually run it once at the beginning of development to set up your working copies of the files
• import - this command is used to import files as a batch into the Repository.  It is usually used once at the beginning of a project that has already begun without version control.
• add - this command adds a file to the repository.
• update - this command updates all the files on the client machine with the latest version from the Repository
• delete - this obviously deletes files
• commit - permanently store any changes in the Repository.  Note: you need to commit after every modification, merge, add, or delete in order for those changes to be permanently stored in the Repository.

Working Copy

When a developer downloads the latest copy of the files from the Repository, they are placed in what is called a Working Copy. This is exactly what it sounds like – a copy of the original files that a developer can use to work on her client machine.

Once a developer has finished modifying the files, she has to then upload them back to the Repository so other developers can see the changes.

Checkout

When a developer starts working on a project that is using version control with Subversion, the first thing they will need to do is get a copy of the latest version of all the files in the project.  This is called the initial checkout.

Any Subversion client, like TortoiseSVN or SvnX, will have an option to checkout the files in a repository.

This command is usually only run once to do the initial setup of the Working Copy on the client machine.

Update

To get the latest copy of files from the Repository, a developer runs a command called Update. This automatically downloads the latest files from the Repository.

Developers should run an update immediately before editing any file, and again immediately before Committing any changes to the Repository.

Commit

When a developer has finished making changes to her Working Copy of the files, she first runs the Update command to make sure that nobody else has modified the same files she is about to upload, and then runs a Commit command that automatically uploads the changed files to the Repository.

Conflicts

When two developers have modified the same files at the same time, and then they both Commit their changes, the second developer to commit his changes will experience a Conflict. Usually the work the developers have done is in different parts of the file, so Subversion can automatically merge the two versions together.

However, in some cases Subversion cannot figure out how to merge the two versions of the file, so it asks one of the developers to manually merge the two. Subversion will show you the difference between the two files, and you can usually easily see what has to be done to get the two versions to merge correctly.

Once you are finished merging, you must of course commit any changes in order for them to be permanently stored in the repository.

Workflow

To sum it up, here are the usual steps you will take when working on code that is held in version control:

1. update to the latest version of code
2. modify the code
3. update again to check for any conflicts from other people’s changes
4. merge any conflicts that have arisen from other people’s modifications
5. commit your changes