Joomla! 1.5 Development Cookbook

By James Kennard
    What do you get with a Packt Subscription?

  • Instant access to this title and 7,500+ eBooks & Videos
  • Constantly updated with 100+ new titles each month
  • Breadth and depth in over 1,000+ technologies
  1. Free Chapter
    Development using and SVN
About this book

Joomla! is the world's hottest open-source content management system. Out of the box, Joomla! does a great job of managing the content needed to make your website sing. Many Joomla! developers face common implementation hurdles, some might want to rapidly extend the Joomla! core functionality or might want to create new and exciting extensions.

This book has a "wealth" of solutions for problems that Joomla! developers face regularly. It provides step-by-step mini examples which show how to overcome common design and implementation problems when creating Joomla! extensions. It will help you setup a sustainable collaborative development environment using the powerful free services offered by

This book can be used in different ways. It can be used by the pro Joomla! developer looking for a specific solution to a problem and can also be used by a novice developer looking for an insight into an area of common problems, such as effectively handling errors in Joomla! Readers who choose to read an entire chapter will first be given a brief overview of the topic in hand and its role and importance when developing for Joomla! The Recipes contained within the chapter will introduce the reader to specific problems and provide hands-on solutions. It provides solutions for core design topics including security, data access, users, sessions, and multilingual capabilities.

Publication date:
September 2009


Chapter 1. Development using and SVN

This chapter contains the following recipes:

  • Setting up a project

  • Managing members of a project

  • Setting up Subversion

  • Understanding the Subversion skeleton

  • Understanding revisions in Subversion

  • Understanding the Subversion process

  • Checking out a Subversion repository using TortoiseSVN

  • Editing a working copy using TortoiseSVN

  • Inspecting changes using TortoiseSVN

  • Updating a working copy and resolving conflicts using TortoiseSVN

  • Committing changes using TortoiseSVN

  • Exporting a working copy using TortoiseSVN



In this chapter, we investigate how we can utilize the free project hosting service. In particular, this chapter addresses how to use SVN (Subversion) and how to work with SVN using the popular visual TortoiseSVN client for Windows. ( ) provides a project management solution for open source Joomla! projects. The following list describes the tools that provides us with:

  • Document Manager: Simple document publishing (usually documentation)

  • File Release System (FRS ): Packages released by the project

  • Mailing Lists: Multiple mailing list manager

  • News: Latest project news

  • Public Forums: Discussion forums for users

  • Public Wiki: Collaborative online documentation

  • Source Control Management (SCM): Manage code base using CVS, SVN, or Git (in this book we focus on SVN exclusively)

  • Tracker: Manager for tracking feature requests, bugs, and patches

The following diagram shows how these various tools can be thought of when used together. Note that this is not a concrete representation; how we utilize the tools that provides us with is always the overriding factor.


Don't let the tools dictate the processes

Software development isn't just about the tools we use. It is about the processes we undertake. We should use the tools that best fit our processes, as opposed to using the processes that happen to fit our tools.

Before we continue, we should take time to note that not all projects will successfully qualify for project space. only supports non-commercial open source Joomla! projects. Remember that non-commercial and open source are not mutually exclusive; it is possible to commercially release an open source product. If we are not creating a non-commercial open source project, there are other similar free and paid-for services; the following table compares four popular alternatives:


Assembla (1)

Google Code

SourceForge (7)


Free Project Hosting





Commercial Project Hosting





Closed Source Project Hosting





Public Forums

YES (2)

YES (4)




Subversion, Git, Mercurial



Subversion, Git






Document Manager


YES (5)

YES (8)

NO (9)


YES (3)

YES (6)





YES (5)



Mailing Lists


YES (4)



Public Wiki




