A version control system is project support software that allows:

• Storage of file documents in a central repository
• Access to files through a checkout process
• Updating of the repository by allowing users to commit changes to files they have checked out
• Synchronization of files checked out by multiple users through an update process

Version control systems can be used to organize any collection of documents, including NetBeans project files.

This presentation describes how to use Subversion to set up a repository, and how to use NetBeans to access it. For project teams, one team members sets up a subversion repository and a server. This is only done once at the begining of team coding efforts.

After the server and repository are set up, all team members use a subversion client that communicates with the server to access the repository.

NetBeans provides support for three version control systems:

• Git
• Mercurial
• Subversion

This presentation shows how to use Subversion with NetBeans.

Subversion is an Apache Software Foundation project.

O'Reilly publishes a free, online book Version Control with Subversion.

Subversion uses a client-server architecture.

The server stores the repository and handles clients' requests for access:

The Subversion server program is called svnserve.

One of the members of your team could run the server on their own server machine if they have one. This would require that the machine be:

• Constantly connected to the internet
• Constantly up and running svnserve

Or, your team can make use of the CS Department file server, an approach that will be described in this section.

All CS and CIS majors have disk space provided by the CS Department.

This space resides on a file server with host name ukko.d.umn.edu, and where Subversion is installed.

Once your team has started a server and configured a project repository, you will be able to access it through NetBeans and a subversion client.

There are five basic steps:

• Login to ukko
• Create the repository
• Authorize a repository user
• Configure the server
• Manage (start and stop) the server

It is important that the same person perform these steps, because the server process and repository folder must be owned by the same user.

In the descriptions that follow, suppose the person setting up the repository has UMD username smit0012.

You will need to be connected to the internet, and you will need to know your UMD X.500 username and password.

If you are using linux/unix, open up a terminal window and do:

     ssh smit0012@ukko.d.umn.edu
      

If you are using Windows, use an ssh client like putty. After successfully logging in, you will be connected to ukko via a command-line interface.

Go to your CS Department disk space (if not already there):

     cd /home/csugrads/smit0012
      

Create the repository, in this case called cs4531project:

     svnadmin create cs4531project
      

Make the repository folder publicly inaccessible:

     chmod 700 cs4531project
      

Go to the configuration folder for the repository just created and observe the configuration files (note that system responses are shown in green):

     cd cs4531project/conf; ls
     authz  passwd  svnserve.conf
      

You will need to edit svnserve.conf and passwd.

Use an editor (emacs, vi, or pico) to open the file passwd and add a line (or lines) to the bottom of the form:

     username = password
      

where username and password are made up by you for your team members to share when accessing the repository. (Apparently digits are not allowed in either.)

For example:

     bill = billsecret
      

Since passwords are stored in clear text you should make sure that the passwd file is not readable by others (giving the repository 700 permission sees to this).

Q: When a user accesses the repository remotely with a password, how is it not transmitted over the network?

A: The server uses CRAM-MD5 authentication, in which the user's password is hashed before sending. The same hash is performed on the stored password, and the hashed results are compared during authentication.

Open the file svnserve.conf and scan through it. The lines that begin with a sharp sign ("#") are comments. You will see some uncommented lines containing nothing but a name enclosed in brackets such as "[general]". These lines begin sections of the configuration file. A section ends at the beginning of the next section or at the end of the file, whichever comes first. You should add thefollowing lines at the end of the "[general]" section:

     anon-access = none
     auth-access = write
     password-db = passwd     
      

These indicate that:

• Anonymous access of the repository is not allowed,
• Authorized access has read/write permission, and
• The file containing your team's username and password is passwd (the default).

Since each team will have its own server instance, each instance will have to run on its own port. You can use any free port from 1000 to 65535. To avoid having to try several different ports I suggest you try port numbers from the following table with x ranging from 0 to 9. You will probably be successful on the first try.

Team	Port
1	901x
2	902x
3	903x
4	904x
5	905x

The rest of this section shows how to start and stop the server.

If smit0012 is on Team 1 then he/she starts the server with:

     svnserve -d --listen-port=9010
      

The -d option runs the server in daemon mode, which means it runs in the background and will continue to run when smit0012 logs off of ukko.

If you see the following message try again with the last digit of the port number incremented.

     svnserve: Can't bind server socket: Address already in use
      

The svnserve daemon will run until ukko is shut down or smit0012 or a sysadmin stops it.

To stop it, first find its process id:

     ps aux | grep svn
     smit0012 18386  0.0  0.0  98536  1128 ?        Ss   15:34   0:00 svnserve -d --listen-port=9010
     smit0012 18388  0.0  0.0   7624   896 pts/2    R+   15:34   0:00 grep svn
      

Here the process id is 18386. Now kill the process and confirm:

     kill 18386; ps aux | grep svn
     smit0012 18440  0.0  0.0   7624   916 pts/2    S+   15:39   0:00 grep svn
      

After the repository is set up any authorized user can access it from any client machine that has a Subversion client installed, by connecting over TCP/IP.

To get a Subversion client, you can go to the Subversion webpage and find binaries for most platforms.

