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 CVS and SubVersion.

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 os4depot.net

SubVersion client from os4depot.net

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 plugins supplied.

 

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.

 

New SVN 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.

SVN url As an example, we are going to checkout the 'dds.datatype' source code from openamiga.org.

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:

SVN Checkout complete 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: SVN Status

 

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:

SVN Status Straight away, we can see there is a marked difference in the status display. Let's take a closer look at what this means.

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.

SVN Compose

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 server).

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

 

 

Detailed View

 

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.

 

  • SVN Status Button Gather and display the current status of the working copy. (See above)

  • SVN Commit Button Commit any changed files back to the repository.

  • SVN Update Button Update the working copy with any newer files from the repository.

  • SVN Clean Button Try and repair any locks that may occur due to partial commits or updates.



  • SVN Add Directory Button Add a directory into the working copy.

  • SVN Add File Button Add a file to the working copy.



  • Remove File Button Remove the selected files.

  • SVN Drop File BUtton Drop the selected files.

  • SVN Information Button Show information about the currently selected file.

  • SVN Revert Button Undo the changes to the local file by replacing it with the one from the repository.

  • SVN Diff Button Show the differences between the file in the working copy and the one in the repository.

  • SVN Blame Button Show the history of changes in a file in the repository by either revision or author.



  • SVN Checkout Button Checkout a particular revision of the repository.



  • SVN Preferences Button Open the SVN Tool preferences.




    back to the top

 

SVN Status Button Status

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

 

SVN Commit Button Commit

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

 

SVN Update Button Update

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

 

SVN Clean Button Cleanup

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

 

SVN Add Directory Button MkDir

SVN Make Directory Button 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

 

SVN Add File Button Add

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

 

SVN Remove File Button Remove

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

 

SVN Drop Button Drop

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

 

SVN Information Button Info

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.

SVn Log 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

 

SVN Revert Button Revert

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

 

SNV Diff Button Diff

Differences between two files 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 reverted.

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

 

Blame Button Blame

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.

svnblame1 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.

 

 

 

SVN Blame2 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 automatically.

back to the top

 

SVN Checkout Button Checkout

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.

Choose Revision 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 committed first.

back to the top

 

SVN Preferences Button Preferences

URL preferences 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 detail above.

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:

Trunk <dir>
Program <dir>
Library <dir>
Include <dir>

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

Valid XHTML 1.0 Transitional This is a W3C checked and compliant web page.