NO (10)

  1. Assembla intends to add a package to their catalog, specifically for Joomla! projects. This package will enable an enterprise-level commit-stage-release cycle in the development process. Assembla also provides an unusually high level of integration with other services; for example, we could hook into a Subversion repository.

  2. Assembla Messages Tool can be used to this effect.

  3. Assembla does not offer a News tab. However, Assembla will display a stream of all project activity, and a Messages tab.

  4. Google Code integrates with Google Groups. Google Groups provides public forums and mailing lists.

  5. Google Code provides downloads which can be used as an FRS and Document Manager.

  6. Google Code integrates with Blogger, and a blog can be used to this effect.

  7. SourceForge is very similar to (the underlying systems are much the same, GForge, used by, is a fork of the SourceForge system).

  8. SourceForge Documentation Plugin can be used to this effect.

  9. Unfuddle does not specifically provide a Document Manager, but files can be attached to tickets, messages, and notebooks.

  10. Unfuddle does not provide a public wiki, but does provide notebooks that can be used like a private wiki.


    SVN is an SCM tool, and SCM is part of SCM… Confusing, isn't it! Let's try that again: Subversion is a Source Control Management tool, Source Control Management is part of Software Configuration Management. Which just goes to show the computer industry really does love its acronyms just a little too much! Even the IETF likes to have some fun with this once in a while can be thought of as a system that provides Software Configuration Management. And as part of that package, we get Source Control Management tools. The topic of Software Configuration Management is beyond the scope of this book, and we will not be discussing it further.

Source Control Management is an integral part of modern software development. We need Source Control Management in our projects because it:

  • Allows concurrent collaborative development of source code (working copies)

  • Tracks all changes made to the source code (revisions)

  • Provides states to which we can return at any time (revisions)

  • Allows parallel development of various functionality (branches)

  • Can be used to manage releases (tags)

  • Can be used to maintain older versions (releases)

  • Provides a common vocabulary for discussing Source Control Management

Source Control Management does require a good level of understanding if it is to be used effectively. This book covers the basic usage and theory of using Subversion.


Subversion client freedom

Although in this book we work exclusively with the popular TortoiseSVN visual Windows Subversion client, it is possible to use several clients on the same working copy. Therefore, we do not need to worry about restricting ourselves to a specific client. For example, I use TortoiseSVN, CollabNet's command line client, and the Netbeans SVN plugin, dependant on what I am doing.


Setting up a project

This recipe describes how to set up our own project so that we can start developing and managing our new extension. Use of is not compulsory.

Getting ready

To set up a project we must create a user account. To register for a user account, all we need to do is follow the Register new account link displayed in the top-right corner of the web site.


The username we choose will be used for all activities that we initiate with, for example using a SVN repository.

Tip usernames must be lowercase. If you request a username with uppercase characters, these will be automatically replaced with the lowercase equivalent.

How to do it...

To create a new project we navigate to the My Stuff tab at the top of the page. This presents us with all sorts of information about our account. From the menu items on the lefthand side, select the My Account item. In the expanded menu there is an option to Register Project, shown as follows:

Once we select Register Project, we are presented with a form that allows us to define our project. The following table describes the purpose of the fields:



Project Full Name

Complete name of the project. This will generally be the name of the extension that we want to develop using

Project Purpose

What the project will be used for. This information is used exclusively to determine if the project should be approved for inclusion on

Project Public Description

Description of the project that is publicly viewable and searchable. This description is shown on the project home page and in the project listings. When a user searches for a project, both the project name and description are searched.

Project UNIX Name

Restricted to alphanumeric characters, this field is used to uniquely identify the project. It is important to select a good UNIX name because the UNIX name of a project can never be altered. The UNIX name is used to identify the project home page, define the file repository location, and to access the GForge shell.

The UNIX name must have the following properties:

  • Unique to

  • Contain between 3 and 15 characters

  • Contain only lowercase characters

  • Contain only characters, numbers, and dashes

Homepage URL

If as part of the project we also maintain a web site external to, we can specify this here.

Template Project

Template to use as a basis for the new project. Selecting Empty Project provides us with a clean slate.

