Synchronizing with Repositories
For many years now, working in groups, or simply wanting to protect valuable source code, programmers have used
Version Control Software to make sure that changes to any part of the code-base is populated throughout
the group. There are a number of systems available, and AmigaOS4 has direct support for both
The plugins that are currently available to CodeBench users are simply "frontends" for
the client programs, so as a consequence, the clients will need to be downloaded and installed before
attempting to use either the CVS or the SubVersion plugins. The relevant client programs can be downloaded at:
CVS Client from
SubVersion client from
Installation of both of these programs is explained in the documentation that is included in each archive respectively.
Using the cvs.syncplugin
This plugin is simply a set of requesters that prompts the user for an action, and depending on the response, performs
that action by running the client program with the correct arguments.
The source code for this plugin is included in the SDK directory of each CodeBench version to allow an example of how
third-party programmers could create plugins for other types of version control systems, or even improve on the basic
back to the top
Using the svn.syncplugin
As in the example cvs plugin, this too uses a simple system of requesters to interact with the user, and performs
tasks by running the installed svn client program. While the source-code for this plugin is not supplied, it is
closely based on the cvs.syncplugin above.
back to the top
Using the svntool.syncplugin
This plugin is a fully featured version of the svn.syncplugin. It allows the user to manipulate the files within
the "working copy" (the local mirror of the files hosted on the remote server).
To illustrate the usage of this plugin, which can be used with any SubVersion server, we shall create a new project
and "checkout" some source code which we can then manipulate with SVN Tool.
First, lets run CodeBench, and create a new project. For this exercise, we need to select the
"AmigaOS4SDK" type of project.
The project name doesn't matter for this project, as we are only testing. As such, we have created a new directory
in the RAM Disk: called "Test", and this is where we will download (checkout)
the source code into.
In order for this project to use any of the Version Control plugins, simply select the appropriate option, and enter
the name of the plugin we shall use in the gadget below. (You may also use the "GetFile" gadget
to select the plugin from a file requester.
All other options in the other tabs can stay at their defaults.
Now select "OK" to save the project file. You will probably be asked whether you wish to
create the project directory, so just answer "Yes". After the dictionary has loaded
(not applicable in the SE version), you will be left with an empty
project list. Normally, when creating a new project, we would opt to add some files
from the project directory, but we shall use the SVN Tool to add files from a SubVersion "repository"
(A remote server which controls all files in a particular project).
Select the "Synchronize" menu, and the SVN Tool window will open. SVN Tool has recognised
that the project directory does not currently contain the required SVN files, and is asking you if you want to create
a new "working copy" (a mirror of the files in the repository), which of course we do. Select
"New" to open the settings window.
As an example, we are going to checkout the 'dds.datatype' source code from
The first thing we need to supply is the URL of where the source code is located, and this information is given on the
project page of the OpenAmiga website. Like most SubVersion repositories, it requires a username and a password, which
need to be entered into their respective gadgets.
There are open repositories around which allow anyone to access, but we have chosen OpenAmiga for our example as their
projects are relatively small, and are OS4 specific (yes, favouritism - ed!). It
does require the user to open an account prior to using its SVN services though, so please see the
website for more details.
The "SubVersion" tab is used to specify where on disk the client program lives. The default installation of
the SVN client creates a "SubVersion:" assign and the "bin" directory is added to the system path.
What this all adds up to is that the system can find the SVN client program without needing to be specifically told
where it is. In this case, the default setting in this tab can be left alone. If you have the client program installed
somewhere special that the system doesn't know about, enter the full path to the client. The SVN client can be
downloaded from os4depot.
Selecting "Save" will store the details you entered so that they do not have to be entered
again, and the process of checking out (downloading) the files will begin. Bear in mind that this is
transferring files over the internet, so the speed of this operation will very much depend on your connection to the
server. Once the checkout has finished, you should see something similar to this:
This shows what files were downloaded. The last line tells you what version the working copy is, and will be the most
recent on the server. You can checkout earlier versions of the repository, more on that later.
OK, now we have the source in our working copy, we can pretty much do what we like with it. Of course, the usual
purpose of this procedure is to make some changes to the code and once those changes have been made, the modified files
need to be uploaded (committed) back to the repository. This allows any other developers
that come along, like us, to checkout the changes that have been made. This way, everybody is
working with the latest versions of the files.
In case you are thinking that there might be two programmers working on changing the same file, yes, it's a valid point.
Luckily, this is one of the main goals of version control software and its handling of such situations. The software will
handle "merging" the changes in the two files to create one file with the changes from both. This is
an extremely powerful feature, and it ensures that files stay current. Of course, there's only so much that can be
automated, and if the software cannot merge the changes because they are too extensive, it will mark the files as
requiring our attention, and the changes will then have to be merged manually.
One of the rules that affect the ability to be able to automatically merge changes is: "Commit often". This
means that the amount of changes that have to be handled at any one time is a lot less, so the chances of a successful
merge is much higher.
You'll notice that there are a number of buttons at the top of the SVN Tool window, and these control certain functions,
like adding and removing files, viewing certain properties of files etc. We shall discuss the specific function of each
button a bit later on in the detailed view, but for now the first button we will use is the
green circular button which displays the "status" of the working copy
(the local files).
The status output, on the freshly checked out files, will look like this:
Here we see all the files that are in the project directory, and their state. Because we have not yet changed any files,
they are all as they were when we checked them out, so they are unchanged (displayed in green).
Any subdirectories are displayed in the list as well as the files. You will also notice a ghosted file in the list,
which is the SVN Tool settings file for this project, and because it is not part of the working copy, it is
labeled as such.
Now we shall make the changes we require to the files in this project, and we can see what effect this has on the
display from SVN Tool. Click the "Finish" button, and then add the newly checked-out files to the
project. For our purposes we shall run the "revision" makefile rule, and modify a few other files.
Here is the status display after making the changes we need:
Straight away, we can see there is a marked difference in the status display. Let's take a closer look at what this
We have made some changes in the project files, and these files are shown to us by being highlighted in red with their
exact status shown in the second column. We can see by the output at the bottom of the window that there are 5
modified files, except we can only see 4. If you look at the "include" directory, you will see that it is in
its folded state, and because we cannot see the files inside of it, the directory name is highlighted for us. If we
were to expand that directory, we would find a file inside marked as modified too.
All the modified files have their checkboxes already ticked, which means that they are selected and will be included
when we proceed with the "commit" operation. If there are any modified files that you
do not want to upload to the server, you may un-tick the checkbox for that file, and it will not be committed.
In order to 'put' these files back onto the remote server, the second button (the green up arrow) will start
the commit operation. Each commit should be accompanied by a
"commit message", and it should describe the changes made to this revision. This is
very useful to you, and others, if they want to checkout a previous version for testing, as
they can view the "commit log" and see what was changed and when. We will see this log
in action a bit later on.
The SVN Tool has a built-in editor for composing the commit message, and it includes a list of the files that will
be committed, although this is not included in the message that is saved on the server.
Here we have added two lines at the top of the message to describe what we have done. The list of files is included
below the "tear" line (this line and beyond gets omitted in the message stored on the
Once we are happy with our message, we select "Use", and the process of uploading the
changed files will begin. If you want to abort, or want to reset the message, select "Cancel"
and you will be prompted on how to continue.
So that concludes our overview. We have shown you how to add files to a new project from a SVN repository
(checkout), and how to upload any changes back to the remote server
(commit). We shall now cover the toolbar buttons and the more advanced functions below.
back to the top
So we have seen above how to checkout files, and how to commit them
back again. Now we shall take a closer look at the toolbar, and what functions it offers. While this details the
SVN Tool, it is by no means intended to be read as a an exhaustive documentation on the use of SubVersion.
For full documentation on how to use SubVersion, please visit the SubVersion
website. We also recommend the
SVNBook website at
red-bean, who offer HTML and PDF versions of their highly informative book on
SVN and its inner workings.
Gather and display the current status of the working copy. (See above)
Commit any changed files back to the repository.
Update the working copy with any newer files from the repository.
Try and repair any locks that may occur due to partial commits or updates.
Add a directory into the working copy.
Add a file to the working copy.
Remove the selected files.
Drop the selected files.
Show information about the currently selected file.
Undo the changes to the local file by replacing it with the one from the repository.
Show the differences between the file in the working copy and the one in the repository.
Show the history of changes in a file in the repository by either revision or author.
Checkout a particular revision of the repository.
Open the SVN Tool preferences.
back to the top
This is the default action, and will display all the files in the project directory (and any subdirectories)
and list what their current state is. Files that have been recently added, removed or modified will be highlighted in
red and have their status listed next the file name. From here, you can get information on files and directories and
view the commit log.
back to the top
This action will commit all changed files that have their checkboxes ticked back to the remote repository. Each time
files are committed, a message should be supplied which details the changes that this revision includes. These commit
messages can be read when viewing the log of a file or directory, and helps if you want to
checkout a previous version for testing purposes. See the Info button for more information.
During this operation, the changes from your files will be merged with the file on the repository, and any other
pending changes too. This is the main strong-point of Version Control Software, and it is this ability to track the
changes that makes the system so versatile.
back to the top
While committing your changes back to the repository to allow other users access to them, this allows you access
others to changes from other users by updating your working copy from the repository. Once the Update has started,
this will download any files from the repository that are newer than the files in the working copy. By updating
regularly, you ensure that you are always using the latest versions of the source code. CodeBench will automatically
prompt you to perform an update when loading a project that hasn't been updated for at least 7 days. This action
will also replace any files which are deemed as "lost". If a file in the working copy gets deleted,
accidentally or on purpose, then Update will replace it with what is currently stored in the repository.
If you have changed files in your working copy, the SVN client will attempt to merge these changes with the file
being updated, creating a hybrid of the remote changes and your own. While this functionality is very powerful,
it may not succeed if there are too many changes or the changes are too extensive. In this case, the status of the
file will be set to "<Conflict>", and you will need to merge your changes manually with the newly
updated file. There may be a file placed in your project directory that shows where the conflicts are, and this may
make the merging job easier. Basically, follow the golden rule of "Commit often" and you should never see
a file with a "<Conflict>" status.
back to the top
Because you are dealing with files over the internet, it is always possible that something may occur during a transfer
which can interrupt or truncate a file. If this happens, it is likely that you will end up with some files that are
"Locked". This option scans the working copy and tries to repair any faulty files that it finds.
If a file is seriously corrupted and cannot be repaired, sometimes deleting the corrupted file from the project
directory and performing an Update operation will restore it. NOTE: This
involves deleting the file from DOS, not via a Remove operation from SVN Tool. If the file is
not found locally, it will be replaced when updating, but a Remove will delete the file from the
repository as well, which isn't what we want.
back to the top
During the life of your project, you may want to add a subdirectory in which to put some more files and better organise
it. You will be prompted to enter the name of the directory. The "Abort" button will cancel
this operation, while "Create" will add the directory with the name you entered.
If you perform a Status operation, you will see the new directory listed with its state as
"<Added>". In order to add this directory to the repository as well as the working copy, you need to
commit this change. Then, and only then, will other users see this change. When they perform an
update, the directory will be automatically added to their working copies too.
back to the top
You may want to add files to the new directory you have just created, or perhaps just in the project directory.
There are two ways to add files, the first is to select this option without highlighting any files in the
Status list. This will then open a standard file requester where you may choose the files you
want to add to the working copy.
The second way is to select from the ghosted items in the list. We briefly discussed these files in the overview,
and these files are marked as "<Not in repository>". What this means is that although they are
listed in the project directory, they are not actually part of the working copy. There may be numerous reasons
for this, and typically items like personal configuration files would not be included in a repository which
multiple users access. Lets assume you have created a new source file, and you have run the
Status operation on the project. Your new file is shown as ghosted, so in order to add it,
select it by clicking the mouse over it in the list, and click the Add button. You will see the
output from the SVN client as the file is added. You can select multiple files to add, both from the list and
from the file requester, but only files that are not already added will be processed.
Again, just like MkDir, once files have been added to the working copy, these need to be
committed in order to upload the changes back to the server. Once you do that, other users
will automatically receive the new file when they perform an update.
back to the top
Just like you can add files to the working copy, you can also remove them too. Select the files
you wish to remove from the Status list by clicking the mouse over the file name, and the
Remove button becomes active. Click the Remove button to start the process of
removing files. You may remove only files that are part of the working copy (and ultimately the repository). You
will see the output from the SVN client as the files are removed.
A Commit operation must be performed to permanently remove these files from the repository.
When other users of the repository perform an update, these files will be automatically
removed from their working copies too.
back to the top
This is not a standard SVN operation, but one that the SVN Tool implements itself. It works in a similar manner
to the Remove operation, but with the exception that a local copy of the file being dropped is
left in the project directory. After performing a Status operation, you will see the file
listed but no longer part of the working copy.
A Commit operation is required for this action to become permanent. Other users will have
the file deleted when performing an update.
back to the top
From here you can view certain information about the selected file or directory. Here we are showing the
information known about the project directory. As you can see, the upper portion shows the static information, and
the lower part the details of when the last change was made.
As we discussed briefly above, the Log is probably the most important part of this information. That does depend,
however, on the quality of the commit messages. For those of you that work as a single programmer on a project, this
is perhaps not so vital, whereas those that work in groups will find the Log History essential in tracking what changes
happened and when.
Here is the Log History for the project directory. Unfortunately, the commit messages are rather empty, so trying
to determine what changed with each revision is going to be difficult.
Viewing the Log History for the project directory will show you all the revisions for the whole project. We could
just as easily view the log for one of the files in the project, and the list would only include revisions where
that particular file changed. This allows us to see specific changes for a file, or all changes in the project,
depending on what information we are after.
back to the top
This option is useful for programmers that want to experiment with the code, or for when testing particular code
sections. Let's take our example above and select all the files that have changed by clicking them with the mouse
(you will need to hold down the shift key to select multiple files). With all 5 files selected, click
the revert button and these files will be replaced by the versions stored on the remote server. This effectively
removes the changes we have made, and is useful when testing different scenarios in the code, and then resetting
the code after the testing has finished. Obviously, the changes you have made will be lost. There is no need to
Commit after this operation has completed, as you have only downloaded and replaced files,
no remote changes have occurred.
back to the top
It may sometimes be appropriate to view the differences between a file in the working copy and the one stored on
the remote server. This is what the Diff operation is for. From here you can view where the changes in a file
have occurred. This may help ascertain whether a changed file should be committed or
In our example project above, we have made some changes to the "Makefile" file. Selecting that file
in the list, and selecting this option opens the "Diff" window.
There are 3 panels in which various information is shown.
Firstly, the "Changes" section shows all the sections of the file that has been changed, and allows
you to jump to a specific area for easy viewing. As you move the cursor from line to line in the
"working copy" panel, the highlighted item in the list may switch from one to another. This works
exactly like the "Quick-Link" window and shows you in which
section the text cursor is currently placed.
The "Working copy" panel shows the local file in its entirety. Changed lines reported by the SVN
client are highlighted in red, but typically the changes are bordered by a few lines at the top and bottom.
There are also some small graphical symbols which show you what kind of change has been made. A "+"
symbol means a line was added, and a "-" symbol means a line was taken away. Lines highlighted in
yellow are the bordering areas reported by the SVN client and have not been modified.
Lastly, the "Original section" panel shows what the corresponding text looks like in the stored
file on the repository. Placing the cursor in a highlighted section of the "Working copy" will
show the associated block here, and this allows a quick and easy view of the changes that have been made to
a specific section of the file.
You may select multiple files from the SVN Tool to view the differences of, and each one will be added as a
separate file, each with its own "tab", making it easy to switch between files for comparison.
You may also select more files from the main SVN window and select this option to add them without the need
to close the "Diff" view. A new "tab" will be created for each file added.
back to the top
Despite its name, this feature can be very useful when trying to revert changes in a file in the repository.
It will allow you to see what changes were made to a particular file, and in what revision those changes were
made. This feature gets its name because it will also show you those changes and who made them.
Select a file in the main list, and you should see the Blame button highlight (You may also select multiple
files from the list, and those files that are applicable will be added to the Blame window). Only files
that are part of the repository and subsequently in the working copy can be viewed, and those files must have
been committed back to the repository. It is not possible to use this feature on modified
files, and a requester will display this warning.
To illustrate the various different revisions and authors, we have selected a file which is part of the
OpenAmiga "Filer" project.
In the list on the left hand side, we can see all the different revisions that this file has undergone. By
selecting one of these, the source of the file on the right will have all the affected lines highlighted. A
brief description will be shown in the status bar under the text, and this will show who committed the revision,
and how many changes were made.
The chooser gadget above the list will allow you to switch to the different users that have committed revisions
too. Again the status bar will show how many changes were made, except this time the amount of changes is a total
amount made in all revisions committed by the selected author.
This makes it very easy to tell what changes were made and when or by whom, hence the functions name.
In this view, we have switched the list to show the authors that have committed changes to this file. We have
selected the user "Rigo", and the status bar shows us that there have been a total of 10 changes
commited by this author in all of the revisions submitted by this user. All the affected lines are now
highlighted in green to make it easier to see which lines are changed.
If you hover the mouse pointer over any of the revisions or authors in the left hand list, the help hint will
show various information pertaining to that entry in the list. This allows you to see what changes will be
highlighted if you select this item.
Just like the "Diff" window, you can use this window and the main window at the
same time, and add more files to it as you require. Closing the main window will also close this window
back to the top
This option can have two modes of operation.
The first is to download the code from a repository into a clean directory on the local machine. This will
inevitably download the latest revision of the repository.
The second mode is to download a complete revision of the repository, which may not necessarily be the latest.
This is sometimes required if the changes made to the latest revision are problematic, downloading an older
revision that doesn't have those changes can help to see why the problem might occur. Of course, the log
history may also come into play here providing the commit messages are detailed enough.
As you can see from our above overview, when the SVN Tool is run for the first time
with an empty project directory, you will have the opportunity to checkout the latest revision of a repository.
You will need to know the URL (internet location) of it, and also any login details required.
Once you have checked out some code, selecting the Checkout operation again will then open a requester which
will list all of the revisions currently in the repository. You may select one of these revisions by clicking
it with the mouse, and selecting the "OK" button. If there are any outstanding
changes to the working copy, you will be notified of this, and given the option to cancel the checkout.
Once the operation has finished, the working copy will be synchronized at the version you selected, and this
will include adding or removing files and directories as required. This is why committing your changes back
to the repository is so important, especially when working in a group, and helps to cut down the chances of
a failed merge. Any changes made prior to the Checkout operation will be lost unless they are
back to the top
This requester is very basic, and only has a few groups of settings.
The first group is the location of the repository to which this working copy should mirror. It also allows for
any login details to be entered (if required). NOTE: These settings are only editable when
initially creating the working copy. Once created, these details are for informational purposes only, as
changing the URL of the repository can have consequential affects on the files stored.
The second group of settings simply allow you to set the location of the SVN client, and is covered in more
The Directories tab allows you to change the directory from which Commits and Updates
(Put and Get respectively) are performed. You may be wondering why that might be useful...
Let us imagine that your current project is actually part of something larger, and buried in a subdirectory of
the entire project hierarchy. A good example of this might be a program that has a library. The program may well
be treated as a project in its own right, and the library also. Normally this wouldn't be a problem, but the
possibility is that some common files may be changed while working on the library, but the programs
project would not see those changes as these files are outside it's home directory.
By changing the directory to perform put and get operations, we can allow the Subversion client to do its work from
a directory higher up in the tree where the common files will get updated. Imagine if you will:
If we try to perform a commit operation from the "Program" directory, any changed files in the "Include" directory will not be sent to the repository, so by changing our "Commit Directory" path to the "Trunk" directory will mean any changed files will be sent to the repository and thus nothing gets missed. Similarly, performing an update from the "Library" directory would mean that the changed files in "Include" would not be updated, and vital changed could be missed.
Although the two directory settings are treated separately, they are equally applicable, and as such you should probably set them both to the same higher directory to be sure nothing is missed.
|back to the top