Quick Links

Have you ever wanted to work on a project with the ability to track your changes as well as revert them? How-To Geek explains How-To use the popular version tracking system, Subversion (a.k.a SVN).

Image by Clearly Ambiguous

Prelog

This guide will aim to give you the ability to use the subversion client in general, and, if you have one, on your *DD-WRT router. This guide is by no means a definitive guide for Subversion and a lot of information can be found on the Subversion Red Book. This guide is only intended to give you the shorthand answer to the most basic of questions.

Overview

There could be numerous reasons why you would want to be able to "checkout" the latest code for a software project that uses a versioning system. Doing so enables you to benefit from the latest still unreleased changes, help with testing and even development. In this guide, we will go over some basic SVN terminology, show how to install the SVN client on Linux, Windows and if you have one your OPKG enabled DD-WRT router. We've also included an example of a project you can checkout and use for said router.

What is Subversion?

Subversion is by no means the only version control system in existence and alternatives include Git (which was created by Linus Torvalds the Linux kernel founder), Mercurial and PerForce to name a few. With that said, it is one of the free ones, it's mature and is extensively used world wide.

Out of the Subversion "Red Book":

Subversion is a free/open source version control system (VCS). That is, Subversion manages files and directories, and the changes made to them, over time. This allows you to recover older versions of your data or examine the history of how your data changed. In this regard, many people think of a version control system as a sort of “time machine.”

Note: This book is the ultimate collection of knowledge about subversion and you are advised to refer to it on all Subversion related topics.

What Is Versioning?

Versioning is a process where the state of a project at a point in time is saved. This sort of procedure is often used to manage software development, so that work can continue to improve the project or add features, while being able to track what has changed from the last overall "save" point. To elaborate, this sort of procedure can be useful for a single person but even more so for a group of people, all working on the same project. This is because, usually, when working on a project as a group, there is a distribution of responsibilities and different people change different aspects of the project. Without a versioning mechanism, it would be very difficult to keep everyone in sync on the latest working changes from everyone else.

Terminology

The Repository

The repository is the location where all the data from all the various places is saved. In the subversion world, from the client's point of view, it is the server which holds the database of the project. This database contains all the files that are part of the project with all of their past versions.

Revision

When a repository is created, it is given the revision number of zero (0). This number is incremented by one(1) every time a commit is performed. The revision number is global for the repository. That is, that there is no individual revision number for individual files in the repository, even if nothing changed in that file for that specific commit.

The Working copy

A working copy is a local copy (or "checkout") of a particular version. Usually this version when checked-out is the "latest" one (also called a "head"), but a previous one can be requested. The User may do with the local copy anything that he/she desires, with knowledge that, at worst, they could just checkout the code again. Moreover, this copy is "private". This is because until you either update or commit your copy, you will not see other people's changes, nor will they see yours.

Updating & Conflict resolving

A Local working copy can be updated. That is, If you "checked out" a certain version, and while you were working, the version on the repository has been updated, you can update your working copy to the latest. In fact, the server will prevent you from committing your changes before you update to the latest version to match the repository. This is done in order to force you to resolve conflicts locally, before you even think of committing changes to the repository.

Merging

Merging refers to the process by which, changed code is blended into one version. It may also entail resolving conflicts.

Commits

Committing is the process in which the changes you have made to your local copy will be merged back into the repository. This is the most perilous part of the process, as it is here that changes you have made, might impact other people using the same repository. That is why this is usually done after some consideration, with the team's consensus and after you've resolved any merging conflicts.

The Workflow

The most basic workflow from the user's perspective when using subversion is this:

1. Checkout the existing code (usually the "head").

2. Make changes, add files and generally develop the code.

3. Update to the latest version, to make sure your local copy is in sync with the updates on the repository.

4. Locally merge and resolve conflicts if necessary.

5. Commit the merged changes into the repository.

6. GoTo step 2.

Lets get cracking

Install the Client

In order to be able to use subversion, you need to install the client on your machine.

On Linux

You need only to install the package. On Ubuntu/Mint, this would be done with:

sudo aptitude install subversion

On DD-WRT

If you've followed the "How To Install Additional Software On Your Home Router (DD-WRT)", you are able to install the svn client by simply issuing:

opkg update; opkg install subversion-client

On Windows

While we deep geek users may start to forget that the GUI even exists at times, not everyone has. If you want to use a windows client to connect to an SVN repository, by far the most popular one is "Tortoise". To use it, simply download the program and install in the regular "next, next, finish" fashion.

Create the "repository"

While we will not go into to much detail on how to setup a subversion server in this guide, the Google alternative is not a bad start for the novice user. To create a Google repository:

  • Head over to the Google Code hosting website and "create" a new project.
  • In the next page, fill in the required fields and select the type of "version control system" to be subversion.
    Note: You may want to glance over what is the difference between the licenses Google offer, before you select one for the project.
  • Click "Create project".

"Checkout" your working copy

Once your project has been created, you Should be able to find the instructions on how to access it in the "Source" tab.

The nice thing about Google code, is that it will enable an anonymous read-only version for your project. If you don't want to deal with the hassle of creating your own project, you may anonymously checkout this writer's repository.

One note about the hotfortech project: This project is meant to be a wrapper for the features that have been added to DD-WRT on How-To Geek (that I personally use) plus some personal tweaks. While this project is geared to work in conjunction with the articles published here on howtogeek, it is still my private project. That is, it's highly suited to my Buffalo router (AR71xx architecture), my personal whims and is prone to the occasional borkage.

On Linux/DD-WRT

Create the directory to work in, for example on DD-WRT, that could be:

mkdir -p /jffs/svn; cd /jffs/svn

The full command on Linux consists of the SVN command itself, the "checkout" directive, the address of the repository and the directory to checkout too. Create an empty directory and execute the command below:

        svn checkout http://hotfortech-dd-wrt.googlecode.com/svn/trunk/ hotfortech-dd-wrt-read-only
    

Do note that in the example above, the read-only version is being checked out. If you opted to create your own repository, you will need to use the httpS link.

On Windows

Because tortoise is a shell extension, you will need to use the Windows file explorer's context menu (right-click) to use it. In fact, if you try to invoke it from the start menu, you will get:

  • Create an empty directory.
  • Right click in it to bring up the context menu.
  • Select "SVN Checkout":
  • Copy & paste the link for project (if you have one) into the "URL" Textbox:
  • Depending on the size of your project this may take a while, but when the "Checkout" has been completed you should see something like:
  • You may start developing.

"Update" & "Merge" your working copy

If your working on the code with colleagues, or you your self are updating the code from several locations (i.e. laptop, desktop or even router), you will have to update your working copy before you commit the latest changes.

On Linux/DD-WRT

The command to do this on these POSIX systems is simply:

svn up

On Windows

  • Right click in the working directory and select "SVN Update":
  • If you encounter conflicts, try following the on screen instruction and use your judgment as to what to do about them.

"Commit" your changes

That is it, you should be conflict free and ready to update the repository with your changes.

The one point to note here is that it is a common practice to add a "log" message to the commit, as to be able to easily recall why the changes were made. In fact, Google's repository makes this a mandatory pre-requirement to committing.

On Linux/DD-WRT

This is an example of the commit I've made to the hotfortech project that upped it to version 19:

svn commit -m "updated to reflect new ant-ads pack link"

On Windows

  • Right click in the working directory and select "SVN Commit":
  • You should be greeted by a window that enables you to note a log message:
  • Hit OK and when prompted for a password, give the Google generated password.
  • If the commit was successful,you should see something like:
  • That is it, you should be able to commit like a BOSS.

Final remarks

This should be enough to get you started. You are advised to read the SVN reference books to get a deeper and better grasp on all of SVN's usages, options and caveats. Also, we remind you (again) that subversion is NOT the only version control system out there and GIT (which was created by Linus Torvalds the Linux kernel founder) seems to be gaining popularity in recent years.

If you will opt to run the "running-config.sh" from the hotfortech project on your router, you will find that it will currently install for you: The anti-ads-pack, the Opkg geek-init script, as well as things such as the full GNU "ls", "less", "BASH" and more.

/jffs/svn/hotfortech-dd-wrt/running-conf.sh

More features are pending and will be added in the future.


System administrators will code their way out of coding.