Trove Categorization: Development Status

Maturity of the project. When creating a new project it is likely that the project will be in the early stages of development, for example, Planning or Alpha.

Trove Categorization: License

The License under which the project is released. Remember that hosting is only available for open source projects.

Trove Categorization: Programming Language

The primary programming language in which the project is written. The majority of projects are PHP and at the time of writing 86% of projects are defined as PHP projects.

Trove Categorization: Topic

The topic that best describes the project. The topics are organized in a way similar to JED. This is really intended to allow users to browse through the projects. However, most users prefer to use JED because it is more complete and provides a greater level of feedback from users of extensions.

Trove Categorization: Intended Audience

The type of user for whom the project is intended to provide services. For example, a project that provides code libraries would be considered to be intended for developers, where as a project that generates tag clouds would be considered intended for end users.

After submitting the registration form the project is ready for approval by the team. The approval process is administered manually, and so it may take some time before the project is approved. If there are any problems with the approval of the project, we will be contacted and given the opportunity to further explain the project.

Once the project has been approved, an approval confirmation email will be sent to us. The following screenshot shows the email received for the project My Project, UNIX name example-project.

We should now have a project ready to go! It is generally a good idea to edit the project home page at this stage. To do this, press the Edit project's homepage button displayed on the home page itself.

There's more...

Jo projects are based on plugins. Each plugin provides us with a specific piece of functionality. When we look at the admin page for the project we find a list of plugins that we can enable and disable.


It is generally best to enable each plugin as and when we require it. Projects that enable all plugins but do not actually make use of them can be frustrating for users who are trying to find information about the project.


Getting Help

Joo uses GForge, and so the GForge documentation can prove helpful. Refer to for more information.

See also

The following two recipes explain how to manage members of projects and how to set up a SVN repository.


Managing members of a project

This recipe explains how, as an administrator of a project, we can manage members of a project. The members are the users who contribute to a project. The nature of the contributions does not necessarily have to be code development. For example, a member may contribute by regularly answering questions on the project forum and contributing to the project Wiki.

Ho w to do it...

We manage members of our project using the Admin Options displayed to the righthand side of the project admin page.

To add a new member, select the Manage Members and Roles option. On this page, we will see a list of users who are already members of the project and their role in the project. At the bottom of this list is an option to add a new member. In the example shown as follows, we are attempting to add the user webamoeba to the project with the Role of Admin.

Once we're all done, the new user will appear in the members list.

How it works...

Members of a project are always assigned a role. Roles define what a member can and cannot do. By default there is a single role, Admin. Allocating this role provides members of the project full administrative access to the project. Generally speaking, there should be only one or two members to whom this role is applied.

We can define additional roles and we can edit existing roles using the Edit Roles option in the Admin Options box. It is only possible to change permissions for plugins that are enabled in the project.

There's more...

In addition to manually specifying users that we want to add as project members, users can request to join projects. Users can do so by pressing the Request to join project button displayed on the project home page and entering a short description of why they want to join the project. It is then up to us as a project administrator to accept or decline their request. To do this we use the Browse Project Join Requests link in the Admin Options box.


Only allow users you trust

It is not uncommon to receive requests to join a project by users who have misunderstood the meaning of member. Before allowing any user to join one of our projects, we should confirm exactly why they want to join and if we actually want them to!


Setting up Subversion

This recipe describes how to set up Subversion for a project.


SVN is not just for collaborative development

If we are the only developer for our project, Subversion can still be of use. Versioning, tagging, and branching are all invaluable functions irrespective of the number of developers.

How to do it...

Firstly we need to log in to our project. From here we navigate to the Admin page. The Plugin Admin box displays the plugins that are active for our project; by default, none of the plugins will be activated. In the area named scm, change the radio button selection from None, to SVN repository. Once we submit our changes, SVN and SVN Admin will appear in the lefthand menu, as shown in the following screenshot:

There is delay between enabling Subversion and the repository becoming active. As soon as the repository is active, we can start using and browsing it!

How it works...

When we create a Subversion repository, the repository will be populated with a skeleton structure. The following screenshot shows us what our new repository should look like:


This initial repository skeleton conforms to the suggested way of working with Subversion. The next recipe explains this skeleton in more detail.

As we can see, there is a normal looking filesystem tree structure, each item in the tree is of a specified revision and age. The last log entry shows the message that was created when the identified revision was committed; in this case, it is Initial Repository Skeleton.

See also

For information about setting up a project on, please refer to the previous recipe Setting up a project.

In the next recipe, Understanding the Subversion skeleton, we investigate the purpose of the skeleton folders that are initially created in the repository.


Understanding the Subversion skeleton

This recipe explains the purpose of the initial skeleton folders that are created in a new Subversion repository.

How to do it...

Understanding the skeleton is vital when setting up a new repository. Getting it wrong early on in the set up process can lead to major problems later. There are three folders, each with a specific purpose. The following diagram describes the skeleton structure:

The folder that we will use the most is the trunk folder. This folder is the basis for all of current mainstream development activity. This is where the next release of the software will be developed.

The bran c hes folder is similar; current development activity also occurs here. However, it is not for mainstream development, it is used for parallel development. Parallel development is development that is taking place at the same moment in time but is pursuing a different goal. For example, if part of the developer team is working on a new area of functionality, to shield that line of development from the mainstream development—and vice versa—a new branch may be created specifically for that line of development.

It is important to understand that branches are nearly always reincorporated with the trunk at a later date. A new folder is created in the branches folder for every line of parallel development.

The concept of the tags folder in Subversion isn't much different from tagging in the semantic web. Tagging is all about semantics, giving things meaning. We create a new tag whenever we create a new release. Tags are always static, that is to say, no more development ever occurs to a tag.

So if there is no development, what's the point? A release will always be associated with a repository revision. For example, if we released our software at version 1.0.0 when the repository was at revision number 165, we could simply extract revision 165 at a later date to rebuild version 1.0.0. But 165 can hardly be considered an easy to remember number. Also, it does not bear any direct relation to version 1.0.0. Creating a tag that contains a complete instance of version 1.0.0 makes it semantically easy to understand, for developers and non-developers alike.

How it works...

OK, let's consider a really basic repository. This project has only one file, myonlyfile.php. There are two releases 1.0.0 and 1.0.1, and the developers are currently working on version 1.0.2. One of the developers is in the process of adding ACL support, and they are doing this separately from the main thrust of development. The following figure shows what the repository will look like:


Sticking to tradition

We do not have to work to these standards, and we can remove the skeleton structure if we do not want to use it. Generally speaking, it is best to stick to this arrangement, or a similar structure, because developers who are familiar with Subversion will be able to understand the repository structure immediately.

There's more...

Another useful folder we can add to the skeleton is the releases folder. The purpose of a releases folder is to enable release maintenance, after earlier releases have been surpassed by a newer release.

For example, if after we have released version 2.0.0 and if 20% of our user base is still using version 1.n.n, we may want to continue to resolve bugs in the earlier release. To manage this, we create a folder for each major release, which has been surpassed, in a releases folder. We can then continue to patch these versions without interfering with the main development.

The Joomla! project itself uses this approach. At the time of writing, in the Joomla SVN there is a releases folder that contains 1.0 and 1.5. Allowing continued maintenance of these versions whilst with the main development of 1.6 is addressed in the trunk folder.


Understanding revisions in Subversion

Part of what makes Subversion so useful is its ability to archive changes. This recipe looks at revisions and how they work in practice in a Subversion repository.

How to do it...

Revisions are expressed as a positive integer. Whenever a set of changes is committed to a repository, a new revision is created. The revision number is incremented every time changes are applied to the repository.