Some Linux distributions provide package managers that make it easy to get and install Subversion (for example, Ubuntu's Synaptic Package Manager).

This section describes how to use a subversion client to access your repository.

A client can access the repository by making command line calls:

     svn import ... Put files into the repository for the first time
     svn checkout ... Get files from the repository for the first time
     svn update ... Get changes to files others have checked out
     svn commit ... Commit changes to checked out files back into the repository
     ... etc.     
      

These commands are documented in the free Subversion book.

Or you can let NetBeans make the calls for you. We will describe this approach next.

Note that NetBeans will assume you have a Subversion client installed.

Suppose you have a NetBeans project, say MyProject, that you want to import into the repository so that it is available to your team.

The rest of this section describes the import process.

Note that a project is imported into the repository only once. Files are added or changed through a commit process (described later).

With MyProject as your current project, select "Import into Repository ..." from the menu bar:

The resulting dialog calls for the URL of the repository with a specific syntax, along with user credentials.

Here are the components of the URL for the example shown below:

URL Component	In Example
Prefix	svn://
Host	ukko.d.umn.edu
Separator	:
Port	9010
Path	/home/csugrads/smit0012/cs4531project

A documentation string for the import is required:

On the initial import, all NetBeans project files should be imported.

That way the entire NetBeans project can be checked out by your team members.

Once a NetBeans project has been imported into the repository, it can be checked out by authorized users.

As with importing, a project is checked out by a user just once, after which arbitrary changes can be committed to the repository.

The rest of this section describes the checkout process.

Launching the checkout dialog is similar to launching the import dialog:

The repository URL and user credentials should be the same as those used for importing.

Note that if you check Save Username and Password, NetBeans will remember your credentials for future repository transactions:

If you know the name of the folder you are checking out, you can enter it directly here; otherwise you can click Browse... to choose from among the folders in the repository (there can be any number).

If you check Scan for NetBeans Projects after Checkout, NetBeans will give you the option of opening the project after checkout:

Upon clicking Open Project, the project will be opened in NetBeans.

You can tell when you have made saved modifications to a file in a checked out project:

• Its name is rendered in a blue font
• Its folder shows a small blue icon:

This section describes how to commit your modified files to the repository.

This example shows right-clicking on the modified index.xhtml file and selecting the Subversion commit operation:

Commit operations require an accompanying documentation message:

Note that NetBeans remembers your authentication credentials from when you checked out the project.

After initiating the commit, in NetBeans' Output tab you should observe something like:

     ==[IDE]== Feb 24, 2012 12:23:21 PM Preparing Commit...
     ==[IDE]== Feb 24, 2012 12:23:21 PM Preparing Commit... finished.
     ==[IDE]== Feb 24, 2012 12:25:10 PM Committing...
     commit -m "My first modifications to index.xhtml" .../MyProject/web/index.xhtml
     Sending        .../MyProject/web/index.xhtml
     Transmitting file data ...
     Committed revision 3.
     Revision: 3
     Author  : team1
     Date    : Feb 24, 2012 12:13:56 PM
     My first modifications to index.xhtml

     ==[IDE]== Feb 24, 2012 12:25:12 PM Committing... finished.
      

If you have made changes to multiple files, you can commit them all at once by initiating the commit on a folder, as shown to the right.

There, the Web Pages folder has been right-clicked.

It is also possible to commit changes made to all files in the project folder by right-clicking the project (in this case MyProject), however:

Committing changes to an entire project is not recommended as it may commit changes to project configuration (.xml) files that can cause conflicts among the checked out projects.

Since all team members have access to the same repository, it is possible that another member has already committed changes to a file you are working on.

For example, suppose that while you are working on index.xhtml, another member commits a modified version of it to the repository.

When you try to commit your changes, Subversion will notice that index.xhtml has changed since the time you checked it out, so it will force you to update your version, which we describe next.

It is a good idea to regularly update your version of a project shared among other team members, since

• It keeps you up-to-date on what your team is doing, and
• It minimizes the chances of having to manually resolve conflicts

This section describes the update process.

Since you probably don't know which individual files have been changed, you would start the update process by right-clicking a folder:

After initiating the update, in NetBeans' Output tab you should observe something like:

     ==[IDE]== Feb 24, 2012 1:31:25 PM Updating "web"
     update ... 
     U   .../MyProject/web/index.xhtml
     Updated to revision 4.
     ===== File Statistics: =====
     Updated: 1
     ==[IDE]== Feb 24, 2012 1:31:26 PM Updating "web" finished.
      

When you update a file you are working on with changes made by someone else, those changes are merged into your file gracefully provided they do not conflict with any changes that you have made.

An update produces a conflict in a file if it introduces a modification to a line that you have also modified.

For example, suppose you have made a change to index.xhtml such that line 9 reads:

     This line is modified by Jones.
      

Meanwhile someone has recently committed a change to index.xhtml in the repository such that line 9 there reads:

     This line is modified by Smith.
      

Now you will not be able to commit your change without updating, but when you update you receive the warning:

Now you have to resolve the conflict manually.

When an update introduces conflicts, they are indicated both in the project structure tree and in the files where they occur.

Note that files with conflicts are shown in red, and the Subversion icon has changed from blue to red:

To resolve conflicts, right-click the file with conflicts and navigate to Resolve Conflicts...:

NetBeans presents the conflicts by displaying the two file versions (local and remote) side-by-side and highlighting the lines in conflict.

When you decide to accept one version or another click Accept or Accept & Next if there is more than one conflict to resolve:

In this example the remote file version has been accepted.

Note that the remote changes have been incorporated into the Result after merge:

When finished with the conflict resolver you can save the changes you've authorized, after which the conflicts disappear: