Version control tutorial
About this tutorial
This tutorial introduces you to the most common version management tasks by walking you through the JBuilder CVS interface and the history view.
This tutorial consists of two lessons:
- Lesson 1: Using CVS in JBuilder covers the use of the JBuilder CVS commands. JBuilder CVS commands are only available in JBuilder Enterprise edition. To begin this lesson, you must have CVS installed and configured on your machine. For instructions on where to obtain the CVS software and how to install and configure it, see "Installing and Configuring CVS".
- Lesson 2: Using the history view covers the use of the history view with CVS. You can use the history view regardless of whether you have CVS or any other version control system installed. The history view is available in all editions of JBuilder 4, though the features differ. This tutorial covers all the features available in JBuilder Enterprise edition. For information on the features available in other JBuilder editions, use F1 Help from within any page in the history view.
Images used in this tutorial are taken from a Windows NT platform. For other documentation conventions, please see "JBuilder documentation conventions."
Definitions
These are words used in this tutorial that have specific meanings in the context of CVS version management:
Workspace |
The area you affect directly, and which you must maintain yourself. When you make changes to a file, you make them and save them in the workspace first. |
Update |
Retrieves changes from the repository and applies them to your workspace. |
Repository |
Contains the files you have put into version control and all their revision records. This may be on your local machine or on a remote server. |
Remove |
Removes a file from the repository. |
Project |
Refers both to the files and settings that make up one body of work, and to the organizational file used in JBuilder that manages the list of those files and settings. |
Module |
Contains a group of associated files that are stored together in the repository for better file management and user convenience. |
Merge |
CVS and some other systems don't lock files when they are being used. To preserve all changes, these systems use the merge command: it combines changes from the repository with changes in the workspace. Saved workspace changes are not overwritten, and textual conflicts are preserved and flagged to be reconciled by the user. In CVS, an update includes a merge. |
Diff |
An area of difference between two versions of a file. Also called a diff block. |
Commit |
Applies changes from your workspace to the repository. You must commit file changes, file additions, and file deletions to the version control system in order to make them available to other users. |
Checkout |
Posts a module from the repository to your workspace. When using CVS, this should only be done the first time. After that, files can be synchronized by updating them. |
Add |
Adds a file to the project module. |
Lesson 1: Using CVS in JBuilder
For this lesson, you will create a local CVS repository to work from. Since it will be created locally by you, you will have the access you need to complete all the steps in this tutorial.
You will create a project, put it into a module, and you will check that module out into two different directories. You will manipulate the same project module in both directories. This way you can replicate a multi-user development environment.
Before you proceed, create a new local directory called newcvs
. You will use it as a sandbox in this tutorial.
Step 1: Creating a local repository
You can create a local repository from the command line interface.
- At the command line, type:
cvs -d :local:[target drive or root]/repo init
and press Enter.
- CVS creates a repository named
repo
for you and returns you to the prompt. Run dir repo
from the command line to see the CVSROOT
directory in the new repository:
The following are features of JBuilder Enterprise edition.
Step 2: Setting up the project
You will create a project and add files to it. This gives you something to work with in order to use the JBuilder CVS interface and generate different versions of the same set of files.
Fist, create the project.
- Select File | New Project.
- In Step 1 of the Project wizard, make the project name
thisproject
. Accept .jpx
as the project file type.
- Change the root path to lead to the
newcvs
directory.
- Name the project directory
firstdir
.
- Click Finish in Step 1:
You now have an empty .jpx
project file. The next step is to populate it.
- Select File | New.
- Choose Application from the object gallery.
- Accept all the defaults in Step 1 and click Next.
- Check all of the checkboxes in the Options area in Step 2:
- Click Finish.
Step 3: Configuring version control
You now have a populated project file to work with in a directory that is separate from your work files. The next step is to configure your version control connection in JBuilder.
- Select Team | Configure Version Control. Select CVS as your version control system. The dialog box will look like this:
- Set your connection type to Local. The available login settings adjust to match the settings required by your connection type. Since a local connection requires no login, you will leave the Login area blank.
- Enter the path to the
repo
repository in the Module Location area. Since your repository is local, you can click the ellipsis (...) to browse to its location.
- Change the module name to
thismodule
, so it's easy to distinguish between the project and the module as you read this tutorial.
- Accept Autosave Files Before CVS Operations. File changes must be saved before CVS can recognize them, so this saves you the step of saving all of your changed files before you use a CVS command.
- Check Show Console Messages. This puts CVS console messages in the message pane of the AppBrowser.
- Click OK.
When you're done, the dialog box will look much like this:
- Click OK.
Step 4: Creating a module
You have created a project and set its default connection to the local CVS repository that you created in Step 1. The next step is to create a CVS module to put this project into. Doing so enables version control for the project.
- Select Team | CVS Project Create Module.
- Enter a description for the module when prompted. The dialog box looks like this:
- Click OK.
Tip: You can close the console message pane at any time by right-clicking the CVS Console tab.
Step 5: Committing file changes
You have created a CVS module for your new project. It now exists in the repository. The next step is to make changes and commit them. This way, your work is stored in the repository, where it's subject to version control and available to other users.
The changes used in this tutorial are extremely simple, so you can focus on the process rather than the code.
Frame1.java
will be active in the project pane.
- Insert // first change below the first line of code, as shown below:
- Select Team | CVS Commit "Frame1.java".
- Type made first change in the CVS Commit dialog box.
- Click OK.
- Expand the console icon in the message pane by clicking the toggle beside it or by double-clicking the console icon itself. You can expand the subsidiary icons to view all of the console messages related to what you just did:
- Close
thisproject.jpx
by clicking the Close Project icon
in the project toolbar.
Step 6: Checking out an existing module
You have created a module for your project and manipulated a file in CVS.
A module is created once, but it needs to be checked out by every user who needs to work on the project. Therefore, the next step is to check out an existing module and make changes to the project, just as if you were using a module that someone else had created.
JBuilder requires you to work from a project, but it protects you from damaging existing work when you use CVS. Therefore, you must check a module out into an empty project.
- Select File | New Project.
- Make these settings:
- Accept the default project name.
- Set the root path to
newcvs
.
- Name the project directory
seconddir
.
Your settings will look like this:
- Click Finish.
Configure the connection to version control for the new project.
- Set your connection type to Local.
- Enter the path to the
repo
repository in the Module Location area.
- Change the module name to
thismodule
, since you will be checking it out of the repository into this empty project soon.
- Accept Autosave Files Before CVS Operations.
- Check Show Console Messages.
- Click OK.
Now, let's check out the project module from the repository.
- Select Team | CVS Project Checkout.
- Click OK or press Enter when it tells you the checkout was successful. The project file name is changed to match the name of the project in the module.
The thisproject
project is checked out into the seconddir
directory. Let's make a change in a file, so you have a diff to examine later.
Tip: If you want to check which directory you're in at any time, select Project | Project Properties and look at the Paths page. It will show you the entire path of the active project.
- Double-click
Frame1.java
in the project pane. It will display in the editor.
- Change
// first change
to // second change
.
You don't have to commit immediately. You often won't when you're busy. Remove a file from the project now.
- Right-click the file
Frame1_AboutBox.java
once in the project pane.
- Select CVS then select CVS Remove "Frame1_AboutBox.java".
- The CVS Remove dialog box will display. Click OK or press Enter. This removes the file from the module in the repository.
- Click Yes or press Enter to commit the removal. This notifies the repository that
Frame1_AboutBox.java
is no longer in the module.
- Accept the default comment and click OK.
- Click OK or press Enter when the change has been committed.
Now commit the change you made before.
- Select Team | CVS Commit "Frame1.java".
- Type
second change made
when prompted. Click OK.
- Click OK or press Enter when the file is committed.
- Close the project.
Step 7: Updating a project
You have configured an individual CVS connection and checked out an existing project. Next, update a project in order to retrieve changes from the repository. Updating keeps your workspace current with changes other developers may have made to the files you're using.
You'll also view a file's CVS status. You can do that at any time.
- Select File | Reopen and choose
newcvs/firstdir/thisproject.jpx
.
- Notice that
// first change
shows in the content pane.
- Select Team | CVS Project Update.
- Click OK or press Enter in the CVS Update dialog box.
- Click OK or press Enter to return to the AppBrowser.
- Insert a new line in
Frame1.java
and type // third change below // second change.
- Select Team | CVS Status for "Frame1.java":
You didn't have to save it manually to show the file to CVS because you set JBuilder to save automatically before performing CVS operations.
- Close the project.
Step 8: Committing a project
The project is updated in the firstdir
directory.
Let's model a situation you encounter in the course of a real session.
You work on several files at a time, make a number of changes, and when you're working well you don't want to break the flow to maintain CVS. Sometimes someone else is working on the same files at the same time and makes changes you don't know about.
This step will give us an opportunity to use the CVS Project Commit option, which will let us view and sort our file versions in new ways.
First, let's set up the work another developer might do when you're both working on the same files.
- Select File | Reopen. Choose
newcvs/seconddir/thisproject.jpx
.
- Double-click
Application1.java
in the project pane to open it in the content pane.
- Type // fourth change under the first line of code:
- Select Team | CVS Commit "Application1.java". Type
fourth change made
when prompted for a comment. Click OK.
- Click OK or press Enter to return to the AppBrowser.
- Open
thisproject.html
in the content pane and choose the Source file view tab.
- The bottom right corner of the content pane tells you the row and column number of your cursor position.
- Add a line under row 21 and type <LI>Item 3 in row 22.
- Select Team | CVS Commit "thisproject.html". Type
fifth change: line item added
when prompted for a comment. Click OK then click OK or press Enter.
- Close the project.
Make one more change. The purpose of this change is to make the Workspace Diff feature of the Committing Changes dialog available.
- Select File | Reopen and choose
newcvs/firstdir/thisproject.jpx
.
- Double-click
Application1.java
in the project pane to open it in the content pane.
- Type // sixth change in row 5, under the third line of code.
- Save the file but don't commit it.
- Select Team | CVS Project Commit. The Committing Changes dialog box appears:
This was altered for the purposes of illustration. You only see the List of Changes page at first.
Notice that each file's status is noted. Let's see how the Committing Changes dialog box can help manage revisions.
- Click Status to sort the files by status.
- Click Status again and notice that the sort order is reversed.
- Click File Name to sort the files by their names.
- Click File Name again and notice that the sort order is reversed.
- Uncheck
Application1.java
in the Execution column.
- Click the Execution heading to sort by whether a file's status will be changed by committing.
- Check
Application1.java
again.
The List Of Changes page is always available, but only appropriate diff pages are available for any given file. Let's look at this more closely.
- Select
Frame1.java
. Notice the diff tab that remains available.
- Click the Workspace Diff tab. The Workspace Diff page displays the difference between the changed and the unchanged versions of the file in the workspace.
- Return to the List Of Changes page.
- Select
thisproject.html
. Notice the diff tab that becomes available.
- Choose the Repository Diff tab. The Repository Diff page shows the difference between the different file versions on the repository.
- Return to the List Of Changes page.
- Select
Application1.java
. Note how many diff tabs are available. This file was changed both locally and remotely.
- Choose the Diff tab. The Diff page compares the repository version to the workspace version.
Now that we've seen how much else CVS Project Commit can do, let's use it to commit the project.
- Type committing the project in the comment field and click OK. JBuilder automatically performs all outstanding CVS functions.
- Click OK or press Enter to return to the AppBrowser.
- Close the project.
You have seen how you can use Team | CVS Project Commit to view the changes in different versions of your files and to manage some CVS commands for your entire project.
Let's turn our attention to the history view in the content pane.
Lesson 2: Using the history view
The history view provides access to revisions of files even without a third-party version control system in place. This lesson assumes you have installed and configured the CVS version control system. If you haven't, use F1 Help from within any page in the history view to learn what it can do. See "Installing and configuring CVS" for more information about CVS and version control.
The history view has three pages: Contents, Info, and Diff. All three pages have revision tables that list all versions of the active file. JBuilder uses the following icons in the revision tables to distinguish different version control types:
 |
The version of the file that you checked out from the repository. |
 |
A file version under a version control system. |
 |
A backup version of the file. |
 |
The version of the file that's in the buffer. The buffer version includes unsaved changes. |
Tip: You can scroll through the revision lists by pressing Enter or by using your keyboard arrow keys.
We will use the Welcome project in this lesson. You will find it in the samples/welcome
directory of your JBuilder installation.
Step 1: Setting up
- Select File | Open Project and navigate to
Welcome.jpr
in the samples
directory.
- Double-click
Welcome.jpr
to open the project in the AppBrowser. The files WelcomeApp.java
, Welcome.html
and WelcomeFrame.java
show in the content pane.
Configure the connection to point to a local repository. If you started with "Lesson 1: Using CVS in JBuilder," you have already created a local repository and configured a connection to it. If so, create a module for this project named welcomemodule
and skip to "Step 2: Generating multiple versions of a project".
- Type cvs -d :local:[target drive or root]/repo init at the command line and press Enter.
- CVS creates the repository for you and returns you to the command line.
- Return to the AppBrowser.
- Select Team | Configure Version Control.
- Select CVS as your version control system.
- Set your connection type to Local.
- Enter your local repository path in the Module Location area.
- Name the module welcomemodule.
- Accept Autosave Files Before CVS Operations.
Your configuration will look much like this:
- Click OK or press Enter.
- Select Team | CVS Project Create Module.
- Click OK in the CVS Create Module dialog box.
- Enter a comment when prompted and click OK.
Step 2: Generating multiple versions of a file
You have set up your repository, your workspace, and your connection. Now make changes to a file in order to generate different file versions to examine.
- Double-click
WelcomeApp.java
in the project pane if it's not already open and active in the content pane.
- Look at the status bar in the content pane. The two numbers (y:x) tell you the row and column of your present cursor position.
- Press Enter in row 21 to add a line below
package com.borland.samples.welcome;
.
- Type import java.applet.*; in row 22.
- Select Team | CVS Commit "WelcomeApp.java".
- Type a comment for the change and click OK.
- Click OK or press Enter to return to the AppBrowser.
- Scroll down to row 41. It has a line of code that reads
Dimension frameSize = frame.getSize();
.
- Select
frame.getSize();
from the line of code.
- Change
frame.getSize();
to new Dimension(500, 500);
.
- Select Team | CVS Commit "WelcomeApp.java".
Step 3: Using the Contents page
The Contents page displays all the revisions of the file you have selected in the content pane, allows you to sort the files in several ways, and provides access to the Revert and Refresh buttons.
- Choose the History file view tab. The Contents page shows:
Note the information in the status bar: file name, revision number, date and time, and row and column notation.
- Double-click a file version to see the version in the source viewer.
- Click the head of the icon column to sort the versions by revision management type. Notice the different icons for the different types of versions used: local backups, CVS, and working file.
- Click the Label column head to sort the versions by their labels.
Step 4: Using the Info page
The Info page provides access to the comments and labels of all the revisions of a file. You can sort any of its six columns. It also provides access to the Revert and Refresh buttons.
- Choose the Info tab.
Below the revision list you can see the label and comment for the file version selected in the revision list.
- Click a version to see the label and comment for that version.
- Click on the Comment column head in the version list to sort the list by comments.
- Select local backup version number 2.
- Click the Revert button
. The Revert Confirmation dialog box shows. Notice that the reversion does not affect the repository; it only affects your workspace.
- Click Cancel.
Step 5: Using the Diff page
The Diff page shows you the differences between any two versions of the active file and provides access to the Refresh button.
- Choose the History tab to open the history view.
- Choose the Diff tab.
- Click the Rev. heading in the From area to sort the versions by revision number.
- Click the icon column heading in the To area to sort those revisions by their revision management types. Notice that the From area's sorting is unaffected.
- Click the Rev. heading in the To area.
Let's take a look at differences between two versions of a file.
- In the From area, select revision number 1.1.1.1. CVS numbers the first version you check in 1.1.1.1, so this is the very first version.
- In the To area, select the file version with the original repository version icon
.
JBuilder retrieves the differences and displays them in the source viewer:
- In the status area at the bottom, the Diff page tells you how many blocks of differences there are in your comparison.
Tip: To see all changes made to the repository since you started working, select the original repository version in the From area and the file version with the highest revision number in the To area.
- Click the Refresh button
. This retrieves any new versions from the repository. There are none, so your revision list doesn't change.
- Press Alt + n to go to the next block of difference.
- Press Alt + p to go back to the previous block of difference.
- Click the diff arrows on the left of the status bar at the bottom of the Diff page to move from one block to another.
- Close the project.
You have used the Contents, Info, and Diff pages in the history view. You know how to view different file revisions, find and view comments and labels of file revisions, and how to examine differences between various backup, buffer, repository, and workspace versions of a file.
This concludes the tutorial.
For more information about the features of the history view, press F1 on any page in the history view.
For information about CVS in JBuilder, see "Team development using JBuilder."