The revision number is global to the repository. In other words, it applies to all files, irrespective of which have been modified. The repository is always accessible as a whole at any given revision. For example, like pages in a book, when a new edition of a book is released all pages are of that edition.

The most recent revision is called the HEAD revision.

The following image illustrates how revisions and the skeleton described in the previous recipe correspond. Each circle represents a revision of the repository. The arrows represent the sources of the new revisions.

We can see that the trunk is continuously developed. We can see a branch created at revision 3 and reincorporated at revision 11. We can see two tags created at revisions 7 and 13 and that these are not modified after they have been created.

There's more...

Notice how the two tags are named 1.0.0 and 1.0.1. Revisions are a very technical (or if you prefer, nerdy or geeky or techie) way of referring to versions. Our tags have version names that are far easier to understand.

There is a standard form of versioning used by most software projects, which can be summarized as major.minor.patch. The impact of the changes dictates whether it is a major, minor, or patch update. For example, removing a bug would be a patch update, improving all of the views in a component would be considered a minor update, while adding some important extra functionality might be considered a major update.

Therefore, we can assert from our example that the changes made between version 1.0.0 and version 1.0.1 were a patch. Had we been using the revision number, we would not have been able to make any assertions.

See also

For information about setting up a project on, please refer to first recipe in this chapter Setting up a project.

In the next recipe, Understanding the SVN process, we will examine the theory behind the working practices of SVN.


Understanding the Subversion process

This recipe explains as a developer how to work with Subversion on a day-to-day basis.


This recipe purposefully avoids referring to concrete examples. This recipe does, however, refer to Subversion commands, Subversion commands remain the same irrespective of the client.

How to do it...

When we work with Subversion we need a working copy. A working copy is an editable copy of all or part of the repository that is held on a client machine.

A working copy contains hidden metadata which is located in the hidden .svn folders. This metadata enables a Subversion client to understand the status of the working copy and to communicate with the server from which the working copy originated.

We obtain a working copy by checking out all or part of the repository. It is possible to check out any revision of the repository. In most instances we check the contents of the trunk folder and the HEAD revision (latest and greatest!).

Every working copy has a BASE revision. This is the revision that forms the basis of the working copy. In time we will find it necessary to update the BASE revision of our working copy.

As soon as we have a working copy we can start the iterative process of development!

Checking out is a one-off event used to obtain an initial working copy. The following diagram illustrates the iterative nature of working with Subversion once we have a working copy. We start in the Edit Working Copy position, and make our way around the circle until we end up back where we started.

The following list describes each segment of the circle:

  • Edit Working Copy

    • Add new files and folders (svn add)

    • Copy existing files and folders (svn copy)

    • Move/Rename existing files and folders (svn move)

    • Remove existing files and folders (svn delete)

  • Inspect Changes (1)

    • Compare working copy with the repository (svn diff)

  • Update Working Copy From Repository

    • Check for new revisions after the local working copy was last updated/checked out (svn status)

    • Get the latest updates from the repository and merge them with the working copy (svn update)

  • Test And Resolve Conflicts

    • Resolve conflicts introduced during the update (svn resolve)

    • Test the working copy to ensure that the update has not "broken" anything

    • Edit the working copy if changes made during the update require it

  • Inspect Changes (2)

    • Compare working copy with the repository (svn diff)

  • Commit Changes (create a new revision in the repository)

    • Apply the changes in the working copy to the repository (svn commit)


    Commit only when ready

    As a general rule of thumb, we should only try to commit changes to an SVN repository once we have finished making a contained definable set of changes.


    Leave a digital paper trail

    When we commit changes to the repository, we should always include a short concise message that describes the changes made. Doing so will pay dividends later should we need to inspect past changes.


    The process is likely to differ in practice. For example, we may update our working copy several times and resolve conflicts several times before we come to commit any changes.

How it works...

Subversion uses the Copy-Edit-Merge paradigm to enable several developers to edit the same files at the same time. Unlike traditional file sharing, the Copy-Edit-Merge paradigm removes the risk of one user irrecoverably overwriting changes made by another user. This is achieved by forcing users to resolve conflicts between their own changes and other users' changes before they are allowed to write their changes back to the repository. And, of course, the repository maintains an archive of past revisions, so we can always step back over the changes made.

We can visualize the state of the repository and the working copies, as shown in the following illustration. Here we can see the Subversion server connected to the Internet. In this instance, there are three users, all with working copies. User One has checked out a branch named ACL. User Two and User Three have checked out the trunk. The base revisions are 10, 14, and 11 respectively.


Subversion servers do not keep a record of the various working copies. This means it is the responsibility of the developer to manage their working copy.


Locking in SVN

Subversion also supports the Lock-Edit-Release paradigm. This can sometimes be useful if we want to ensure that only one developer is editing a file at any one time.

There's more...

Subversion is an incredibly complex system. It is easy for new users of Subversion to underestimate its complexity, and as a result fail to maintain a repository correctly. The topic is far too big to cover in its entirety in this book. For more information, visit the official Subversion web site

See also

To find out how to set up an SVN repository, refer to the recipe, Setting up SVN. For information about applying the process described in this recipe, refer to all of the remaining recipes in this chapter.


Checking out a Subversion repository using TortoiseSVN

This recipe d escribes how to check out a Subversion repository using TortoiseSVN.

Getting ready

The first ste p we need to take is to download the latest version of TortoiseSVN and install it on our local Windows machine TortoiseSVN is only available as an MSI (Windows Installer). TortoiseSVN installation requires a reboot after installation.

How to do it...

To create a new working copy we use the context menu on the folder in which we want to create the working copy. This menu will provide us with the SVN Checkout option for the My Working Copy folder, as shown in the following screenshot:

Selecting SVN Checkout prompts us with a dialog box; the following table describes the options in the dialog box:



URL of repository

Location of the repository, for projects this is in the form, in most instances the optional sub location will be the trunk folder.

Checkout directory

Local directory into which we are checking out; this is automatically populated.

Checkout Depth

How much of the repository we want to check out. Generally this will be fully recursive, that is, all sub folders and files.

Omit externals

Also check out external repositories with which this repository links.


Revision of the repository to check out.

When we press the OK button, TortoiseSVN connects to the Subversion server and prompts for our user credentials. It is possible to checkout anonymously; for this we enter the username anonymous, and leave the password field blank. The checkout process will then begin.

The transcript describes the actions taken during the checkout. This will generally take quite some time, depending on the size of repository. We can see from the transcript above that a total of one file was added to the working copy.

We now have a working copy ready and waiting!

There's more...

If we browse to our working copy, we will find the folders and files from the repository. At this stage all of these will be highlighted with a green-colored tick mark. This means that the file is part of the working copy and it is up-to-date. The following image shows the various icon overlays used by TortoiseSVN to indicate the status of files and folders in a working copy. Exact icons may vary.

The status of folders is often inherited from a subfile or subfolder. For example, if a conflicted file exists deep in the tree, parent folders will be highlighted as conflicted. This makes it very easy to locate problems in the repository.


Hey! Teacher! Leave them .svn folders alone!

We should never make changes to the hidden .svn folders. These folders contain the metadata required by Subversion clients. If we do experience problems with a working copy, we should use cleanup, as explained in the Committing changes using TortoiseSVN recipe later in this chapter.

See also

For an explanation of the role of checkout refer to the Understanding the Subversion process recipe, earlier in this chapter.


Editing a working copy using TortoiseSVN

This recipe describes how we make changes to a working copy.

Getting ready

All you right-handers out there need to warm up your middle finger on your right hand. All you lefties need to warm up your middle finger on your left hand. The context menu in Explorer is about to become your new best friend!

Ho w to do it...

As soon as we have a working copy, we can begin editing a repository. Editing existing files is the most common action. We don't need to do anything special in order to do this; just pick your favorite IDE/editor and work normally.

Adding new files and folders is just as easy; we simply create them as we would normally. However, because it is possible for a working copy to contain unversioned files—files that are not part of the repository—we must inform TortoiseSVN about new files and folders.

To do this, we can do one of two things. We can tell TortoiseSVN before we come to commit the changes by using the context menu TortoieSVN | Add command. Alternatively, we can select unversioned files and folders when we come to commit our changes.

Deleting is achieved slightly differently to normal. We delete files and folders using the TortoiseSVN | Delete context menu command. If we delete files and folders in the normal way, when we update our working copy, the removed files and folders will be restored!

Renaming should always be done using the TortoiseSVN | Rename command. If we do not use this, TortoiseSVN will misinterpret a renaming as a deletion of the original file or folder, and the creation of a new file or folder.

Mov ing files and folders is achieved using the TortoiseSVN | Relocate command. When we move files or folders, we can only move them to a folder that is versioned. That is to say, the new parent location in the tree must already exist in the repository. We can, alternatively, drag the file or folder using the mouse context button to the new location. Doing this provides us with a number of options, which are as follows:

  • SVN Move versioned files here : Moves to new location

  • SVN Move and rename version files here : Moves to new location and prompts for a new name

  • SVN Copy versioned files here : Copies to the new location

  • SVN Copy and rename versioned file here : Copies to the new location and prompts for a new name

See also

For an explanation of the role of editing a working copy, refer to the Understanding the SVN process recipe, earlier in this chapter.


Inspecting changes using TortoiseSVN

This recipe explains how to inspect changes made to files in a working copy using the TortoiseSVN tool TortoiseMerge.

How to do it...

Imagine we want to document language strings introduced in our working copy. To do this, we would use the context menu TortoiseSVN | Diff command. This allows us to compare our working copy with the base revision. In the example shown in the following screenshot, we can see that the new language string BAR has been added.

We c an obtain a status list of files and folders using the context menu TortoiseSVN | Check for modifications command. This tool provides us with two useful options—view a list of changes between our working copy and the base revision; and view a list of changes between our working copy and the HEAD revision.


The ability to inspect changes can be especially useful if we are attempting to track down a bug. For example, if it is known that a bug was introduced in revision 70, we can compare revision 70 with its predecessor, revision 69.

See also

For an explanation of the role of inspecting changes made in a working copy, refer to the Understanding the Subversion process recipe, earlier in this chapter.

To learn about applying changes to the repository, refer to the Committing changes to a Subversion repository using TortoiseSVN recipe, later in this chapter.


Updating a working copy and resolving conflicts using TortoiseSVN

This recipe explains how to update a working copy and how to resolve any conflicts that arise as the result of an update.

How to do it...

It is possible to update a part or all of a working copy. For continuity, it is generally best always to update the entire working copy. To perform an update, we use the context menu for the part of the working copy we want to update. TortoiseSVN provides us with two update options. They are:

  • SVN Update : Update working copy to the HEAD revision (latest repository revision)

  • TortoiseSVN | Update to revision : Update working copy to the specified revision

Durin g the update process, it is not uncommon to encounter conflicts. In the event that a conflict does arise, we will receive an error message identifying the conflict. Conflicts must be addressed as soon as reasonably practicable.

When we browse to the conflicted file, we will see the file highlighted as conflicted and three other helper files, originalname.ext.mine, originalname.ext.rX, and originalname.ext.rY. These files respectively contain the working copy that we hadwhen we tried to update, the base revision, and the HEAD revision. The conflicted file contains a mixture of the changes.

The TortoiseMerge tool can be used to resolve conflicts; we access this tool using the context menu TortoiseSVN | Edit Conflicts command. The following example shows a conflict in which the language strings LOREM and IPSUM have been appended to a file, and are now conflicting.

TortoiseMerge displays three of the four files—originalname.ext.rY (Theirs), originalname.ext.mine (Mine), and originalname.ext (Merged). We can select which of the changes we want to use from the Theirs and Mine panes. We can also directly edit the Merged pane. In this instance, we would likely take the changes from Theirs (using the right arrow in the toolbar) and manually copy the changes from Mine.

Once we have resolved the conflict, we can save the file and mark as resolved using the button on the toolbar, or the context menu TortoiseSVN | Resolved command. This will remove the helper files and allow us to continue development of our working copy. More importantly, it will mean that we are now in a position to successfully commit our changes.


Files can contain more than one conflict. In these instances, we can navigate through the conflicts using the up and down arrows in the toolbar.

How it works...

When we update our working copy, the changes in the repository are merged with our working copy. It is this merging of changes that enables Subversion to allow several users to work on the same file at once. Sometimes, however, Subversion will not be able to successfully merge the changes as demonstrated. For example, if two developers edit the same file by inserting new content, and that new content is inserted at the same location, Subversion will not be able to determine how to merge the sources.

This is where human intervention is required. It may be that the two developers have added content that does the same thing; therefore, one of those sets of changes needs to be discarded. On the other hand, the changes may need to be manually combined.


A common source of conflicts when using Subversion to develop Joomla! extensions, are the INI language files, because new language strings are nearly always added to the end of the file.

See also

For an explanation of the role of updating a working copy, refer to the Understanding the Subversion process recipe, earlier in this chapter.

To learn about applying changes to the repository based on a working copy, refer to the next recipe, Committing changes using TortoiseSVN.


Committing changes using TortoiseSVN

This recipe describes how we commit changes to a Subversion repository.

How to do it...

To commit changes we make to our working copy, we use the context menu TortoiseSVN | Commit command. As with an update, a commit does not have to include the entire working copy.

The Co mmit dialog box allows us to select the files and folders—including unversioned files and folders—that have changed in our working copy that we want to include in the commit. We can also include a message. It is good practice to always include a message that briefly describes the changes that the new commit applies to the repository.

When we are happy with the selected changes that we want to apply, we simply click on the OK button. We will now be presented with a transcript dialog that will log the actions taken during the commit.

There's more...

Sometimes a commit will fail. This will usually be the result of inconsistencies in the working copy as the result of earlier failed Subversion actions. There is a quick and easy solution! Cleanup is an automated process that "cleans up" our working copy. To cleanup a working copy using TortoiseSVN, use the context menu TortoiseSVN | Clean up.


If using the TortoiseSVN cleanup command does not resolve the problem, try using the command-line client. This can prove more reliable. The command-line client cleanup command does not provide any output.

 $> svn cleanup H:\path\to\working\copy


To get a copy of the SVN command-line client visit

See also

For an explanation of the role of committing changes from a working copy, refer to the Understanding the Subversion process recipe, earlier in this chapter. To learn how to apply other users' changes to your working copy, refer to the previous recipe Updating a working copy and resolving conflicts using TortoiseSVN.


Exporting a working copy using TortoiseSVN

This recipe explains how to export files in a working copy to a new location. This can be especially helpful when we come to package a release.

How to d o it...

There are two very useful options that dragging folders outside of a repository using the mouse context button provides us with. There are two export options that enable us to export the contents of the working copy without copying the Subversion metadata. The options are:

  • SVN Ex port to here: Exports the versioned files and folders to the new location (without the .svn metadata)

  • SVN Ex por t all to here: Exports all of the files and folders to the new location (without the .svn metadata)

About the Author
  • James Kennard

    James Kennard is a computer programmer. He has worked with various PHP and MySQL applications, since 2002. He quickly discovered Mambo/Joomla! because of its flexible extension manager. James currently maintains one open-source Joomla! component, which has been translated into over fifteen languages. Moreover, he has plans to build two more open-source components. Examples of his work can be found on his personal website

    Browse publications by this author
Joomla! 1.5 Development Cookbook
Unlock this book and the full library FREE for 7 days
Start now