6 Versioning Applications with Source Control

This chapter describes how to use source control systems to manage the versions of applications developed in a team environment. It discusses the available version control systems, how to download the various version-control extensions available to Oracle JDeveloper, and then includes instructions for each of the source control systems that can be used with JDeveloper.

This chapter includes the following sections:

6.1 About Versioning Applications with Source Control

Developing in teams often requires coordination among multiple developers who may be called upon to make changes to the same files, to track these changes against project management or bug reporting systems, and eventually to check in or commit their edited files to a commonly used repository of content that will be built into a functioning product.

To assist in team development of software products, JDeveloper integrates two popular version control systems, Subversion and Git, into its available feature set. You can access a number of commands for Subversion and Git directly from the JDeveloper interface, through the Team menu or through the Versions window.

For users familiar with other versioning systems, or whose teams use other versioning systems than Subversion, JDeveloper provides downloadable extensions that give you access to the following:

  • Concurrent Version System (CVS)

  • Perforce

  • Rational ClearCase

  • Microsoft Team System

To download these extensions, select Help > Check for Updates. Once downloaded, you will be able to access these version control systems from the Versions window and the Team menu.

6.2 Downloading Source Control Extensions in Oracle JDeveloper

JDeveloper offers a number of tools for developing in teams. These include an integrated solution, Subversion, as well as a selection of extensions that interface JDeveloper with popular version control systems. In addition, an application lifecycle management system, Oracle Team Productivity Center, is also available as a downloadable extension.

While most members of a team will interact with their selected versioning system by checking files in and out and managing their changes to the project they are working on, at least one team member is typically required to administer and maintain the versioning system as it relates to JDeveloper. If you are the administrator for your versioning system, you will most likely have additional tasks beyond checking files in and out.

If your team uses one of the versioning systems that require you to download a JDeveloper Extension to integrate your versioning system with JDeveloper, you can browse for the versioning system from the Update Center by selecting Help > Check for Updates. Be sure to select all update centers when you search for your versioning system.

6.3 Setting Up and Configuring Source Control

In addition to the popular team development solution Subversion (SVN), JDeveloper supports a number of other version control software packages. These additional packages are available as extensions to JDeveloper and can be downloaded by selecting Help > Check for Updates. Instructions for configuring each of these extension-based version control systems are included here.

6.3.1 How to Set Up Subversion and JDeveloper

JDeveloper is integrated with the popular team development solution Subversion (SVN). If you are part of a team that uses Subversion, JDeveloper's Team menu contains commands for using Subversion to manage the content you are working on while maintaining a connection to your team's repository and tracking changes, merges, and more. Setting up Subversion involves creating a repository for your source-controlled files, making sure that JDeveloper can connect to that repository, importing files to the repository, and more.

In general, you begin by importing your working files into the Subversion repository to bring them under version control.Once in the repository, your files are then available to be checked out from the Subversion repository to a local folder known as the "Subversion working copy." When you create a new file in JDeveloper (or move it into JDeveloper), you store it in the Subversion working copy. When you are ready to make your work available to the team, you add these new files to Subversion control. When it comes time to make your changed and new files available to other users, you can do so by committing them to the Subversion repository. To take advantage of the work others on your team have done, you can copy changed files from the Subversion repository to your working copy by updating your files.

After completing setup, your work with Subversion will revolve around checking files out, editing them in JDeveloper, and checking them in with your changes. You may also need to resolve conflicts between changes you made and those made by others in your team. Files may also be moved in and out of Subversion control, and finally, you might use special properties of the files associated with specific versions for tracking bugs, customer requests, and other characteristics.

6.3.1.1 Installing Subversion Client Software

In addition to creating a repository for your source-controlled files, making sure that JDeveloper can connect to that repository, and importing files to the repository, it may be necessary to install Subversion client software under the following circumstances:

  • You wish to create a local Subversion repository using the JDeveloper Subversion VCS extension.

  • You wish to use a Java binding (helper library) other than SVNKit, which is the one supplied with the extension.

  • You wish to connect to a Subversion repository through a proxy server

In all of the above cases, you will need to install separate Subversion client software. If you wish to use an alternate Java binding, you will additionally have to install the binding software.

To Install Subversion Client Software: 

  1. Download the Subversion installer (svn-1.7.8-setup.exe) from http://subversion.apache.org/ (to, for example, c:\downloads).

  2. Run the installer and place the Subversion client in a convenient location, for example c:\subversion. Reboot your computer.

This procedure assumes that the operating system is Windows. For non-Windows environments, consult the documentation for the operating system package management system to ensure the vendor-supplied Subversion client contains JavaHL.

To check the installation so far, open a command prompt and type svn help. You should see a list of subcommands. If not, check that the system path contains the bin directory of the location where the client software was installed (in this example, c:\subversion\bin).

6.3.1.2 Checking the Subversion Client Installation

Once you have completed installing the Subversion client software,

To Check the Installation: 

  1. In JDeveloper, select Subversion as the versioning system (Team > Configure, and then select Subversion).

  2. Open the main Subversion preferences page (Tools > Preferences > Versioning), and then check that the required client installation is available. If more than one is listed, select the one that you wish to use.

Important: If you subsequently accept an update of the JDeveloper Subversion extension from the Update Center (Official Oracle Extensions and Updates), the client preference will be reset to SVNKit, even if you had previously chosen an alternate client.

6.3.1.3 Creating a Subversion Connection

Before you can work with a Subversion repository through JDeveloper, you must create a connection to it. You can subsequently edit the connection details if they change for any reason.

Typically, you will obtain the details of your Subversion connection (server name, user ID, password, etc.) from your team or version control administrator. You will need to know those details before you create a connection to your Subversion repository.

To Create a Subversion Connection: 

  1. In the Versions window (Team > Versions), right-click the Subversion node and choose New Repository Connection.

    The Create Subversion Connection dialog is opened. For help when using this dialog, press F1 or click Help.

  2. Enter the URL of the location of the Subversion repository.

  3. Optionally, enter a name for the connection.

  4. If the Subversion repository has been set up with password protection, enter the username and password.

  5. If you want to test the connection to the Subversion repository, click the Test Connection button. The results will be displayed in the Status area.

  6. To complete the connection, click OK.

6.3.1.4 Editing a Subversion Connection

If any of the details (such as IP address, port, user ID, password, etc.) of your Subversion connection change, you can edit the connection in JDeveloper so that you can connect to it with the new details.

To Edit a Subversion Connection: 

  1. In the Subversion Navigator (Team > Versions), right-click the Subversion connection name and choose Properties.

    The Edit Subversion Connection dialog is opened. For help when using this dialog, press F1 or click Help.

  2. Make changes as required and click OK.

6.3.1.5 Exporting Subversion Repository Connection Details

You can export the details of your Subversion repository connections to a file. You can subsequently import the connection details from the file to recreate the Subversion repository connections. This can greatly simplify the process of connecting to a Subversion repository as new team members join, as the repository connection file can be stored on a server accessible to the team, then downloaded as required as new members join. Similarly, if new servers are added, the team leader or administrator can distribute new connection information in a connection detail file to be imported by all team members.

To export Subversion connection details to a file: 

  1. In the Subversion Navigator, select the Subversion node and, from the context menu, choose Export Connections.

    The Export Subversion Connections dialog opens.

  2. Enter a location and name for the file that will contain the connection details, then click OK.

6.3.1.6 Importing Subversion Repository Connection Details

If you or your team have saved the details of your Subversion repository connection, you can import them into JDeveloper to simplify making the connection to your repository.

To import Subversion connection details from a file: 

  1. In the Subversion Navigator, select the Subversion node and, from the context menu, choose Import Connections.

    The Import Subversion Connections dialog opens.

  2. Browse to the file that contains the connection details that you wish to import, then click OK.

6.3.1.7 Connecting to a Subversion Repository Through a Proxy Server

If you wish to connect to a Subversion repository through a proxy server, you must first install separate Subversion client software.

Once you have installed the Subversion client software, you will have a Subversion subdirectory in your Windows Application Data directory. To find the Application Data directory, at the c:/ prompt type cd %APPDATA%. Then open the Subversion subdirectory. (On Linux, the equivalent subdirectory will be in ~/.subversion, where ~ is the home directory.)

Note:

If you have entered the proxy settings in the JDeveloper Preferences, you can omit editing the servers file as described in the following paragraphs.

In the Subversion subdirectory will be a file named servers. Open this file with a text editor and find the [global] section. Remove the comment marker (#) from the line http-proxy-host and overtype the placeholder proxy information with the details of the proxy server that you use. Remove the comment marker (#) from the line http-proxy-port and overtype the placeholder port information with the port number for the proxy server. If you wish to exclude certain URLs from using the proxy server, remove the comment marker (#) from the line http-proxy-exceptions and overtype the placeholder URLs with URLs that you wish to exclude.

Add additional http-proxy-host and http-proxy-port lines with details of any other proxy servers that you use.

It is important that the proxy server supports all the http methods used by Subversion. Some proxy servers do not support the following methods by default: PROPFIND, REPORT, MERGE, MKACTIVITY, CHECKOUT. If you experience problems with using a proxy server to access a Subversion repository, ask the server's system administrator to change the configuration to support these http methods.

6.3.1.8 Exporting Subversion Controlled Files from the Working Copy

You can export copies of JDeveloper files that are under Subversion control from either of two places: the Applications window, in which case the files will be exported from the Subversion ”working copy”, or the Subversion Navigator, in which case the files will be exported from the Subversion repository. Exporting the files means copying them to a local file system directory that you specify.

To export files from the Applications window: 

  1. In the Applications window, select the project containing the files that you wish to export.

  2. Select Team > Export Files.

    An Export Files dialog opens.

  3. In the Destination Path box, enter or browse to the location where you want the files to be copied to.

  4. To export the files, click OK.

This exports the selected files from the Subversion "working copy" the your local file system.

6.3.1.9 Exporting Files from the Subversion Navigator

You can export copies of files under Subversion control from the Subversion Navigator. This ensures that the files will be exported from the Subversion repository (not from the "working copy"). In addition, exporting with the Subversion Navigator lets you specify which revision of the files to export.

To export files from the Subversion Navigator: 

  1. In the Subversion Navigator, select the repository node or directory containing the files that you wish to export.

  2. Select Team > Export Files.

    An Export Files dialog opens.

  3. In the Destination Path box, enter or browse to the location where you want the files to be copied to.

  4. If you want to export a particular revision of the files, select Use Revision and enter the revision number in the adjacent text box.

  5. To export the files, click OK.

This exports the selected files from the repository to your local file system.

6.3.2 How to Set Up and Configure a Git Repository

Git is a popular open-source version control system with a growing user community. To begin using Git with JDeveloper, you create a clone of your team's repository on your local system.

To complete this procedure, you will need the following information, which should be available from the Git administrator on your team:

  • The name of the repository

  • The URL at which the repository is stored

  • The user name and password you will use for accessing the repository. Optionally, your team may use a private key file with a passphrase; you can select the appropriate option for your team when you connect to Git.

  • The name of the remote branch that your team uses for development.

  • The destination pathname in your local system to which you wish to store your local repository.

To connect to Git:

  1. Select Team > Connect to Git. This displays the Clone from Git wizard welcome screen. Click Next to continue.

  2. Enter the information about your team's remote Git repository, then click Next to continue.

  3. Specify the remote branch your team uses for development, then click Next to continue.

  4. Specify the pathname on your local system at which you wish to create your local repository, then click Next to continue.

  5. Verify all the information displayed in the Git Clone Summary screen, then click OK.

JDeveloper connects you to the remote repository and creates a local clone based on the branch you selected. From this local clone you can check out, edit, merge, and commit files to the main repository.

6.3.3 How to Set Up CVS with Oracle JDeveloper

In general, CVS uses a common repository of files, accessible to JDeveloper, that you and your team share while developing a software project. To modify files in that repository, you first check them out so that CVS tracks the who, when, and what of file access. In the event that two team members edit the same file at the same time, CVS contains tools that help you determine whether those changes conflict, and to resolve problems that may arise and merge these simultaneous changes into a single, comprehensive file. Finally, CVS lets you check these changed files back into the repository so that your build tools will have access to the latest files, with new and/or merged content.

Note:

For extensive information about how to use and administer CVS, see the CVS online manual at http://www.cvshome.org.

Before you can use CVS to manage your shared content, you need to connect JDeveloper to CVS. This means configuring JDeveloper, making a connection to your team's CVS repository, creating a local repository, and more. The topics in this section cover all the steps you'll need to make sure CVS is available from JDeveloper after downloading the CVS extension from Check For Updates. If your team is already using CVS, you should check with them for specifics on how CVS is implemented in your organization.

The process of setting up CVS with JDeveloper involves configuring JDeveloper, creating a CVS connection, importing files for the project into your CVS repository, and then checking out the CVS modules to be edited.

6.3.3.1 Configuring CVS for Use with JDeveloper

Before you can use CVS, you need to configure JDeveloper by setting preferences.

To configure JDeveloper for use with CVS: 

  1. Choose Tools > Preferences, then select Versions from the left panel of the Preferences dialog.

  2. In the right panel, click Load Extension. The main CVS preferences panel is shown. Other CVS preferences panels are shown when you click on the items beneath the CVS node.

  3. Make changes to the preferences as required. For more information about the specific preferences, press F1 or click Help.

  4. Click OK to close the Preferences dialog.

6.3.3.2 Creating a CVS Connection

Once you have installed the CVS extension in JDeveloper, you must create a connection to CVS before you can access the repository. You can create a CVS connection by

To create a CVS connection: 

  1. Select Team > CVS > Check Out Module.

    JDeveloper prompts you to create a CVS connection. Click OK to open the Create CVS Connection wizard.

  2. Complete the Create CVS Connection wizard.

    For help when using the wizard, press F1 or click Help.

6.3.3.3 Editing a CVS Connection

If any of the connection details change after creation, you can edit the CVS connection as follows.

To edit a CVS connection: 

  1. In the CVS Navigator (View > CVS Navigator) right-click the connection name and choose Properties.

    The Edit CVS Connection wizard is opened.

  2. Use the wizard to make changes as required.

    For help when using this wizard, press F1 or click Help.

6.3.3.4 Exporting a CVS Module

You use the CVS Export wizard to export the revisions of files for a module, creating a deployment-ready file structure.

To use the CVS Export wizard: 

  1. Choose Team > CVS > Export Module. The CVS Export wizard is displayed.

  2. Complete the export as prompted by the wizard. To obtain more information when working with the wizard, F1 or click Help.

The files are exported to the location you have specified.

6.3.3.5 Copying the CVSROOT Path to the Clipboard

You can copy the path of the CVSROOT from a node in the CVS Navigator to the Clipboard, for use in other applications.

To copy the CVSROOT path to the Clipboard: 

  1. In the Connection Navigator, right click the connection name.

  2. From the context menu, choose Copy CVSROOT.

The full path of the CVSROOT is copied to the Clipboard, from where you can paste it into another application.

6.3.4 How to Configure CVS For Use with JDeveloper

In addition to setting up JDeveloper to be able to use CVS, there are certain tasks you need to perform to make CVS usable with JDeveloper. Some of these tasks may be performed by your administrator. You should always check to make sure which of these tasks have been performed in your installation.

In general, you need a local CVS repository for storing files as you are working on them. You may also need to configure a secure shell (SSH) for communicating with CVS, and you may need to choose a character set. Finally, you will need to log in to CVS.

6.3.4.1 Choosing a Character Set (Local Client Only)

If your installation uses a local CVS client, you need to choose a character set.

For each CVS repository connection, you can choose the character set to be used for the encoding of files. The default is to use the character set specified by the platform/operating system.

You can change to the IDE default or to a specific character set through the Set Encoding dialog.

To choose a character set:. 

  1. Select a connection in the CVS Navigator.

  2. Clicking the right mouse button and choose Set Encoding.

  3. Select the desired character set.

6.3.5 How to Set Up Perforce with JDeveloper

Before using Perforce with JDeveloper, in addition to downloading the Perforce extension, you need to install a number of Perforce features so that they are available to JDeveloper. Once installed, you configure JDeveloper and connect to the Perforce client workspace. Finally, you need to bring your working files under Perforce control so that they are available from within JDeveloper while using Perforce.

There must be at least one Perforce server installed, on a machine that is accessible to the intended JDeveloper users. If a Perforce server installation does not already exist, obtain the necessary software (for example, from www.perforce.com) and install it in accordance with Perforce's instructions. Record the identity of the machine on which the Perforce server software has been installed: you will need this when you connect to it through JDeveloper.

Before using Perforce with JDeveloper, in addition to downloading the Perforce extension, you need to install a number of Perforce features so that they are available to JDeveloper. Once installed, you configure JDeveloper and connect to the Perforce client workspace. Finally, you need to bring your working files under Perforce control so that they are available from within JDeveloper while using Perforce.

6.3.5.1 Installing Perforce Components for Use with JDeveloper

There must be at least one Perforce server installed, on a machine that is accessible to the intended JDeveloper users. If a Perforce server installation does not already exist, obtain the necessary software (for example, from www.perforce.com) and install it in accordance with Perforce's instructions.

Perforce Client Installation

You must install the Perforce client application on the machines that contain (or that will contain) JDeveloper. The Perforce client application can be installed from the same software as the server software, obtainable from www.perforce.com. The installation must include the ”Command Line Client (P4)”.

When you first run the Perforce client application, you will be required to create a Perforce client workspace. The Perforce client workspace is where the working copies of files under Perforce control will be stored. You can use the JDeveloper default directory as the Perforce client workspace, whether or not it already contains JDeveloper files. The JDeveloper default directory is <installation_directory>\jdev\mywork. Alternatively, you can accept the default Perforce client workspace, or specify one of your own. In these cases, you should note the location you have used, because you will need to specify it when creating applications and projects in JDeveloper.

If you set up passwords in the Perforce client application, you will also need to use them when connecting to Perforce through JDeveloper.

JDeveloper Installation

JDeveloper must be installed in the normal way. Each installation of JDeveloper can act as a client application for Perforce. You can install JDeveloper on every machine that you wish to be a Perforce client, or you can use a mixture of JDeveloper installations and Perforce's own client applications. The JDeveloper and Perforce client applications will work together in a seamless manner. In addition to the JDeveloper embedded support for Perforce, you will also be able to access a Perforce client application through the JDeveloper interface.

6.3.5.2 Configuring JDeveloper for Use with Perforce

Before you can configure JDeveloper to use Perforce, you must have installed the Perforce server and client software.

To configure JDeveloper for use with Perforce: 

  1. Choose Tools > Preferences > Versioning > Perforce. C

  2. Verify that the path to the Perforce client is as you installed it.

  3. If your team uses comment templates, select Comment Templates from the left-hand pane and configure your team's comment templates. More

  4. In the left pane of the Preferences dialog, select General, then make selections about icons, log messages, opening files automatically for edit, and the length of the idle period before timeout. More

  5. In the left pane of the Preferences dialog, select General, then make selections about the Pending Changes window and the Merge Editor. More.

  6. To save the configuration you have just set up, click OK to close the Preferences dialog.

6.3.5.3 Selecting Perforce as the Version System

Once you have configured JDeveloper for use with Perforce, you can select Perforce as the version system. This will specify a number of default settings which mean that all team operations will default to Perforce as your chosen version system.

To select Perforce as the version system:

  • Choose Team > Perforce.

You can change this default selection at any time if your team changes to a different version system at a later date.

6.3.6 How to Configure JDeveloper to Use Rational ClearCase

JDeveloper allows you to use the source control features of Rational ClearCase release 4.0 onwards (including ClearCase 2002). JDeveloper works in a seamless manner with ClearCase so that once you have it configured you can add files to source control, and check them in and out from the Applications windows

The JDeveloper Rational ClearCase extension allows you to use the source control features of Rational ClearCase inside JDeveloper. Once you have JDeveloper configured to work with your ClearCase installation, you can add files to source control, and check them in and out from the Applications windows.

To work in ClearCase, you have to store your workspaces, projects and files on your ClearCase view; before new projects and files are under ClearCase source control, you have to explicitly add them to ClearCase. Once your files are added to your ClearCase view, you can check them in and out, compare versions, review file histories, and (if necessary) remove files from ClearCase.

To use ClearCase with JDeveloper, you must have ClearCase 4.0 or greater client installed on the same machine as JDeveloper.

To configure JDeveloper to use ClearCase: 

  1. Select Tools > Preferences >Versioning > ClearCase. The first time you select this on a new installation of JDeveloper, click Load Extension to display the ClearCase preferences pages.

  2. On the first ClearCase page, select whether or not to connect automatically on startup. More

  3. Select the General page of the ClearCase versioning preferences to specify whether to display navigator overlay icons, whether to check files out automatically, and to specify a checkout comment. You can also set the timeout period. More

  4. Select the Version Tools page of the ClearCase versioning preferences to specify when to display the check in dialog (always, when comments are hidden, or never). More

  5. Save your configuration and close the Preferences dialog by clicking OK.

If you have not chosen (in the preferences) to have connections made automatically, make sure that you have a connection to the ClearCase server, then select Team > ClearCase > Connect to ClearCase.

Now that you have configured JDeveloper to work with ClearCase, you can access files and folders that already exist in a mounted ClearCase view. New files and folders must be created in or copied to your ClearCase view.

6.3.7 How to Set Up Team System and JDeveloper

Oracle JDeveloper's Team System extension allows you to use the source control features of Microsoft Visual Team System inside JDeveloper. Once you have JDeveloper configured to work with Team System, you can add files to source control, and check them in and out from the Applications windows.

To begin using Team System with JDeveloper, you must first create a workspace using Team System software, and then populate this workspace with content from the Team System server. Files are checked out to the workspace, where they can be worked on. Files newly created within JDeveloper must be added to version control. Changed and new files are made available to other users by checking them in to the Team System server.

Before beginning to use Team System with JDeveloper, there are some initial steps you need to follow:

  1. Set up the Team System client software. See Section 6.3.7.1, "Setting Up Team System for Use with JDeveloper."

  2. Configure JDeveloper for use with Team System, including the preferences and other settings for making Team System the source control system recognized by JDeveloper. See Section 6.3.7.2, "Configuring JDeveloper for Use with Team System."

In practice, Team System (like any version control system) consists of operations that you use at varying times depending on the place in the product lifecycle. For example, if you create a new file, you'll need to add it to Team System control. Other operations you may perform, depending on the stage of development, include:

6.3.7.1 Setting Up Team System for Use with JDeveloper

Using Team System with JDeveloper requires a setup procedure that includes installing software, connecting to your server, and populating your workspace.

To set up Team System with JDeveloper:

  1. Install the Team System server.

  2. Install the Team System client software.

  3. Connect the Team System client software to the Team System server.

  4. Use the Team System client software to create one or more workspaces.

  5. Use the Team System client software to populate the workspace(s) with content from the Team System server.

Instructions for doing the above are given in the Team System online help.

6.3.7.2 Configuring JDeveloper for Use with Team System

Once you have set up Team System for use with Oracle JDeveloper, you are ready to configure JDeveloper to use Team System. In addition to the steps in Section 6.3.7.1, "Setting Up Team System for Use with JDeveloper," make sure you have already installed the JDeveloper Team System VCS extension (from the Official Oracle Extensions and Updates center).

To configure JDeveloper for use with Team System, carry out the following activities in JDeveloper:

  • Connect to Team System as the JDeveloper versioning system.

  • Set the workspace to use with JDeveloper.

  • Create a JDeveloper project to hold the workspace files.

  • Refresh the workspace folders in JDeveloper.

6.3.7.3 Selecting Team System as the Versioning System

Connecting to Team System as the default versioning system specifies that Team System is the target for a number of actions from the Team menu.

To connect Team System as the versioning system: 

  • Choose Team > Connect to Team System.

This displays the Team System connection menu, from which you can select the available operations. Detailed instructions for this are given in the Team System online help.

6.3.7.4 Setting the Team System Workspace to use JDeveloper

Before beginning, you need to set your selected Team System workspace to use JDeveloper.

To set the workspace to use with JDeveloper: 

  1. Choose Team > Team System > Set Workspace.

  2. Select the required workspace from the list.

6.3.7.5 Creating a JDeveloper Project for the Workspace Files

Associating the JDeveloper project with the selected Team System workspace ensures that the files you create and edit will remain part of the workspace your team is using.

To create a JDeveloper project to hold the workspace files: 

  1. Select File > New to open the New Gallery.

  2. Use the New Gallery to create a new application and project.

  3. In the Applications window, select the newly created project and click the Add to Project Content button in the toolbar.

    This opens the Project Content page of the Project Properties dialog.

  4. Use the Add button in the Java Content area to add the location of the workspace.

    If your workspace contained Java sources, a dialog is displayed through which you should confirm that you want the sources added to the project content.

    To avoid confusion, you may wish to remove non-workspace locations from the Java Content list.

  5. Click OK to close the Project Properties dialog.

Once completed, refresh the workspace folders in JDeveloper by choosing Team > Refresh Workspace Folders.

6.3.7.6 Getting Versions of Files from the Team System Server

JDeveloper lets you get (from the Team System server) a version of a file that is in the Applications window. You must previously have used the get command in the Team System client software to populate your workspace with source files.

You can use this procedure to obtain the following versions of files: the latest version; files from a previously saved named changelist; files with a particular date stamp; files from a previously created named label; files from a particular workspace version.

The version obtained from the Team System server will replace the version currently in the Applications window.

To get versions of files from the Team System server: 

  1. In the Applications window, select the application, project or files to set the scope of the Get operation.

  2. Select Team > Team System > Get.

    The Get dialog is opened.

  3. Complete the dialog.

    For information while using the dialog, press F1.

6.3.7.7 Adding FIles to Team System Control

Use to bring files under Team System source control. The files will be added to the Team System server and made available to other users when you next check in the file.

To add files to Team System Control: 

  1. In the Applications window, select the file that you want to add to Team System control.

  2. Select Team > Add.

    The Add dialog is opened.

  3. Complete the dialog.

    For information while using the dialog, press F1.

  4. To add the file to the server and make it available to other users, check in the file.

6.4 Setting Up and Configuring a Source Repository

After initializing your version control system in JDeveloper, the next important step is to configure the source repository. Typically, you maintain a local repository, containing local copies of the files you are working with, on your own system. You typically check out the files you want to work on, make edits to the versions on your local system, and then check the files back in to the remote repository. Your version control system typically tracks, or at least notifies you of, changes and conflicts if more than one person is editing a file at a time. The menu options and details vary from system to system; these variations are described individually in each of the following sections.

Before beginning to use Subversion with JDeveloper, you will need to load your repository with content so that you have local versions to edit. For more information, see Section 6.4.4, "How to Load the Repository with Content."

6.4.1 How to Create a Source Repository

Creating a repository is something you typically only do once per project/release; once you have created the repository, you check files in and out as part of your daily work routine. In many teams, the source repository is created by a team member assigned to the role of administrator for the repository; if this is the case, you may be able to skip this section and rely instead on accessing the existing source repository for checking out and checking in files.

The details of creating and connecting to your source repository differ depending on the versioning software your team uses. The following sections include instructions on creating source repositories for the versioning systems available to JDeveloper.

6.4.1.1 Creating a Subversion Repository

In most cases, you will connect to your team's Subversion repository. As you develop your projects and applications, you will check files out from the Subversion repository, modify them, and check them back in. This is the typical, and recommended, practice for using Subversion.

Depending on your installation, however, you may find it necessary to create a Subversion repository on your local file system through JDeveloper. A connection to the repository will be created at the same time.

JDeveloper will try to use the file:/// protocol to access the newly created repository. SVNKit, the Subversion client installed with JDeveloper, supports the file:/// protocol. If you are using a Subversion client that does not support the file:/// protocol, you will need to use a different access method (http://, https://, svn:// or svn+ssh://). Consult the Subversion documentation for how to do this.

To Create a Subversion Repository: 

  1. Choose Team > Create Local Repository.

    If your installation does not support local repository creation, you will see an error message. Otherwise, the Create Subversion Repository dialog will open.

  2. Complete the Create Subversion Repository dialog.

    To obtain help while using the dialog, press F1 or click Help.

To Browse a Subversion Repository: 

  1. Expand the connection to your Subversion repository in the Versions window.

  2. Double-click on a folder to view its contents.

  3. Right-click on an element to view available operations.

6.4.1.2 Initializing a New Git Repository

If you have new files that are not already part of any existing Git repository, you need to initialize a Git repository.

You initialize a Git repository when you have a new project with all new files. This is typically done once per project, at the beginning. As an ongoing task, you are more likely to add new files to an existing Git repository (link), or check out files, edit them, and then commit the changes back to the Git repository (link).

To initialize a Git repository:

  1. Select Team > Git > Initialize. This displays the Initialize Repository dialog.

  2. Enter the path to the local repository, then click OK.

6.4.1.3 Making a Local Copy of an Existing Git Repository

If your team already has a central Git repository and you wish to make a local copy of it for your work, you can clone the Git repository as described here.

To clone a Git repository:

  • Select Team > Git > Clone.

This opens the Clone from Git Wizard. Enter the information requested on each screen. You can press F1 or click Help at any time for more information.

6.4.1.4 Adding New Files to an Existing Git Repository

Adding new files to an existing Git repository involves selecting, then adding the files, and finally committing them for the changes to be incorporated into the repository.

To add new files to an existing Git repository:

  1. Select the files to be added. You can do this either in the

  2. Select Team > Git > Add (or Team > Git > Add All). This displays the Add dialog.

  3. Click OK.

6.4.1.5 Creating a Local CVS Repository

From within JDeveloper, you can create a new CVS repository on your local file system. This feature is available only if you are using external CVS client software, rather than the internal CVS client installed as part of the CVS extension to JDeveloper.

To create a local CVS repository: 

  1. Select Team > CVS > Create Local Repository.

  2. In the Repository Folder box, enter the path of a directory where you want the new local repository to be created.

    You can specify or select an existing directory if it is empty, or you can specify a new directory. If the directory you have specified exists and is not empty, you will see a warning dialog telling you to specify an empty or new directory for the repository.

  3. If you want to create a connection to the local repository that you are creating, make sure that the Create Repository Connection box is checked.

    The connection will be given a name in the form :local:{path}. If you later want to change this name, you can do so through the CVS Navigator: from the context menu of the connection name, open the properties dialog and, on the Name tab, overtype the existing name with a new one.

  4. Click OK. You will see a confirmation dialog when the new local repository has been created.

6.4.1.6 Importing JDeveloper Project Files Into CVS

Before you can start using your JDeveloper project with CVS, you have to import the project files into the CVS repository. This copies all your folders and files to the CVS repository and places them under source control.

You import your project files into the CVS repository using the Import to CVS wizard.

To use the Import to CVS wizard: 

  1. Choose Team > CVS > Import Module. The Import to CVS wizard is displayed.

  2. Complete the import as prompted by the wizard. For help when using this wizard, press F1 or click Help.

Before you can change any files, you have to copy them back to your machine, where you can work on them locally.

6.4.1.7 Bringing Files Under Perforce Control

Perforce uses a local directory structure to receive files that are going to be placed under formal source control. This location is called the ”Perforce client workspace”. Files created in (or moved into) JDeveloper must be stored in this location. Once files are in your Perforce client workspace, you bring them fully under source control by submitting them to a central location called the ”Perforce depot”. Files must be submitted to the Perforce depot before they can be versioned and accessed by other users.

Files that you create within JDeveloper, or files that you bring into JDeveloper from outside, must be brought under Perforce control before you can use the JDeveloper Perforce versioning facilities with them.

If you have an existing JDeveloper project that you wish to bring under Perforce control, use the Import to Perforce wizard.

To put individual JDeveloper files under Perforce control: 

  1. Select the files in the Applications window and choose Team > Perforce > Open for Add.

    The files can be your work files, or they can be the application and project files used by JDeveloper.

    The Add Files to Perforce dialog is displayed with the files listed.

  2. If you wish to lock the files, making them unavailable to others for editing, check the Lock Files box.

  3. To add the files to Perforce control, click OK.

    The files are now shown in the Applications window with a red cross, meaning that they are stored in your Perforce client workspace but not yet in the Perforce depot. Files must be added to the Perforce depot before they can be versioned and accessed by other users.

  4. To add files to the Perforce depot, select the files in the Applications window and choose Team > Perforce > Submit.

    The Submit Files dialog is displayed with the files listed.

  5. Add your versioning comments in the Comments box.

    You will later be able to see these comments when viewing the list of versions of a particular file.

  6. To submit the files to the Perforce depot, click OK.

    The files are now shown in the Applications window with a green dot, indicating that they are known to the Perforce depot and are up to date.

To bring files created outside JDeveloper under Perforce control: 

  1. Copy or move the files into an existing \src directory under the JDeveloper file storage directory (which should be the same as the Perforce client workspace).

  2. Refresh the application or project.

    The files should now appear in the Applications window, within the project whose \src directory you used. The files are marked with a white-on-blue diagonal cross, showing that they are known to JDeveloper but not under source control.

  3. Bring the files under Perforce control as described in the previous procedure.

6.4.1.8 Adding a File to ClearCase

To work in ClearCase, you have to store your workspaces, projects and files on your ClearCase view, and before new projects and files are under ClearCase source control, you have to explicitly add them to ClearCase. The comment pane in the Add to ClearCase dialog allows you to build up comments for different groups of files. The comments you type apply to the files you have selected. For example, you can select all the files and type a global comment. Next, select a smaller number of files. The first comment is displayed and you can add to it. Then you can select just a single file in this group and add another comment specific to that file.

To add one or more files to ClearCase: 

  1. Select the files in the Applications window, and choose Team > Add. The Add to ClearCase dialog is displayed, listing the items you have selected.

    If you want to continue working on the files, leave the Check In box clear. If you check the box, the files will be checked in and you must check them out when you want to work on them.

  2. To add the files in the list to ClearCase source control, click OK. You may see one or more messages asking whether you should add folders to ClearCase. Click Yes.

6.4.2 How to Connect to a Source Control Repository

Once the source control repository has been created (either by you or by a team administrator), you typically connect to it from the Team menu, then selecting your versioning system from the Connect To... option. The following sections outline some of the specifics of connecting to your source control repository.

6.4.2.1 Viewing Subversion Repository Content

You can view the current content of the Subversion repository through the Versions window. The nodes under your selected Subversion connection unfold to reveal the structure and file content of the Subversion repository.

You can open a read-only version of a Subversion repository file by choosing Open from its context menu. This will let you see what changes have been made to the files in the Subversion repository since you checked out or updated your local versions.

Folders in the Subversion repository, visible from the Versions window, offer the following operations:

New

Opens the new gallery, from which you can create applications, connections, projects, and other entities.

New Remote Directory

Opens the Create Directory dialog, which lets you create a new directory to associate with the URL of the element on which you right-clicked.

Delete

Removes the selected element immediately from the JDeveloper view, without a confirmation dialog. Use with caution.

Check Out

By default, opens the Check Out from Subversion dialog.

If you have configured JDeveloper for a different version control system, Check Out will open the checkout dialog for your selected version control software.

6.4.2.2 Logging In to CVS

Some types of connection to a CVS repository require you to log in independently of making the connection. If you cannot access any CVS features even though a CVS connection exists, you need to log in.

To log in to a CVS repository: 

  1. In the CVS Navigator, select Team > Log In.

    If the Log In menu option is unavailable but the Log Out option is available, you are already logged in.

  2. In the Log In To CVS dialog, enter your password. If you want your password to be remembered and supplied automatically when you connect to the CVS repository in future, check the Connect Automatically on Startup box.

  3. Complete login by clicking OK.

6.4.2.3 Accessing Local Files with CVS

If JDeveloper finds a path to a CVS client on your machine, the JDeveloper CVS preferences will by default be set to use that CVS client (rather than the internal CVS client installed with JDeveloper). If no path to a CVS client is found, the preferences will be set to use the internal CVS client.

The internal CVS client cannot be used to access a local CVS repository (that is, one on your own machine). If you wish to access a local CVS repository, you must install a full client/server version of CVS onto your machine and set the JDeveloper CVS preferences accordingly.

If you wish to use an external CVS client, we recommend the following:

Note:

You may already have a CVS installation that is client-only. This will not be able to access a local CVS repository, and you should install a full client/server version instead. If you are unable to expand the connections node in the CVS Navigator or open the list of modules from the Get Module List button in the CVS wizards, you probably have client-only CVS software that is attempting to access a local CVS repository. You can check which type of CVS installation you have by typing cvs -v at the CVS command prompt. A client-only installation will display (client) at the end of the version information line, whereas a client/server installation will display (client/server).

To access CVS through a firewall: 

If you are accessing a CVS server through a firewall, you can connect to it if:

  • the firewall allows TCP/IP communication on the CVS port, or

  • you use a CVS client that supports HTTP Tunneling (for example, CVSNT).

If there is an authentication failure when you log in, try using the CVS command line to connect. If this fails, the connection may be being blocked by the firewall, and you should contact your network administrator.

If necessary, you can alter the value of the CVS root variable to support connection through a firewall.

6.4.2.3.1 Handling CVS File Types

The CVS administrator has to configure the CVS repository for the automatic handling of binary files produced by JDeveloper, such as image file formats.

Where other file types are updated, CVS attempts to merge them. If you do not want is to occur, you must change the configuration of the CVS repository.

For more information about CVS, refer to the CVS documentation, or see the CVS website, http://www.cvshome.org. This is also where you can download CVS software.

6.4.2.4 Connecting to Perforce

Before Perforce operations become available within JDeveloper, you must connect to Perforce.

To connect to Perforce manually: 

  1. Choose Team > Connect to Perforce.

    The Connection dialog is opened. The username, port and client information should have been derived automatically and should now appear in the Connection dialog.

  2. If not already present, enter the correct username, port and client information.

  3. If the Perforce server has been set up with password protection, enter the password. (If you want the password to be remembered for the next time you make a connection, check the Remember Password box.)

  4. If you want to test the connection to the Perforce server, click the Test Connection button. The results will be displayed in the rectangular text area.

  5. To complete the connection, click OK.

6.4.2.5 Making Multiple Connections to Perforce

In some development environments, you may need to make more than one connection to Perforce. For example:

  • Your organization uses one Perforce server for development and another Perforce server for test.

  • You wish to connect using two different Perforce clients.

  • You wish to use different Perforce user IDs.

The Perforce extension to JDeveloper permits all these operations. You begin by giving each Perforce connection a name as you create it.

To create a named Perforce connection: 

  1. Choose Team > Connect to Perforce.

    The Connection dialog is opened. The username, port and client information should have been derived automatically and should now appear in the Connection dialog.

  2. If not already present, enter the correct username, port and client information.

  3. Enter a name to use for this Perforce connection. Make sure it is different from any other Perforce connection that you currently have open.

  4. If the Perforce server has been set up with password protection, enter the password. (If you want the password to be remembered for the next time you make a connection, check the Remember Password box.)

  5. If you want to test the connection to the Perforce server, click the Test Connection button. The results will be displayed in the rectangular text area.

  6. To complete the connection, click OK.

Note that your Perforce changelist will display the connection that applies to each file in the changelist. For more information on changelists, see...

6.4.2.6 Refreshing the Status of Objects Under ClearCase Control

In Rational ClearCase, the source control status of a ClearCase object is indicated in the Applications window by an icon overlay, as below.

Table 6-1 Status icons for ClearCase

Icon Description

checked out

The object is checked out and can be modified.

checked in

The object is checked in and must be checked out before it can be modified.


If the status of an object is changed outside JDeveloper, for example by checking in an object using external source control software, the new status might not immediately be shown in JDeveloper. To ensure that the status indicated in the Applications window matches the true status of the object in the source control system, you can perform a manual refresh. To refresh the status of objects in JDeveloper, select Team > Refresh States.

6.4.3 How to Configure JDeveloper for the Source Repository

If you are using Subversion, which is included by default in JDeveloper, you do not need to configure JDeveloper for your source repository. You only need to connect to the repository, then you update your local working copy, check files out to work on them, and then check in your changed files on completion. Other version control systems, however, have configuration requirements, which require you to configure them, and JDeveloper, before use.

6.4.3.1 How to Configure CVS For Use with JDeveloper

In addition to setting up JDeveloper to be able to use CVS, there are certain tasks you need to perform to make CVS usable with JDeveloper. Some of these tasks may be performed by your administrator. You should always check to make sure which of these tasks have been performed in your installation.

In general, you need a local CVS repository for storing files as you are working on them. You may also need to configure a secure shell (SSH) for communicating with CVS, and you may need to choose a character set. Finally, you will need to log in to CVS.

6.4.3.2 Configuring SSH (Secure Shell), CVS and JDeveloper

JDeveloper supports SSH Levels 1 and 2 as access methods for CVS repositories.

6.4.3.2.1 Configuring for SSH Level 1 (SSH)

JDeveloper does not provide a direct way of using SSH Level 1 as an access method for the CVS repository. It is however possible to configure SSH Level 1 so that it can be used for remote shell access.

To configure SSH Level 1 to enable remote shell access: 

  1. Generate public and private keys using the command: ssh-keygen

  2. Concatenate the ~/.ssh/identity.pub public key file with ~/.ssh/authorized_keys on the machine with the CVS repository.

Before running JDeveloper and attempting to use CVS with SSH Level 1, users should be explicitly authorized and the environment correctly configured. Follow the steps below to configure the environment correctly.

To configure the environment for SSH Level 1: 

  1. Set the CVS_RSH environment variable to the location of the SSH client.

  2. At the UNIX command line, enter ssh-agent {shell}, and then press Enter.

  3. At the UNIX command line, enter ssh-add, and then press Enter.

  4. Start JDeveloper.

  5. Select External as the CVS access method when using the CVS Connection Wizard.

6.4.3.2.2 Configuring for SSH Level 2 (SSH2)

JDeveloper provides a direct way of using SSH2 as an access method for the CVS repository.

To use SSH2 for remote shell access: 

  1. On the JDeveloper CVS preferences page, set the CVS Client preference to Internal to JDeveloper [...].

  2. Start the CVS Connection Wizard.

  3. While using the CVS Connection Wizard, on the Connection page, choose Secure Shell via SSH2 as the Access Method. For more help at this stage, press F1 or click Help.

  4. On the Connection page, click Generate SSH2 Key Pair. This opens the Generate SSH2 Key Pair dialog. For help using this dialog, press F1 or click Help.

  5. After generating the SSH2 key files, an information dialog will appear that explains where to install the files.

  6. Install the SSH2 key files as instructed in the dialog.

  7. Complete the CVS Connection Wizard to create the CVS connection.

If you are using an internal CVS client, you can generate SSH2 key files at any time by choosing Team > CVS > Administration > Generate SSH2 Key Pair. If you are using an external CVS client, this menu option is unavailable.

6.4.3.3 Editing and Watching Files in CVS

Editing and watching are available only when an external CVS client executable is used.

These procedures allow you to obtain and release an editor on a file, to know who else in your team is editing files, and to know who is watching for files to be edited. Two or more developers retain the ability to edit the same file at the same time.

To set up JDeveloper to use editing and watching: 

  1. Open the preferences page obtainable from Tools > Preferences | Versioning | CVS.

  2. Ensure that External Executable is selected and that valid details are entered.

  3. Select Run CVS in Edit/Watch Mode.

  4. Open the preferences page obtainable from Tools > Preferences | Versioning | CVS | General.

  5. Deselect Automatically Make Files Editable.

To obtain an editor on a file: 

  1. With the file selected in the Applications window, select Team > Edit.

  2. Check that you want the operation to apply to all of the files highlighted in the file selection box.

  3. To set up a watch for this file, select the Set Watch Actions checkbox and select a watch action from the drop-down list.

  4. Click OK.

To release an editor on a file (to unedit a file): 

This action reverses changes made in the current edit. Any local file modifications will be lost when the editor is released.

  1. With the file selected in the Applications window, select Team > Unedit.

  2. Check that you want the operation to apply to all of the files highlighted in the file selection box.

  3. Click OK.

To turn on or turn off the file watching facility: 

  1. In the Applications window, select a project containing files about which you want to be notified.

  2. Select Team > Watch.

  3. In the Watch CVS Files dialog, choose Turn On Watching or Turn Off Watching from the Command Type drop-down list.

  4. Click OK.

To add yourself to the list of people who receive notification of work done on files: 

  1. In the Applications window, select the project containing the files about which you want to be notified.

  2. Select Team > Watch.

  3. Check that you want the operation to apply to all of the files in the file selection box.

  4. On the Watch Settings tab, choose Add File Watch as the Command Type from the drop-down list.

  5. Optionally, check the Set Watch Actions checkbox and choose the particular actions that you want to be notified about.

  6. Click OK.

To remove yourself from the list of people that receive notification of work done on files: 

  • Follow the procedure for adding yourself to the list (above), but choose Remove File Watch from the Command Type dropdown list.

To see who is watching for changes being made to files: 

  • Select Team > Edit Notifications.

The Edit Notifications window is opened. The Watchers tab shows the files that are being watched and the user(s) who are currently watching for changes.

To see who is currently editing files: 

  • Select Team > Edit Notifications.

The Edit Notifications window is opened. The Editors tab shows the files that currently have editors on them and the user(s) who have obtained those editors.

6.4.4 How to Load the Repository with Content

Before you can use the repository for your selected version control system, you typically have to load the repository with the content your team will be working on. You might need to do this when:

  • your team begins to work on a new version of the project (especially if you are working on more than one version concurrently, such as a patch set and a major update)

  • your team is starting an all-new project, either by beginning with an older version or with file templates

  • you are performing a clean installation of JDeveloper on a new workstation that does not yet contain a local file system to store your repository's files as you work on them

Normally, loading the repository with content is done once per project. After this initial load, you will regularly update the files and folders in your local repository to ensure that your files are up to date with the work of your team.

6.4.4.1 Importing JDeveloper Files Into Subversion

Files that you created within (or brought into) JDeveloper before using Subversion control must be imported into the Subversion repository, and then checked out from it.

To import an existing JDeveloper project or application into Subversion:

  1. In the Applications window, select the application or project that you want to import into Subversion.

  2. Select Team > Import Files.

    The Import to Subversion wizard opens.

  3. Complete the wizard. For help while using the wizard, press F1 or click Help.

    If you allowed the wizard to check out the imported files, the files are shown in the Applications window with a version number next to them. You may have to refresh the view before the files are shown.

    If you did not allow the wizard to check out the imported files, you must now check them out before you can work on them.

6.4.4.1.1 Importing a Project to Subversion

You can also import an entire project into Subversion using the JDeveloper Version Application feature.

To import files using Version Project:

  1. Select the application you wish to add to version control.

  2. Select Team > Version Project. This opens the Import to Subversion wizard.

  3. Complete the wizard. For help while using the wizard, press F1 or click Help.

    If you allowed the wizard to check out the imported files, the files are shown in the Applications window with a version number next to them. You may have to refresh the view before the files are shown.

    If you did not allow the wizard to check out the imported files, you must now check them out before you can work on them.

After you import files into Subversion using the Version Application feature, you will notice that Subversion creates two directories, one as your work area and one as a backup directory.

For example: after creating a new application called Catalog, select Versioning > Version Application > Subversion. Be sure to select the Perform Checkout from the Options page, then finish the wizard.

When the wizard completes, browse to the local directory that you have specified as the Source Directory for this application in Subversion. You will see two directories listed there: Catalog.svn-import-backup and Catalog.svn-import-workarea.

JDeveloper (and Subversion) will use the Catalog.svn-import-workarea directory for file access, checkout/checkin, and other activities. You should avoid editing, moving, or manipulating files in those directories outside of JDeveloper and Subversion.

6.4.4.2 Adding a File to Subversion Automatically

When you create a new file in JDeveloper that is part of a local working copy (that is, an application that has been versioned and checked out of your SVN repository), you need to add and then commit the file to Subversion control before you can use the JDeveloper Subversion facilities with it. The preferred method is to set up JDeveloper to do this automatically, through the Preferences menu.

To add new files on commit: 

  1. Select Tools > Preferences > Versioning > Subversion > General.

  2. Select Automatically Add New Files On Committing Working Copy.

  3. Click OK.

6.4.4.3 Adding Files Individually to Subversion

You can also place individual files under Subversion control.

To place individual files under Subversion control: 

  1. Select the files in the Applications window and choose Team > Add.

    The files can be your work files, or they can be the application and project files used by JDeveloper.

    The Add to Source Control dialog is displayed with the files listed.

  2. To add the files to Subversion control, click OK.

    The files are now shown in the Applications window with a black cross, meaning that they are stored in your JDeveloper workarea but are not yet committed to the Subversion repository. Files must be committed to the Subversion repository before they can be versioned and accessed by other users.

  3. To commit files to the Subversion repository, select the files in the Applications window and choose Team > Commit.

    The Commit Resources dialog is displayed with the files listed.

  4. Add your versioning comments in the Comments box.

    You will later be able to see these comments when viewing the list of versions of a particular file.

  5. To commit the files to the Subversion repository, click OK.

    The files are now shown in the Applications window with an orange dot, indicating that they are known to the Subversion repository and are up to date.

6.4.4.4 Moving Files from Remote Repositories in Git

While you use your local Git repository for changes made while editing, it is frequently necessary in a distributed team to work with remote repositories. Push, pull and clone are three concepts that apply to remote Git repositories.

Fetching and pulling are two different methods of obtaining content from a remote repository. When you fetch from a remote repository, Git loads all changes into your local repository but it does not change any of your existing branches. This way, you can inspect the changes and merge them as appropriate.

To copy from a remote repository without changing existing branches:

  1. Select Team > Git > Fetch

  2. Follow the instructions on the wizard screens to specify the remote repository and remote branch you wish to fetch.

  3. Click Finish to fetch the files from the remote repository.

Pulling, on the other hand, copies files from the remote repository and updates the HEAD branch of your local repository. More

To copy changes from your local repository to the remote repository, use the Push command.

6.4.4.5 Importing JDeveloper Files Into Perforce

Perforce uses a local directory structure to receive files that are going to be placed under formal source control. This location is called the ”Perforce client workspace”. Files created in (or moved into) JDeveloper must be stored in this location. Once files are in your Perforce client workspace, you bring them fully under source control by submitting them to a central location called the ”Perforce depot”. Files must be submitted to the Perforce depot before they can be versioned and accessed by other users.

Before you can start using existing JDeveloper project and source files with Perforce, you have to import them into your Perforce client workspace. Once they are in your Perforce client workspace, you bring them fully under source control by submitting them to the Perforce depot.

You import JDeveloper project and source files into your Perforce client workspace using the Import to Perforce wizard.

To use the Import to Perforce wizard:  

  1. If you have not already done so, connect to Perforce by choosing Team > Connect to Perforce.

  2. In the Applications window, select the JDeveloper project that you want to bring under Perforce control.

  3. Choose Team > Import Project. The Import to Perforce wizard is displayed.

  4. Complete the import as prompted by the wizard. To obtain more information when working with the wizard, press F1.

    The project and files will be shown in the Applications window. If you have chosen to display overlay icons, these will indicate the current source control status of the files.

  5. To bring the files fully under Perforce source control, submit them to the Perforce depot.

6.4.4.6 Updating a Project, Folder, or File in CVS

The CVS update operation updates your local files with data in the CVS repository. Alternately, you can choose to completely replace your local files with those held in the CVS repository.

You can update individual files (including project files), or you can update the entire contents of a project folder.

You can view the contents of the CVS repository through the CVS Navigator. The nodes under CVS Server unfold to reveal the structure and file content of the CVS repository. You can open a read-only version of a CVS repository file by choosing Open from its context menu. This will let you see what changes have been made to the files in the CVS repository since you checked out or last committed your local versions.

To update an individual file (including a project file): 

  1. Select the file(s) in the Applications window, and then choose Team > Update.

  2. Set the options as required. For information about these options, press F1 or click Help.

  3. To update all the files listed, click OK.

To update the contents of a project folder: 

  1. Select the project folder(s) in the Applications window and then, from the context menu, choose Update Project Folders.

  2. Set the options as required. For information about these options, press F1 or click Help.

  3. To update all the files listed, click OK.

To update files shown in the Pending Changes window: 

  1. With the Pending Changes window in Incoming Changes mode, select the files that you want to update.

    To obtain more information about the Pending Changes window, press F1 or click Help.

  2. Click the Update button.

Note:

For the Pending Changes window to be populated with candidates, the project containing those candidates must be open. If you do not see a file that you expect to see, open the project (File > Open > Project, then select your project).

6.4.5 How to Create a WebDAV Connection

Web-based Distributed Authoring and Versioning, or WebDAV, is an extension to HTTP which allows users to edit and manage files on WebDAV-enabled servers in a collaborative fashion. WebDAV connections in JDeveloper allow you to view files hosted on WebDAV servers in the same way as you would files on the local file system. Files located on WebDAV servers, accessed using WebDAV connections in JDeveloper, can be viewed in the same way as files stored on the local file system or LAN.

As WebDAV clients provide access using HTTP, files can be accessed through firewalls (configured to support WebDAV extensions) that would otherwise prevent FTP file transfer. The JDeveloper read-only implementation of WebDAV supports the current WebDAV 1.0 standard, which does not support versioning. As a WebDAV client, JDeveloper can connect directly to any Oracle Internet File System, allowing you to view WebDAV files from the database.

6.4.5.1 WebDAV Server Requirements

You must run a WebDAV server to use JDeveloper as a WebDAV client. The WebDAV server must be one of the following:

  • Apache 1.3.19 (or above)

    Note:

    If the Apache server is version 1.x, the mod_dav module must also be installed.

  • A server that conforms to the WebDAV 1.0 standard

Note:

If you access the Internet through a firewall, it must be configured to process the extended HTTP commands used by WebDAV.

If your web server is configured to redirect URLs to a different server (for example, if you are using JkMount in Apache to redirect requests for certain file extensions to Tomcat), be aware that WebDAV will not be available for those resources if the server you are redirecting to does not support WebDAV in that context.

If you'd like to find out more about WebDAV, see the following Web sites:

  • http://www.webdav.org

  • http://httpd.apache.org/docs-2.1/mod/mod_dav.html

6.4.5.2 Creating a WebDAV Connection

WebDAV connections created in JDeveloper allow you to view files and folders as part of a JDeveloper project.

Note:

The same URL cannot be used for more than one WebDAV connection on the same JDeveloper client.

To create a WebDAV connection in JDeveloper:  

  1. In the New Gallery, choose General > Connections > WebDAV Connection, then click OK.

  2. Use the WebDAV Connection dialog to create a connection.

    For more information while using the dialog, press F1.

6.4.5.3 Accessing a WebDAV-Enabled Server Via a Proxy Server

If you access the internet via a proxy server you need to configure JDeveloper before accessing WebDAV-enabled servers on the internet.

To access a WebDAV-enabled server via a proxy server: 

  1. Check with your network administrator to ensure that your proxy server is WebDAV-enabled.

  2. In JDeveloper choose Tools > Preferences, click Web Browser and Proxy in the left pane of the Preferences dialog box, make sure that the Use HTTP Proxy Server checkbox is checked, then enter the details for the proxy.

  3. If the WebDAV-enabled server you want to access is inside your firewall and you do not need to go through your proxy server to access it, add the name of the WebDAV server to your default web browser's proxy exceptions list. This is normally set on the browser's preferences/settings page with the other proxy settings.

6.4.5.4 Modifying a WebDAV Connection

WebDAV connections are shown in the Application Resources section of the Applications window, listed under the Connections node.

Existing WebDAV connections can be modified.

To modify a WebDAV connection: 

  1. Right-click the WebDAV connection that you want to modify.

  2. Choose Properties.

  3. On the WebDAV Connection Properties dialog, change the details of the WebDAV connection.

    For help while using the dialog, press F1.

  4. Click OK.

6.4.5.5 Refreshing a WebDAV Connection

WebDAV connections are shown in the Application Resources section of the Applications window, listed under the Connections node.

To ensure that the folders and files accurately reflect the current contents of the WebDAV server, you can manually refresh the display of a WebDAV connection.

Note:

All folders and files listed for the WebDAV connection are refreshed. The properties of the folders and files, and their contents, are refreshed.

To refresh the entire contents of a WebDAV connection: 

  1. Right-click the WebDAV connection that you want to refresh.

  2. Choose Refresh.

6.4.5.6 How to Delete a WebDAV Connection

WebDAV connections are shown in the Application Resources section of the Applications window, listed under the Connections node.

Deleting a WebDAV connection from JDeveloper does not affect any of the files or folders on the WebDAV server itself.

To delete a WebDAV connection: 

  1. Right-click the WebDAV connection you want to delete.

  2. Choose Delete.

You can subsequently recreate the connection, in which case the files and folders that were part of it will be shown beneath it again.

6.5 Working with Files in Source Control

As a general rule, your workflow in the version control system your team uses will follow this basic format:

  • Check out files from the repository

  • Make changes

  • Check in (or commit) files back to the repository

In some circumstances, you may find that other team members have been editing the same files that you are committing. This requires resolving file conflicts.

In addition, many version control systems allow you to lock a file so that other users cannot check it out. This prevents you from having file conflicts which need to be resolved.

6.5.1 How to Check Out Files

Commonly, your version control system requires you to check out a file from the repository before you begin making changes to it. This logs your access to the file and, in many instances, locks the file you have checked out to prevent other team members from accessing it while you are editing it. This can help prevent problems where multiple team members make conflicting edits to the same file.

6.5.1.1 Checking Out Files from the Subversion Repository

To begin making edits and revisions to files in your project, you check out the files you will be working with. It is recommended that you check out the entire application from the Subversion repository, so that you will have access to all files in that application in your local work area. Subversion uses the term modules to refer to the application it is recommended you check out.

Note:

With Subversion, there is no "check in" procedure, so you do not check in files that you have updated and check them out again when you next want to work on them. Instead, when you have finished working on your local copies of files, you commit them to the Subversion repository to bring the files up to date.

When you check out Subversion files, they are copied from the Subversion repository to a new location (specified by you) on your local machine. This location and the files within it constitute the Subversion "working copy".

To check out modules from the Subversion repository:

  1. In the Versions window, select the repository node or folder containing the files that you want to check out.

  2. Choose Team > Subversion > Check Out.

    If there is no current connection to a Subversion repository, the Create Subversion Connection dialog is opened for you to create one.

    The Check Out from Subversion dialog is displayed. To obtain more information when working with the dialog, press F1 or click Help.

  3. Make sure that the Subversion connection that the dialog displays is the correct connection (if you have more than one Subversion connection or repository).

  4. Browse to the path in the Subversion connection containing the application files you wish to check out.

  5. Enter the destination in your work area to which you wish the checked-out files to be copied, or click Browse to navigate to your local work area.

  6. You have the option of checking specific tags, if your team uses them.

  7. If you wish to check out files within folders contained by this Subversion module, make sure to select Depth.

    When you have made all your selections, click OK.

6.5.1.2 Checking Out Files in Git

Checking out a file from your Git repository makes that file available for changes and edits. You can also specify the revision you wish to check out.

To check out a file:

  1. Select Team > Git > Checkout.
    This displays the Git Checkout Revision dialog.

  2. Enter the branch from which you wish to check out the file. To browse from a list of available branches, click the Branch button.

  3. Select the tag (optional) you wish to check out. To view a list of tags, click the Tag button, then select the desired tag.

  4. Specify the commit ID (optional) for the checkout. To view a list of commit IDs used in your repository, click the Select Commit button, then choose from the list of commit revisions.

  5. Optionally, create a new branch for the checkout.

  6. When you have made all your selections, click OK.

Git checks out the files you have selected. They are now available for editing.

6.5.1.3 Checking Out CVS Modules

This is a configuration task you perform when you first start to use JDeveloper with files and folders that are under CVS source control. You perform this task once, after (if necessary) importing your JDeveloper project into the CVS repository.

To check out modules from the CVS repository:

  1. In the CVS Navigator, select the CVS module that you want to check out.

    Either:

    Choose Team > CVS > Check Out Module.

    or:

    from the context menu, select Check Out Module.

    The Check Out from CVS dialog is displayed.

  2. Complete the dialog. For help when using this dialog, press F1 or click Help.

6.5.1.4 Editing Files in Perforce

Unlike some version control systems, Perforce does not require you to explicitly check out a file. To begin editing a file in Perforce, select Team > Perforce > Open for Edit. This opens the Open Files for Edit dialog, which gives you the option of placing the file on a changelist, locking the file so that other team members cannot edit it simultaneously, and more. More

You can start editing a file under Perforce control just by opening it from the Applications window. While the Perforce server is being contacted, you may experience a delay before you can type into the opened file. If you would prefer files to remain closed until you manually open them for editing, set the Automatically Open Files for Edit preference to off.

6.5.2 How to Update Files with Subversion

Updating files at the beginning of every work session helps ensure that you have all the changes made and checked in by your team members. This reduces the amount of time you might have to spend reconciling changes later, because it helps ensure that you have the latest version of your files when you begin editing them.

6.5.2.1 Updating Files from the Subversion Repository

Once your Subversion repository is set up, you typically update your local working copy with files from the repository. This ensures that the files you work on contain all committed changes that others on your team may have made to the same files.

It is recommended that you perform the update operation on a working copy.

When you use Update Working Copy, all the files in your checked-out working copy will be updated, regardless of which node you have active in your application in the JDeveloper Applications window. The alternative is to select Update. This will only update the folder or file (and any child folders and files) that you have selected in the Applications window.

To update a working copy (recommended): 

  1. In the Applications window, select a navigator node or file that is part of the working copy.

  2. Select Team > Update Working Copy.

    The Update Working Copy dialog is displayed with the working copy folder listed.

  3. Ensure that the folder shown is the correct one for the working copy that you wish to update. If it is not, cancel the dialog and begin again from step 1.

  4. Set the options on the Update Working Copy dialog as required.

    To obtain more information about the options, press F1 or click Help.

  5. To update the working copy from the Subversion repository, click OK.

6.5.2.2 Updating Individual Files in the Subversion Repository

You can also update individual files. However, this runs the risk of not updating all files that may have been modified by your team members since the last time you checked them out.

To update individual files: 

  1. In the Applications window, select the file(s) that you wish to update and choose Team > Update.

    The Update Resources dialog is displayed with the file(s) listed.

  2. Set the options on the Update Resources dialog as required.

    To obtain more information about the options, press F1 or click Help.

  3. To update the listed file(s) from the Subversion repository, click OK.

6.5.2.3 Removing Files from Subversion Control

If you wish to remove a file from Subversion control, use the JDeveloper Delete feature. This performs a ”safe delete,” which searches for usages of the file you are deleting and provides you with a dialog with options for proceeding.

To remove a file from Subversion control: 

  1. In the Applications window, select the file to be removed from Subversion.

  2. Select Edit > Delete (or right-click the file and select Delete).

  3. Make sure that Delete Safely is selected.

  4. Click OK.

    If JDeveloper finds usages of the file you are deleting, a dialog will offer you options for proceeding. Choose the appropriate option, then click OK.

6.5.2.4 Working with Files in CVS

As a very general rule, working with files in CVS means checking out the latest version of a file, making your edits, and checking the file in with your changes. Occasionally, if you and a colleague have made edits to the same file, you may need to merge your changes to make sure your work is not lost. Other functions of CVS are also available, such as adding a new file or removing unused/obsolete files from the repository, but your general workflow will follow the checkout-edit-checkin pattern.

The file operations in CVS include refreshing the display of CS objects, adding and removing files, using templates, comparing files, replacing a file in CVS, viewing the history and status of a file, locking and unlocking files, and working with revisions and tags.

6.5.2.5 Refreshing the Display of CVS Objects

The source control status of an object is indicated in the Applications window by an icon overlay, as listed in Table 6-2.

Table 6-2 CVS Object Status

Icon Description

Added icon

The object has been copied from the CVS repository and added to your working files directory.

Not added icon

The object is not under CVS source control, but may be added to the CVS repository.

Conflicts icon

There were conflicts when the object (a file) was updated from the CVS repository. In this case, you have to manually edit the file to resolve all the points of conflict.

Scheduled for removal

The object has been scheduled for removal from the CVS repository with the next commit action.

Modified

The object is out of synch with the CVS repository due to local or remote changes.

Unmodified

The object is unmodified since it was last copied from the CVS repository.

Unmodified read-only

The object is unmodified since it was last copied from the CVS repository but is read-only.

Sandbox

The package or node is a CVS sandbox folder.

COnfused composite

The apparent object may comprise several underlying objects, the statuses of which may not all be identical.


If the status of an object is changed outside JDeveloper, for example by checking in an object using external source control software, the new status might not immediately be shown in JDeveloper. To ensure that the status indicated in the Applications window matches the true status of the object in the source control system, you can perform a manual refresh.

To refresh the status of objects in JDeveloper: 

  • In the Applications window or CVS Navigator, click the refresh button.

6.5.2.6 Adding and Removing Files in CVS

You can add a file to CVS only if it is part of a project that is already under CVS version control.

When you create a new file, for example a new class, it has to be added to source control before you can use the other CVS operations on it. The file is added to source control locally, and the CVS repository is not updated. The file is identified in the Applications window by the icon +.

After completing setup, your work will revolve around the following:

  • updating your files from the repository,

  • checking out the files you need to work on,

  • editing them in JDeveloper, and

  • committing the modified files back to the repository.

You may also need to resolve conflicts between changes you made and those made by others in your team. Files may also be moved in and out of CVS control as the project changes. Finally, you might use special properties of the files associated with specific versions for tracking bugs, customer requests, and other characteristics.

To add a file to CVS through the Applications window: 

  1. Select the file in the Applications window and choose Team > Add (or, if the file is binary, Team > Add as Binary). JDeveloper usually recognizes binary files and adds (Binary) after the file name in the Applications window. The Add to CVS dialog (or Add to CVS as Binary dialog) is displayed, with the file listed.

  2. Click OK.

    The file will be added to the CVS repository when the next commit is performed.

To add files shown in the Pending Changes window: 

  1. With the Pending Changes window in Candidate Files mode, select the files that you want to add to source control.

    To obtain more information about the Pending Changes window, press F1 or click Help.

  2. Click the Add button.

To remove a file from CVS: 

When you remove a file from CVS it is removed from your local disk.

  1. In the Applications window, select one or more files to be removed, then choose Team > Remove.

  2. The Remove from CVS dialog is displayed with the files listed.

  3. Click OK.

The file or files will be removed from the CVS repository when the next commit is performed.

6.5.3 How to Work with New and Changed Files in Git

In the Git version control system, you commit files for two reasons: to make your initial import of new files to your repository, and to check in changes when you have made edits.

In Git, the basic file workflow is in three parts:

  1. You initially create a local file system with the selected branch and content from your repository. You can do this using Team > Git > Clone.

  2. You add new files to the repository: one at a time using Team > Git > Add, or multiple files with Team > Git > Add All.

  3. As you edit files, you check them back into the Git repository one at a time with Team > Git > Commit, or multiple files with Team > Git > Commit All.

The following sections describe how to perform these operations.

6.5.3.1 Adding a File to a Git Repository

To add a single file to your Git repository, use the Add command from the Git menu.

To add a file:

  1. Select Team > Git > Add.

  2. Browse to the pathname for the file you wish to add.

  3. Click OK.

The file is added to your selected Git repository.

6.5.3.2 Adding Multiple Files to a Git Repository

To add multiple files to your Git repository, use the Add All command from the Git menu. This command adds all files in a directory.

To add multiple file:

  1. Select Team > Git > Add All.

  2. Browse to the pathname for the directory from which you wish to add files.

  3. Click OK.

All files in the selected directory are added to your Git repository.

6.5.3.3 Committing a Change to the Git Repository

When you have made changes to a file, you can commit them to the Git repository.

To commit a change:

  1. In the Applications window, select the file whose changes you want to commit.

  2. Select Team > Git > Commit. This displays the Commit dialog, which displays the file name and location in your local directory.

  3. In the Commit dialog, you can optionally choose to commit non-staged files.

  4. In the Comments field, enter a short description of the changes you have made to the file you are committing.

  5. If your team uses comment templates, select one from the Comment Templates drop-down list. You can also select the link to display the Preferences > Git > Comment Templates dialog. This allows you to add or import comment templates.

  6. When you are finished, click OK.

JDeveloper commits your changed file to the Git repository.

6.5.3.4 Committing Multiple Files to the Git Repository

When you have made changes to multiple files, you can commit them all to the Git repository in one operation.

To commit a number of changed files:

  1. In the Applications window, select the files whose changes you want to commit.

  2. Select Team > Git > Commit All. This displays the Commit dialog, which displays the path name to the files in your local directory.

  3. In the Commit dialog, you can optionally choose to commit non-staged files.

  4. In the Comments field, enter a short description of the changes you have made to the file you are committing.

  5. If your team uses comment templates, select one from the Comment Templates drop-down list. You can also select the link to display the Preferences > Git > Comment Templates dialog. This allows you to add or import comment templates.

  6. When you are finished, click OK.

JDeveloper commits your changed files to the Git repository.

6.5.4 How to Work with Files in Perforce

Perforce provides features for creating and applying patches—methods for determining changes between two revisions of a file, and then applying those changes to a third file. In addition, Perforce contains features for exporting the details about repository connections, as well as files in the repository.

6.5.4.1 Synchronizing Local Files With the Controlled Versions in Perforce

Another person may edit a file through their Perforce client and submit their changes to the Perforce depot. This will cause your copy of the file to become out of date compared with the controlled version.

To test that your view is showing the latest file statuses: 

  • Choose View > Refresh.

    A file that is out of date with the controlled version is shown with an exclamation point icon.

To bring your files up to date compared with the controlled version: 

  1. From the Connection drop-down list, select the preferred Perforce connection (if you have more than one) for this changelist.

  2. Select the files in the Applications window and choose Team > Sync.

    The Sync Files dialog is displayed with the files listed.

  3. Complete the dialog.

    For more information about the dialog options, press F1.

  4. To synchronize the files, click OK.

    Your local files are replaced with copies of the controlled versions. The icon shown next to the files changes to a green dot.

6.5.4.2 Synchronizing Files With the Perforce Navigator

The Perforce Navigator lets you browse the Perforce depot and update your working directory from content at the depot. Using the Applications window, you can select folders or files to sync to your client workspace, downloading content from the Perforce Server to your computer. If new files are detected in the depot, you have several options for handling them.

If you opens a connection node and no connection has been made, Perforce displays the connection dialog.

To synchronize your files using the Perforce Navigator: 

  1. Expand the content under Perforce in the Versions window, selecting the folders and/or files you wish to synchronize. When you expand to the level of the project you're working on, right-click the file or folder, and then select Sync From Depot. This displays the Sync From Depot dialog.

  2. The project you selected displays in the Name pane of the Sync From Depot dialog. Below that are fields you can select or specify:

    Head Revision

    Synchronize to the Head revision of your project. If you select this, the Sync From Depot dialog displays the Force sync checkbox. Select Force Sync if you wish to download the depot content to your working directory regardless of the contents of each (for example, if you know you want to start with a clean download of the depot's contents).

    Revision Number

    Select this to synchronize to a specific revision number. The Sync From Depot opens the Target field; use the Target field to type the revision number to which you wish to synchronize your local working copy.

    Changelist

    Select this to synchronize to a specific changelist. The Sync From Depot opens the Target field; use the Target field to type the name of the change list from which you wish to synchronize your local working copy.

    Label Name

    Select this to open files with a specific label (typically, used to identify a specific branch). The Sync From Depot opens the Target field; use the Target field to type the name of the label from which you wish to synchronize your local working copy.

    Date

    Select this to specify a date (and, optionally, time) from which you wish to synchronize your local files. The Sync From Depot opens the Target field; use the Target field to type the date (in either yyyy/mm/dd or yyyy/mm/dd:hh:mm:ss format) of the files from which you wish to synchronize your local working copy.

    Choose the field that applies to your current project, then click OK.

  3. If the depot contains files that do not exist in your source, Perforce tells you that new files were detected, and lists the following options:

    Open files in active project

    Copy the files, and open them in the project you have selected.

    Create new project from files

    Creates a new project, using the files Perforce has detected.

    Open editors onto files

    Open the files in editor windows, so that you can review them and determine the best resolution (keep, rename, discard, or modify).

    Do not open files

    Leaves the files unopened, without copying them from the depot to your working directory.

6.5.4.3 Filtering Files By Perforce Workspace

If you have a very large number of files in your Perforce depot, it can be much easier to navigate to the files you're working on by filtering files in the Perforce workspace. You can do this by setting things up in the Perforce client, and then displaying the filtered view in JDeveloper.

Filtering files in Perforce (specifically, p4v) requires making sure that you are viewing the Depot Tree, then select the Filter icon > Tree Restricted to Workspace View.

To filter files in JDeveloper: 

  • Version Navigator > Perforce > Connection name > Context menu - Filter by Client Workspace.

You will only see a difference in the JDeveloper Version Navigator if the Perforce client has a rule that restricts the Perforce workspace. (In p4v, the rules are shown and set in the View field of the Workspace dialog for the selected workspace.) You could restrict the workspace view in your p4v client with a rule like the following:

//depot/JDeveloper_1013/... //<client name>//JDeveloper_1013

In JDeveloper, if you select Filter by Client Workspace, the Applications window would be filtered so only //depot/JDeveloper is shown.

6.5.4.4 Refreshing the Status of Files under Perforce Control

The source control status of a file is indicated in the JDeveloper navigators by icon overlays, as listed in.

Table 6-3 Perforce Status Icons

Icon Meaning

Not in depot

The file is in the Perforce client workspace but is not yet submitted to the Perforce depot.

Ready for deletion

The file will be deleted when next submitted to the Perforce depot.

Out of date

The file is out of date compared with the Perforce depot.

Overlay not open

The file is up to date compared with the Perforce depot.

Open for Edit

The file is open for edit.

Locked

The file is locked.


If the status of a file is changed outside JDeveloper, for example by using a Perforce client application, the new status might not immediately be shown in JDeveloper. To ensure that the status indicated in the Applications window matches the true status of the file in the source control system, you can perform a manual refresh.

To refresh the status of files in JDeveloper: 

  • Select View > Refresh.

6.5.4.5 Deleting Files from Perforce

If you wish to delete a file that it is under Perforce control, you should do so using the Perforce facilities within JDeveloper or the Perforce client application.

To delete a file under Perforce control: 

  1. Select the file in the Applications window and choose Team > Open for Delete.

    The Delete Files dialog is displayed with the file listed.

  2. Click OK.

    The file is deleted from the local file system. A black diagonal cross is added to the file's icon in the Applications window.

If you need to retrieve a file that has been deleted, you will need to use the Perforce client. To do this, select Team > Perforce > Launch Perforce Client.

6.5.5 How to Remove a File From ClearCase

You can remove a file from ClearCase if you no longer need it. The files are removed from the current version of the directory which contains them.

To remove a file from ClearCase:

  1. With the file or files selected in the Applications window, choose Team > Remove. The Remove from ClearCase dialog is displayed with the files listed.

  2. To remove all the listed files from ClearCase, click OK.

The files are removed from the current version of the directory, and you will no longer be able to work with them.

6.5.6 How to Check Out a File From ClearCase

To work on a file, it must be checked out from ClearCase.

Files will be checked out automatically when you start to change them, if the Automatically Check Out Files preference is set on the ClearCase preferences page (available by choosing Tools > Preferences and selecting ClearCase). This preference applies to data files, workspace files and project files. For data files, the file is checked out when you begin to edit in the source view. If you check out a file unintentionally, immediately use Team > Undo Checkout to revert.

To check out one or more files manually:

  1. Select the files in the Applications window, and choose Team > Check Out. The Check Out From ClearCase dialog is displayed listing the items you have selected.

    If you want to prevent another user from checking out the same files and then checking them in before you do, check the Check Out Reserved To User box.

  2. Type comments about this checkout into the Comments box.

  3. To check out the listed files, click OK.

The files in the list are checked out from ClearCase source control and you can work on them.

Checked out files are shown in the Checked Out Files window. This window opens when files are first checked out. You can open it at other times by selecting Team > View Checked Out Files.

6.5.7 How to Undo a ClearCase Checkout

If you have checked out a file but not made any changes to it, or if you want to discard the changes you have made, you can undo the last check out of that file.

Caution:

You may lose you work if you use this on a file that you have changed since it was checked out.

To undo checkout for one or more files:

  1. Select the files in the Applications window, and choose Team > Undo Checkout. The Undo Clearcase Checkout dialog is displayed listing the items you have selected.

  2. To undo the checkout for all the listed file, and lose any changes that you have made to those files, click OK.

6.5.8 How to List ClearCase Checkouts

You may want to see all the files that you have checked out from ClearCase, for example to see which files need to be checked in before performing another action.

To list ClearCase checkouts:

  • Choose Team > View Checked Out Files. The Checked Out Files viewer is displayed.

6.5.9 How to Compare Files Checked In to ClearCase

Use these procedures to compare versions of files that are under ClearCase source control. You can compare a file with its immediate predecessor, any of the file's previous revisions, or any other file on your file system.

To compare a file with its immediate predecessor:

  • With the file selected in the Applications window, choose Team > Compare with Previous Version.

If there are no differences, a message is displayed. Otherwise, a Compare Viewer is displayed through which you can find and reconcile the differences.

To compare a file with another revision:

  • With the file selected in the Applications window, choose Versioning > Compare. Ensure that the Predecessor File Revision option is chosen.

Previous versions of the file are listed in the Compare ClearCase File dialog. Select the version you want to compare the current file with and click OK.

If there are no differences, a message is displayed. Otherwise, a Compare Viewer is displayed through which you can find and reconcile the differences.

To compare a file with a file outside ClearCase source control:

  • With the file selected in the Applications window, choose File > Compare With > Other File.

The Select File to Compare With dialog is opened.

Browse to and select the file you want to compare the current file with, and then click Open.

6.5.10 How to Lock and Unlock Files

Not all version control systems explicitly require, or even have the facility for, locking files before editing. In some systems, checking out the file automatically locks it and prevents other team members from editing that file. In other systems, the files can be checked out by any team member, with the emphasis being on easily merging different changes to the resulting file.

The following sections explain how each version control system handles locking and unlocking a file.

6.5.10.1 Locking and Unlocking Files in Subversion

Team > Lock

6.5.10.2 Locking and Unlocking Files in CVS

Note:

The locking of files is not supported in newer releases of CVS client software and this facility may be removed in future releases of JDeveloper.

You can choose to prevent other users working on a file while you are working on it yourself. This is not normally considered necessary, because CVS can usually reconcile differing versions of files as they are being committed to the CVS repository. The JDeveloper compare and merge facilities will reconcile differing versions of files automatically, or present you with a tool for doing so manually if there are serious conflicts.

You may want to ensure that a file is worked on only by you, until you have finished working on it. This might be because a file is in binary format and therefore inherently difficult to merge. In this case, you can lock the file that you want to work on. The file is locked in the CVS repository, and other users are prevented from accessing it. When you want to let others work on the file, you unlock it.

To lock files in CVS:

  1. With the file or files that you want to lock selected in the Applications window, choose Team > CVS> Administration > Lock.

  2. Check that you want the operation to apply to all of the files highlighted in the file selection box.

  3. Click OK.

To unlock files in CVS:

  1. With the file or files that you want to lock selected in the Applications window, choose Team > CVS> Administration > Unlock.

  2. Check that you want the operation to apply to all of the files highlighted in the file selection box.

  3. Click OK.

6.5.10.3 Editing Files in Perforce

By default, you can start editing a file under Perforce control just by opening it from the Applications window, without explicitly locking the file. While the Perforce server is being contacted, you may experience a delay before you can type into the opened file. If you would prefer files to remain closed until you manually open them for editing, set the Automatically Open Files for Edit preference to off. The following procedure works whichever way the preference is set.

To edit a file under Perforce control:

  1. Select the file in the Applications window and choose Team > Open for Edit.

    The Open Files for Edit dialog is displayed with the file listed.

  2. If the file is out of date with the controlled version and you wish to edit the controlled version, check the Sync files to box.

    If you do not obtain the controlled version before editing the file, you may create a conflict between your file and the version in the Perforce depot. You will then have to resolve the conflict before your changes can be accepted into the controlled version.

  3. If you wish to lock the file, check the Lock Files box.

    Locking a file means that others can edit the file but cannot submit the file until the person who applied the lock has released it.

  4. To make the file editable under Perforce control, click OK.

    The file will be indicated to Perforce as editable. A red check mark is added to the file's icon in the Applications window.

  5. To edit the file, choose Open from the file's context menu.

  6. Make your changes and save the file.

    You can also close the file if you wish.

The changes that you made to the file are now saved in your Perforce client workspace. To add your changes to the controlled version of the file and make them available to other users, you must now submit them.

6.5.10.4 Checking Out Files in Team System

Use to check out files so that you can work on them. The files must already by under Team System source control.

To check out files:

  1. In the Applications Navigator, select the application, project or file that you want to check out.

  2. Select Team > Check Out.

    The Check Out dialog is opened.

  3. Complete the dialog.

    For information while using the dialog, press F1.

6.5.10.5 Viewing the Status of a File in Team System

Use this procedure to check the status of a file that is under Team System source control. See also Section 6.5.10.6, "Refreshing the Status of Files in Team System."

To view the status of a file:

  1. With the file selected in the Applications window, open the context menu and select Team > Properties.

  2. Select the Versioning tab.

The status labels shown are those used by Team System to describe the source control status of the file.

The main statuses are:

  • Edited - In JDeveloper, the file is checked out and may have been modified.

  • Unchanged - In JDeveloper, the file is currently checked in.

  • Scheduled for addition - In JDeveloper, the file has been added (that is, brought under source control) but not yet checked in.

6.5.10.6 Refreshing the Status of Files in Team System

The source control status of a file is indicated in the JDeveloper navigators by icon overlays, as below.

Table 6-4 File status icons in Team System

Icon Description

Checked in

The object is checked in and must be checked out before it can be modified.

Checked out

The object is checked out and can be modified.

Unadded

The object is not under source control.

File added

The file has been brought under source control but has not yet been checked in to the Team System server.

scheduled for removal

The object has been scheduled for removal from the Team System server the next time it is checked in.


To refresh the status of files in JDeveloper:

  • Select View > Refresh.

6.5.11 How to Check In Changed Files

Checking in, sometimes called committing, is the process by which the changes you have made to your local file version are uploaded to the central repository. The following sections outline the procedures used by the various version control systems in use with JDeveloper.

6.5.11.1 Committing Files to the Subversion Repository

Once you have made edits and revisions to your working files, you return them to the Subversion repository.

Use these procedures to bring the Subversion repository up to date with the latest version of the files you have been working on, at the same time adding any new files to or removing any unwanted files from the Subversion repository.

You can perform the commit operation on individual files, or in the context of a working copy.

If an individual object that you want to commit has uncommitted parent objects, you must first commit the parent objects. An alternative is to commit the working copy that the objects are part of, in which case all the uncommitted objects will be committed.

You can also use change sets to manage groups of files, which can help ensure that you commit all files pertaining to a particular sub-project or task within the overall application.

To commit individual files shown in the Applications window or the Pending Changes window:

  • Select the file(s) and choose Team > Commit.

    The Commit Resources dialog is displayed with any files listed. Set the options on the Commit Resources dialog as required.

    To obtain more information about the options, press F1 or click Help. To commit the listed file or files to the Subversion repository, click OK.

To commit a working copy from the Applications window:

  1. Select a navigator node or file that is part of the working copy.

  2. Select Team > Commit Working Copy.

To obtain more information about the options, press F1 or click Help. To update the Subversion repository with the content of the working copy, click OK.

When you use Commit Working Copy, all the files in your checked out working copy will be committed, regardless of which node you have active in your application in the JDeveloper Applications window. The alternative is to select Commit. This will only commit the folder or file (and any child folders and files) that you have selected in the Applications window.

Additionally, you can commit a working copy from the Pending Changes window.

To commit a working copy from the Pending Changes window:

  1. Put the Pending Changes window into Outgoing Changes mode.

    To obtain more information about the Pending Changes window, press F1 or click Help.

  2. Select a file from the working copy that you wish to commit.

  3. Select Team > Commit Working Copy.

6.5.11.1.1 Saving Work Item ID with the Oracle Team Productivity Center Extension

If you are using Oracle Team Productivity Center, the work item ID will automatically be saved as a tag in the comment dialog when you commit.

6.5.11.2 Committing Changes to the Git Repository

There are two options for committing your changes to the Git repository: selecting an individual file to commit, or committing all files at once.

To commit an individual file:

  1. Select the file you wish to commit.

  2. Select Team > Git > Commit. This opens the Save Files dialog. Click OK to continue. This opens the Commit dialog.

  3. If your team uses comment templates (for example, to make it simpler to track issues automatically in a bug-tracking system), select the template or add a comment. Otherwise, click OK to commit the file to the repository.

To commit all files in a project:

  1. Select the project whose files you wish to commit.

  2. Select Team > Git > Commit All. This opens the Save Files dialog. Click OK to continue. This opens the Commit All dialog.

  3. If your team uses comment templates (for example, to make it simpler to track issues automatically in a bug-tracking system), select the template or add a comment. Otherwise, click OK to commit the files to the repository.

6.5.11.3 Committing Changes to CVS

Use these procedures to update the CVS repository with the latest version of the files you have been working on, and to add any new files to or remove any unwanted files from the CVS repository.

You can perform this on a single file, or in the context of a project. When in the context of a project, JDeveloper determines which files have changed since they were last committed and displays them as a list.

If you select a project to be committed that includes files that are not yet part of CVS version control, the Add Files to CVS message dialog will open. To obtain information about using this dialog, press F1.

You can view the current contents of the CVS repository through the CVS Navigator. The nodes under CVS unfold to reveal the structure and file content of the CVS repository. You can open a read-only version of a CVS repository file by choosing Open from its context menu. This will let you see what changes have been made to the files in the CVS repository since you checked out or updated your local versions.

To commit individual files shown in the Applications window:

  1. Select the file(s) in the Applications window, and then choose Team > Commit.

    The Commit to CVS dialog is displayed with the file(s) listed.

  2. Set the options on the Commit to CVS dialog as required.

    To obtain more information about the options, press F1 or click Help.

  3. To update the listed file(s) in the CVS repository, click OK.

To commit the contents of project folders shown in the Applications window:

  1. Select the project folder(s) in the Applications window and, from the context menu, choose Versioning > Commit Project Folders.

    If there are files in the project that are not under CVS control, you will be asked whether you want to add them.

    The Commit to CVS dialog is displayed with the folder(s) listed.

  2. Set the options on the Commit to CVS dialog as required.

    To obtain more information about the options, press F1 or click Help.

  3. To update the listed file(s) in the CVS repository, click OK.

To commit files shown in the Pending Changes window:

  1. With the Pending Changes window in Outgoing Changes mode, select the files that you want to commit.

    To obtain more information about the Pending Changes window, press F1 or click Help.

  2. Click the Commit button.

6.5.11.4 Submitting Changed Files to the Perforce Depot

Any changes that you make to a file are initially saved in your Perforce client workspace. To add these changes to the controlled version of the file and make them available to other users, you must submit them. In the following procedure, if the Submit menu option is unavailable, it is because there are unresolved conflicts between your copy of the file and the one in the Perforce depot. Before proceeding, you will have to resolve the conflicts or revert the file to a non-conflicting version.

To submit changes to the Perforce depot:

  1. With the file selected in the Applications window, choose Team > Submit.

    The Submit Files dialog is displayed with the file listed.

  2. Add your versioning comments in the Comments box.

  3. To submit the files to the Perforce depot, click OK.

    The file is now shown in the Applications window with a green dot, indicating that it is up to date compared with the version in the Perforce depot.

6.5.11.5 How to Check In Files to ClearCase

When you have finished working on a file, you should check it into ClearCase.

To check in files to ClearCase:

  • Select the files in the Applications window, and choose Team > Check In.

The Check In to ClearCase dialog is displayed listing the files that you selected.

If you want to check in the files even though they are identical to the previous versions in ClearCase, check the Force Check In Where Files Are Identical box. If you do not check this box, the file may remain checked out, depending on how ClearCase handles files of that type. If the file remains checked out, you can use the Undo Checkout command to return the file to its previous checked in state.

Type comments for this checkin into the Comments box or, to use the same comments for the check in that were used for the checkout, check the Use Checkout Comments box.

To check in the listed files, click OK. The files in the list are checked in to ClearCase source control.

To check in files shown in the Checked Out Files window:

  1. Select the files in the Checked Out Files window that you want to check in. To obtain more information about the Checked Out Files window, press F1.

  2. In the button bar of the viewer, click the Check In button.

6.5.11.6 How to Check In Files to Team System

Use to check in a file to the Team System server. A checked in version of a file can be seen and worked on by other users.

To check in files:

  1. In the Applications window, select the file that you want to check in.

  2. Select Team > Check In.

    The Check In dialog is opened.

  3. Complete the dialog.

    For information while using the dialog, press F1.

6.5.12 How to Use Change Sets and Changelists

Some version control systems (notably Subversion and Perforce) use the notion of change sets or changelists to group together files which form part of a single logical group. For example, you might be adding a new feature to an application which has a number of specific files: the HTML framework which calls a JavaScript function, the JavaScript file which contains the function itself, and a set of image files which represent the various states of the button before, when and after the user clicks on it in the final application. You might choose to group all these files in a single change set, as a way of tracking them and ensuring that you commit all of them to the repository (or that you refer to all of them in your team's tracking or build software).

The following sections describe how to use change sets or changelists in the version control systems that support them.

6.5.12.1 Using Change Sets in Subversion

Change sets, or change lists, are essentially labels which can be applied to working copy files to enable group operation on each change list. The idea behind adding files to a change set is similar to sorting files into directories, but change lists can be created dynamically and the labels applied to each file, regardless of their level in the file system hierarchy. You can then address all the files in the change set as a single group. For example, if you make a single bug fix that requires editing three different files, you can add all three files to the change set and track them as a single logical unit in the JDeveloper Pending Changes window.

Subversion lets you associate files with a named change set, either manually or automatically. You make additions to the change set through the menu system; automatic additions are also possible through default association, when JDeveloper detects outgoing changes.

You can browse changes for a named change set in a view of the Pending Changes window. From there, you can manipulate the change sets, and commit associated changes to the repository.

To add a selected file to a new change set:

  • Select a file from the Pending Changes window, then select Team > Add To > New Change Set.

To add file to a change set:

  1. In the Pending Changes window, select a file to add to an existing change set and click the right mouse button.

  2. Select Add To, then choose an existing change set.

  3. Select one of the existing change sets displayed in the dialog, or select New Change Set to create a new change set containing this file.

  4. Click OK.

6.5.12.1.1 Editing Change Sets

JDeveloper creates a default, unnamed change set for each installed version control system, and uses this change set until you specify another change set as the default. You can make changes to the content and the status of individual change sets, including this default change set, by right-clicking any change set and selecting from the following:

Edit

Change the content of the selected change set.

Remove

Deletes the selected change set from Pending Changes. Does not delete the files associated with the change set.

Make Default

Makes the selected change set the default for future operations. All newly created and edited files will be made part of this change set until you either change the default or manually add the file to a different change set.

6.5.12.2 Creating a Perforce Changelist

In Perforce, changelists let you group files together to simplify operations. Once files are grouped in a changelist, you can check them out and submit them all in a single operation.

In Perforce, changes are submitted to a Perforce repository using a changelist. This lets you group changes to several files into a logical unit, and then submit this unit to the Perforce repository in one operation.

You can have more than one changelist. You may find it useful to create changelists for specific projects, for related groups of files, or for any other grouping of files that you find create a logical unit, based on the way you and your team work. You can also move files from one changelist to another.

In general, you use changelists by following this workflow: create a changelist, add files to your changelist, edit your files and submit your changelist with the edited files.

You can also browse existing changelists through the Changelist Browser. The Changelist Browser also lets you create, submit, and move files between changelists. If the submit operation fails on any file in the changelist, then the whole changelist fails. This means the Perforce repository is left in a consistent state.

A Perforce changelist lets you manipulate a number of changed files and folders in a single operation, simplifying the process when you have several files that you have been working on.

To create a Perforce changelist:

  1. From the Versioning menu, select Perforce > Create Changelist.

  2. From the Connection drop-down list, select the preferred Perforce connection (if you have more than one) for this changelist.

  3. Select the files to be added to the changelist, or click Select All to add all displayed files to this changelist.

  4. Add comments to this changelist, if desired. You can choose a previous comment (with the option of editing it if necessary), or you can select your comment template.

  5. When you have set up the changelist as desired, click OK.

6.5.12.3 How to Annotate a Perforce Revision or Changelist

Annotating a Perforce revision or changelist lets you store the Perforce revision or changelist as a comment linked to every file in the revision. When you modify these files later in Perforce, you can view the sequence of revisions or changelists to these files, as annotations to the files.

To add annotations to a changelist:

  1. From the Versioning menu, select Team > Perforce > Perforce Pending Changelists.

  2. Select the changelist to view by clicking the Use Changelist selector.

Any previous annotations will be visible in the Comments field of the changelist.

6.5.12.4 Adding Files to a Perforce Changelist

A Perforce changelist lets you manipulate a number of changed files and folders in a single operation, simplifying the process when you have several files that you have been working on. When you add files to Perforce, you can select the changelist to which these files will be added at the same time, through the Open for Add menu.

To add files to a changelist:

  1. From the Versioning menu, select Perforce > Open for Add.

  2. Select the changelist to use by clicking the Use Changelist selector.

6.5.12.5 Submitting a Perforce Changelist

Once you have made a series of edits to your files, you are ready to submit them in Perforce. If you have created a changelist, you can submit all the files on that changelist in a single operation, or select just the ones you have edited and submit them.

To select and submit the files in a changelist:

  1. From the Versioning menu, select Perforce > Submit Changelist.

  2. Enter a description of the changes you have made in the Description field.

  3. Check the files you wish to submit. Use the Select All and Deselect All buttons if required.

6.5.12.6 Using the Perforce Changelist Browser

The Changelist Browser lets you see, at a glance, the state of all the pending changelists in your Perforce repository. Each pending changelist is shown with its name, description, and contents. The default changelist is always shown at the top of the browser. Under each changelist, you can browse the files that are associated with that changelist. Additionally, the Perforce connection and client are displayed at the top of the browser.

From the Pending Changelist browser, you can create and submit changelists, move files between changelists, and refresh the browser.

To create a changelist with the Changelist Browser:

  1. From the Versioning menu, select Perforce > Create Changelist.

  2. From the Connection drop-down list, select the preferred Perforce connection (if you have more than one) for this changelist.

  3. Select the files to be added to the changelist, or click Select All to add all displayed files to this changelist.

  4. Add comments to this changelist, if desired. You can choose a previous comment (with the option of editing it if necessary), or you can select your comment template.

  5. When you have set up the changelist as desired, click OK.

To submit a changelist:

  1. From the Versioning menu, select Perforce > Submit Changelist.

  2. Enter a description of the changes you have made in the Description field.

  3. Check the files you wish to submit. Use the Select All and Deselect All buttons if required.

To move files between changelists:

  1. Click the right mouse button the file in the Changelist Browser and select Move File to Changelist.

  2. Select the changelist to which you wish to move this file, then click OK.

You can also refresh the changelist browser by pressing F1.

6.5.13 How to Use Comment Templates for Checkins

Subversion, CVS, Git, and Perforce all let you configure comment templates to be used when checking in or committing files. One popular use for a comment template is to structure the comment text in such a way that it can be read by a bug-tracking system to correlate file checkins with issues being tracked. For example, beginning a comment with the string bugtraq and then following with the issue number would make it possible to analyze comments automatically and generate a report of files and the bugs they were filed against.

The four version control systems that use comment templates all allow you to are Subversion, CVS, Git, and Perforce. The following instructions are common to all these systems.

6.5.13.1 Creating Templates

Many team environments allow the developer to enter comments when a file is checked in. These comments might include bug report numbers, dependencies on other files, or some other explanatory information to be stored in connection with the file being committed to the repository.

In particular, some teams wish to correlate checked-in files with the bugs that the files address. One way to do this is to set up a standard template for issue tracking, for example, bugtraq <bug number> where you replace <bug number> with the actual ID of the issue this file addresses, and use that as the comment to a file checkin. This way, file checkin comments can be used to correlate the edits with the issues being tracked.

JDeveloper lets you create and select templates for use with such comments. The templates are available from the Commit or Checkin menu, depending on how your version control system refers to the process of committing changes to the repository.

To create a new template:

  1. Select Tools > Preferences > Versioning > Subversion > Comment Templates.

  2. Click Add. This brings up the Add Template dialog.

  3. Type in the comment template as you wish to use it, then click OK.

The template you created will now be available to select when you commit or check in your files.

6.5.13.2 Sharing Templates

JDeveloper lets you import and export templates as text files, allowing you to share a set of templates with your team. This simplifies using the exact format that any tracking system you use will expect to see in the commit comments, and also avoids errors in formatting the template.

To import a template:

  1. From the Comment Templates page, click Import. This opens a file browser.

  2. Navigate to the directory containing the template file you wish to import and click on the file to select it.

  3. Click Open.

The template file will be imported to JDeveloper.

You can also export your templates as a file to be imported later, either by you or (if you make the file available on a shared resource) by your team members.

To export a template:

  1. From the Comment Templates page of your selected version control system, click Export. This opens a file browser.

  2. Navigate to the directory in which you wish to save your template file. Note that the default template file format is XML.

  3. Give your template file a name (for example, my_bugtraq.xml) and click Save.

The template file is now available for import to JDeveloper.

Note that if your team uses more than one version control system, you can use Export and Import to share the same templates across systems.

6.5.13.3 Selecting and Using Templates at Checkin

Many team environments require the developer to enter comments when a file is checked in. These comments might include bug report numbers, dependencies on other files, or some other explanatory information to be stored in connection with the file being committed to the repository.

JDeveloper lets you create and select templates for use with such comments. The templates are available from the Commit menu.

To select a template:

  1. From the Commit menu for your selected versioning system, click Choose a template or previous comment.

  2. Select the template from the list.

  3. If your template requires you to enter specific data (for example, a bug or enhancement tracking number), make the edits in the Comments field.

  4. Click OK.

Your file will be committed with the template you selected, plus any edits you made.

6.5.13.4 Shelving and Unshelving Team System Files

Shelving lets you save file changes in the Team System server without having to check the files in. As part of the shelving process, you can choose either to continue to work on the changed files or to remove them from view and revert to unchanged versions.

When you later want to make use of the file changes that were shelved, you can unshelve them.

If you decide you no longer want to keep changes that were shelved, you can delete the shelveset that you put them in.

To shelve a set of file changes that have not been checked in:

To shelve a set of file changes that have not been checked in:

  1. In the Applications window, select the versioned project containing the files.

  2. Select Team > Shelve.

    The Shelve dialog opens.

  3. Complete the dialog.

For information while completing the dialog, click F1.

The file changes will be shelved when you click OK.

The file icons in the Applications window will change to reflect the new file statuses, if any.

To unshelve a set of file changes:

  1. In the Applications window, select the versioned project into which you want to unshelve the file changes.

  2. Select Team > Unshelve.

    The Unshelve dialog opens.

  3. Select the shelveset name for the shelveset containing the file changes.

The file changes will be unshelved when you click OK.

Files deleted since the shelveset was created will be reinstated and the file icons in the Applications window will change to reflect the new file statuses.

To delete a shelveset:

  1. Select Team > Delete Shelveset.

    The Delete Shelveset dialog opens.

  2. Select the name of the shelveset that you want to delete.

The shelveset will be deleted when you click OK.

6.5.13.5 Deleting Team System Files

Use to delete files from your workspace and from the Team System server.

To delete a file:

  1. Select the file in the Applications window and choose Team > Delete.

    The Delete dialog is displayed with the file listed.

  2. Click OK.

    On the Outgoing tab of the Pending Changes window (Team > Pending Changes), the file will be indicated as ready for deletion: a black diagonal cross is added to the file's icon.

  3. To complete the deletion of the file, select it in the Pending Changes window and choose Team > Check In.

    The Check In dialog is opened.

  4. Add your comments, if any, and click OK.

The file is deleted from your workspace and from the Team System server.

6.6 Working with Branches and Tags

Many version control systems used with JDeveloper (notably, Subversion, Git, and CVS) use branches to keep track of development projects or streams. Branches are a useful way to separate out development when (as is often the case) your team is working on multiple releases -- for example, a patch release, a major update, and a new project -- at the same time. Tracking each of these projects as a separate branch in your version control system makes it easy to track, modify, and update each project with the correct feature set, bug fixes, and other changes, and to ensure that all members of the team are tracking the same issues on the same branch.

Tags, on the other hand, are a way of tracking collections of files that capture the state of development at a particular point. Where a branch represents a stream of development moving towards a particular release, product or version, tags are useful for tracking elements within a branch -- such as a specific bug fix that might affect multiple files in a given release.

6.6.1 How to Create Branches

Creating branches varies slightly from system to system. The following section introduces working with branches and tags in the various versioning systems which use them.

6.6.1.1 Working with Branches and Tags in Subversion

When you wish to work on files independently of the main line of development (the "trunk") you can create a branch. Using the same feature, you can also create a tag, a collection of files that captures the state of development at a particular point.

When you wish to put the work you have being doing on a branch back into the main line of development, you can start the process by using the merge revision facility. This will compare the content of two revisions and apply the differences to the current working copy. You can also use this facility whenever you wish to copy changes made in one revision to another revision.

You may want to change your working copy so that it is based on a different branch. You can do this using the switch feature, either as part of branch creation or independently.

To create a branch or tag:

  1. Ensure that you have committed your files to Subversion before continuing.

  2. In the Applications window, select a project or file that is in the line of development that you wish to branch or tag.

  3. Select Team >Branch/Tag.

  4. Complete the Branch/Tag dialog.

    For help when completing the dialog, press F1 or click Help.

To use the merge facility (that is, to compare two revisions and apply the results to the working copy):

  1. In the Applications window, select a project or file that is in the start revision (that is, the resource that is to be compared against).

  2. Select Team > Merge.

  3. Complete the Merge dialog.

    For help when completing the dialog, press F1 or click Help.

To switch the working copy to be based on another location in the repository:

  1. In the Applications window, select a project or file that is in the current working copy.

  2. Select Team > Subversion > Switch.

  3. Complete the Switch dialog.

    For help when completing the dialog, press F1 or click Help.

6.6.1.2 Creating a New Branch in Git

You can create a new, named branch of your Git repository, and optionally apply a tag tag when you create it, from the Create Branch dialog.

To create a new branch in Git:

  1. Select Team > Git > Create Branch.

  2. Enter the name for your branch or tag -- for example, the version number of the release you are working on, or the code name for the current update.

  3. Enter the branch you are using as the source for the branch you are creating. To select from available branches, click Select Branch. This places the branch name in the Branch field and greys out the Tag field.

  4. To give your new branch a tag, click Select Tag, then select from one of the available tags displayed in the Select Tag dialog.

  5. Optionally, use a specific commit ID for the source of the branch you are creating. You can either enter the commit ID by hand (or more likely, by copy and paste as the commit ID is a 40-digit hexadecimal number), or click Select Commit to choose one from a list of available IDs.

  6. When you are finished, click OK.

This creates the named branch for use with Git, and associates the selected tag with it if you choose.

6.6.1.3 Creating a New Branch in CVS

You create a new branch when you are beginning a project based on an earlier version of your code repository, such as for fixing bugs after a major release, or working on specific features for a subset of your customers.

To create a new branch:

  1. In the CVS repository, select the file or folder on which you wish to base your new branch, then click the right mouse button.

  2. Choose Branch > Branch in CVS.

  3. Type in the branch name. JDeveloper converts the branch name to the default tag for the branch, by appending _BASE to the branch name as you type it.

  4. Choose whether the branch source is the trunk or the working copy. If you select the trunk, the HEAD revision of every file is branched.

  5. Click Save.

The base tag is applied before the branch is created, allowing you to specify these versions as a merge point in future.

You can also specify that you wish to create your new branch from an existing branch, by choosing the branch to use as the base.

To create a new branch from an existing branch:

  1. Click Details.

  2. Select the desired branch from the list of existing branches.

6.6.2 How to Use Branches

Once you have created a branch, JDeveloper presents a number of methods of using it to manage and track the projects you have under version control. Typically, you check out branches at the beginning of a project involving that branch, then later you can check out the individual files that you are editing or reviewing. You may also occasionally need to delete a branch (when a project is archived, for example), and you may also need to merge a branch. These operations are described here.

6.6.2.1 Checking Out a Branch in Git

Checking out a branch in Git gives you access to the files on that branch.

To check out a branch in Git:

  1. Select Team > Git > Checkout.

  2. The Name and Location fields list the available repositories from which you can select the branch to check out. Select the repository you wish to use.

  3. Click on Select Branch to display the list of available branches in the Select Branch dialog. Expand the folders as required to locate the desired branch. Select the desired branch, then click OK.

  4. If you wish to check out content associated with a specific tag, click Select Tag, then choose the desired tag from the Select Tag dialog. When you are finished, click OK.

  5. To check out content from an existing commit, click on Select Commit, then select the desired commit from the Select Commit Revision dialog. This lists all available commits (including their 40-digit hex ID), and also displays the date and time of the commit, the ID of the team member who made the commit, and a message field if notes were added at the time of the commit. When you have selected the commit, click OK.

  6. Give the checked-out branch a name to associate with this branch, then click OK.

JDeveloper displays the branch that you have checked out, with any projects and files associated with the selected branch. You can access these files from the Application window.

6.6.2.2 Merging a Branch in Git

Note that after merging your changes from the branch into HEAD, you must still commit those changes. The changes will be available in the main repository after they have been pushed to the main repository

6.6.2.3 Using Branches in CVS

CVS lets you define branches, used when development needs to be carried out separately from the main (or trunk) branch of a project. JDeveloper gives you access to CVS branches in your repository through the Tag, Branch and Merge menu.

In CVS, you can create a separate branch when you want to carry out specific work (such as bug fixes or specialized feature development) without any impact to the main set of files, also called the trunk.

Once you have created a branch, you interact with it as normally with CVS -- check out files, commit changes, etc. You can switch back and forth between branches, and you can merge the changes you have made to your branch back into the trunk.

CVS also lets you apply tags to specific branches, or to specific files in a branch (as well as generating a new tag for the branch you create, when you create it).

Branch selection is integrated into a number of CVS functions. You can switch branches or versions for files you are editing or have checked out; you can choose tags, branches, or version dates while updating the contents of your work area, as well as while you are checking out a CVS module.

6.6.2.3.1 Switching the Branch or Version

You can switch the branch or version of a file you are editing, either from the JDeveloper Versioning menu or from the file or project's context menu.

To select a branch, version or date from the Versioning menu:

  1. From the Versioning menu, choose Tag, Branch or Merge > Switch Branch or Version.

  2. Click the chooser to display a list of branches or versions.

  3. Select the branch or version you wish to use.

  4. Optionally, click Add Date to specify a date to use.

  5. Click OK.

To select a branch, version or date from the project's context menu:

  1. Choose Team > Switch Branch or Version.

  2. Click the chooser to display a list of branches or versions.

  3. Select the branch or version you wish to use.

  4. Optionally, click Add Date to specify a date to use.

  5. Click OK.

6.6.2.3.2 How to Choose a Branch while Updating

When you are updating your content to capture the latest revisions to the repository, you have the option of branch (via its associated tag) at the same time.

To select a tag and branch while updating:

  1. From the project's context menu, choose Update Project Folders.

  2. In the Update from CVS dialog, check the box marked Use Revision, Tag or Date, then click the chooser icon.

  3. Select a tag to use.

  4. Optionally, click Add Date to specify a date to use.

  5. Check any other boxes (Overwrite Local Changes, Prune Empty Folders, etc.) that you wish to apply to the current update, then click OK.

6.6.2.3.3 Choosing a Branch While Checking Out

As with other CVS operations, tags and branches are integrated into the process of checking out a CVS module.

To choose a branch while checking out:

  1. Click the right mouse button on the content in the Versions window to bring up the context menu, then choose Check Out Module.

  2. Check the box labeled Use Revision, Tag or Date, then click the chooser to select a tag.

  3. Select a tag. Optionally, you can click the Add Date button to specify a date. When you have made your selection, click OK to close the Tags dialog.

  4. Choose any other options (Force Match, Ignore Child Folders, etc.), then click OK to close the Check Out from CVS dialog.

6.6.3 How to Create Tags

Tags give you another way of identifying content that is logically grouped in some way, typically as a subset of files within a branch (for example, a list of files associated with a particular feature set, or with a particular bug fix). Once you create tags, they can be used in a number of ways, in particular for checking out files from the version control system.

6.6.3.1 Creating Tags in Git

You are given the option of creating a new tag when you check out a branch in Git. However, you can also create a tag at any time by using the Create Tag dialog.

To create a tag in Git:

  1. Select Team > Git > Create Tag. This opens the Create Tag dialog.

  2. In the Name field, type a descriptive name for the tag you are creating (for example, Version 1.2.3 Beta Release).

  3. In the Comments field, enter any descriptive notes that can help you identify this content in the future when you are using this tag.

  4. In the Branch field, enter the branch name or click Select Branch to open the Select Branch dialog, then choose the branch on which you wish to create this tag. When you have made your selection from the Select Branch dialog, click OK to close the dialog and make you selection.

  5. If you wish to base this tag on content currently associated with another tag, click Select Tag to open the Select Tag dialog.

  6. Optionally, use a specific commit ID for the source of the tag you are creating. You can either enter the commit ID by hand (or more likely, by copy and paste as the commit ID is a 40-digit hexadecimal number), or click Select Commit to choose one from a list of available IDs.

  7. When you have entered all the information for this tag, click OK.

6.6.3.2 Creating and Assigning CVS Tags

CVS allows you to create and assign tags to content.

To assign CVS tags:

This procedure will assign symbolic tags to the local CVS revisions of selected files.

  1. In the Applications window, select a single file, a project or a workspace. If you select a project or a workspace, all the files within the project or workspace will be selected for tagging.

  2. Choose Team > Tag > Tag.

  3. Check that you want the operation to apply to all of the files highlighted in the file selection box.

  4. Enter a name for the tag in the Tag Name box.

  5. Set the other options as required. To obtain descriptions of the options, press F1.

  6. Click OK.

To view CVS tags:

This procedure will display a dialog containing information about any existing tags that have been applied to the file revision.

  1. From the context menu of the file, choose Team > Properties.

  2. Select the Versioning tab. The sticky tag, date and options (if any) are shown, as is a list of existing tags for the file revision.

To reset CVS tags:

This procedure will remove any sticky tags or dates that have been applied to the selected files and reset them to the HEAD revision.

  1. In the Applications window, select the file or files whose tags you wish to reset.

  2. Choose Team > Tag > Reset Tags.

6.6.3.3 Deleting CVS Tags

Deleting a tag does not delete the content associated with it, but if you are using tags to identify a specific project that has completed, you can delete the tag to simplify the display when you are choosing tagged content in future.

To delete CVS tags:

This procedure will delete symbolic tags from the local CVS revisions of selected files.

  1. In the Applications window, select a single file, a project or a workspace. If you select a project or a workspace, the tag will be deleted from all the files within the project or workspace.

  2. Choose Team > Tag > Delete Tag.

  3. Check that you want the operation to apply to all of the files highlighted in the file selection box.

  4. Enter the name of the tag in the Tag Name box.

  5. Click OK.

6.6.4 How to Use Tags

In Subversion, creating a tag is like creating a branch...

6.6.4.1 Using Tags in Git

You can select from an existing tag in Git and apply it to the file you have selected for the current transaction.

To select a tag in Git:

  • Select Team > Tag. Scroll through the list to find the tag you wish to apply to the selected file.

If there are more than one tags that apply to the file, hold down the Ctrl key, then select each tag that you wish to use.

6.6.4.2 Using Tags in CVS

Tags in CVS are a way of identifying branches, branch-specific content, or other content that you wish to identify and manipulate as a single logical group. You can tag files, folders, or projects. You can then later use these tags to identify branches, update files from a branch with a specific tag, and other operations.

You can select and browse tags from context menus as well as the Team > CVS > Tags menu. The availability of tags differs depending on the context of the operations you are performing on your content.

6.6.4.2.1 Adding a Tag to a Project

You can identify a project by adding a tag to it. You can then operate on this project by selecting the tag from any of the CVS menus that contain the tag chooser.

To add a tag to a project:

  1. Select the project you want to tag.

  2. Choose Team > CVS > Tag, Branch and Merge > Tag.

  3. Type the tag you want to use, or click the chooser icon to browse the existing tags.

  4. Optional: Choose Use Revision, Tag or Date, then type the tag or click the icon to browse the list.

6.6.4.2.2 Applying Tags While Updating a Project or File

You can choose and apply a tag while using the Update from CVS dialog.

To select an existing branch, version or date from the Projects view:

  1. From the project's context menu, select Team > Tag.

  2. Choose Use Revision, Tag or Date.

  3. Click the tag chooser icon.

  4. Choose a tag from the list that appears.

6.6.4.2.3 How to Delete a Tag

You can also delete a tag. Deleting a tag removes it from any resources to which you have applied it. Deleting the tag does not delete the content to which the tag was applied; it merely removes it from the list of available tags.

To delete a tag:

  1. Select Team > Tag, Branch and Merge > Delete Tag.

  2. Click the chooser icon. Choose the tag you wish to delete, then click OK.

In this context, only existing tag versions (regular non-branch tags) can be selected.

6.6.5 How to Use Properties in Subversion

6.6.5.1 Using Subversion Properties

Subversion lets you define and add properties to various levels of the elements in the Applications window: files, folders, and other resources. You can define these properties and use them as a way of tracking files or folders that have something in common. For example, you can associate a specific Subversion property with a newly added feature. Viewing all files or folders with this Subversion property lets you see all the files associated with this feature: an HTML file, a JavaScript file, a class definition file, or any other elements that are involved in adding this new feature to your application.

When you add or edit Subversion properties, the dialog lets you select or specify the following elements:

Resource file

The file (or folder or other resource) to which this property is to be applied. To change this value, select a different file or resource. Note that if you wish to add this property at the application or project folder level, edit the resource file entry so that it refers to the folder, not the file.

Property name

Select a property name from the available list, or enter a new name to create a new Subversion property. Preface the new property name with svn: to be tracked as a Subversion property.

Value string

Enter the string to be displayed with this Subversion property when you view properties. For example, you can associate a specific Subversion property with a particular bug identification number or a specific upcoming release.

Note that the Value String might differ depending on the property. For instance, consider a property named svn:externals meant to record the connection between a local file and its external URL in the SVN repository. This property's value string would be a pair of text strings, respectively showing the local directory where the external file is to be checked out and the URL to the external file in the SVN repository

Assume for this example that the resource file is D:\temp and the property name is svn:externals. The value string (a value pair) might be:

external_libs https://ukp16449.uk.oracle.com/repos/trunk/FOD/StoreFront.jar

This indicates that the file StoreFront.jar held in the Subversion repository at that URL is to be checked out to D:\temp\external_libs. If the Value String entries were held in a specific file pointed to from this property, use the Value File entry.

Value file

If you know you will be adding the same Subversion property to a number of resources in your application, you can save the value string in a text file. Click Browse to select the text file that contains the value string you wish to use.

Set property recursively

Select this if you wish Subversion to apply this property to all files and elements below the current level in the application or project hierarchy.

If your team has been using Subversion properties for some time, you can use the View Subversion Properties menu to see a list of all elements that use a selected Subversion property. You can also compare the Subversion properties between different versions.

To view a list of Subversion properties:

  1. Select an element under Subversion control from the Applications window.

  2. Select Team > Subversion > View Subversion Properties.

If your project needs a new property for tracking and managing a particular aspect (such as a new feature or a bug fix), you can also add new properties.

To add a new Subversion property:

  1. Select an element under Subversion control from the Applications window.

  2. Select Team > Subversion > Add Subversion Property.

  3. Enter the values for the property, then click OK. Refer to the following section for examples of Subversion properties and how to use them.

When you set an external property with a revision number, make sure you follow the correct format for the value string. You can use either of the following as the value string for a property of type svn:external to set the ExternalWebINF revision to 16, using the JDeveloper integrated Subversion:

ExternalWebINF -r 16 https://myserver.myteam.com/svn/repos/public-html/WEB-INFhttps://myserver.myteam.com/svn/repos/public-html/WEB-INF@16 ExternalWebInf

6.6.5.2 Viewing File and Property Status

Use this procedure to check the content status and any associated property status of a file that is under Subversion source control. You can also refresh the status of a file.

To view the status of a file:

  1. With the file selected in the Applications window, open the context menu and select Team > Properties.

  2. Select the Versioning tab.

The status labels shown are those used by Subversion to describe the source control status of content and any associated property.

The main statuses for content are:

  • added - The content has been added to source control but has not yet been committed to the Subversion repository.

  • modified - The property has been locally modified since it was copied from the repository.

  • unmodified (normal) - The property is unmodified since it was last updated from the Subversion repository.

  • conflicted - There were conflicts when the property was updated from the Subversion repository.

  • deleted - The file (content and any associated property) will be removed from the Subversion repository with the next commit action.

The main statuses for associated properties are:

  • modified - The property has been locally modified since it was copied from the repository.

  • unmodified (normal) - The property is unmodified since it was last updated from the Subversion repository.

  • conflicted - There were conflicts when the property was updated from the Subversion repository.

6.6.5.3 Resolving Property Conflicts in Subversion

Subversion allows you to create and save properties associated with folders or files. These properties have a name and a value string.

You can resolve any such conflicts using Subversion's Resolve Tree Conflicts feature.

To resolve Subversion property conflicts:

  1. In the Applications window, select the element under Subversion control that has a property conflict.

  2. Click the right mouse button, and then select Team > Subversion > Resolve Conflicts.

This displays the versions with the conflicting properties in two adjacent panes, as with the Version Compare.

To resolve the conflict, you can make changes in the Subversion Properties window.

6.7 Working with File History, Status and Revisions

One of the most useful parts of working with version control is the ability it gives you to look at the history of a file and compare changes made to different revisions. In debugging, you can look through the file history to find a version just prior to the introduction of a defect, which can help you identify where the problem occurred. If you and another team member make conflicting changes to a file or a set of files, you can go back to versions of the file from before the changes were made.

6.7.1 File History

You can refer to the history of a file in your repository to review changes made to it over the life of the project.

6.7.1.1 Viewing the History of a Subversion File

To help you understand the sequence of changes made to a specific Subversion file, you can use the History Viewer and view the history of Subversion files.

To view the history of a file:

  • With the file selected in the Applications window, choose Team > Version History from the context menu.

    For more information while using the History Viewer, press F1 or click Help.

6.7.1.2 Refreshing the Status of Files Under Subversion Control

The source control status of a file is indicated in the JDeveloper navigators (Applications window and Teams window) by icon overlays, as below.

If the status of a file is changed outside JDeveloper, for example by using a Subversion client application, the new status might not immediately be shown in JDeveloper. To ensure that the status indicated in the Applications window matches the true status of the file in the source control system, you can perform a manual refresh.

To refresh the status of files in JDeveloper:

  • Select View > Refresh.

6.7.2 How to Work with Revisions

There is another section dealing with reversion, reverting changes, etc. Consolidate -- look over both sections to see which is more sensible.

6.7.2.1 Replacing a File with the Subversion Base Revision

Use this procedure to replace a file with the base revision. The base revision is the revision from which the one you are currently working on originated.

To replace a file with the Subversion base revision:

  1. In the Applications window, select the file to be replaced.

  2. Choose File > Replace With Base Revision. The Replace With Base Revision dialog opens. Check that the file that you want to replace is shown in the dialog.

  3. To replace the file, click OK.

6.7.3 How to Undo or Revert Changes

Undo changes, revert to previous versions, selecting specific revisions: these are all commonly used phrases to describe the process of canceling changes you have decided not to check in to the repository.

6.7.3.1 Reverting Files to their Previous State in Subversion

Use the Revert command to:

  • Undo changes that you have made locally to the contents of a file.

  • Change the status of a file that has been added, but not yet committed, back to unadded.

  • Stop a file that is scheduled for removal (in the Pending Changes window) from being removed from the Subversion repository.

To revert a file:

  1. Select the file in the Applications window or Pending Changes window and choose Team > Revert.

    The Revert Local Changes dialog is displayed with the file or files listed.

    For help while using the dialog, press F1 or click Help.

  2. To revert the listed file or files, click OK.

6.7.3.2 Reverting Changes to Files in Git

You can revert changes made to a file that you have committed to a Git repository to return it to a previous state.

To revert changes:

  1. Select Team > Git > Revert. This displays a list of files that you can revert to a previous version, with the path in your local file system at which the file resides.

  2. Select the file you wish to revert, then click OK.

6.7.3.3 Working with Revisions and Tags in CVS

CVS lets you select specific revisions from the CVS repository, if you find it necessary to begin or resume working with a previous version of the file you are currently working on.

To open a CVS file revision:

This procedure will obtain a revision of a file from the CVS repository so that you can view it or save it locally.

  1. With the file selected in the Applications window, choose Team > Open Revision.

  2. Set the options on the dialog as required. To obtain descriptions of the options, press F1 or click Help.

  3. Click OK.

6.7.4 How to Merge Changes from Different Files

Many version control systems offer ways to let you merge changes from different files, ending up with a single version which contains edits from multiple team members. To begin, you will need to compare different versions of the file, then follow the procedures for selecting and merging changes.

6.7.4.1 Comparing Files in Subversion

Use these procedures to compare files that are under Subversion control with other revisions of the same files, or with other files.

To compare revisions of a file:

  1. From the context menu for the file, choose Compare With.

  2. Select either Previous Revision, Latest Revision, or Other Revision.

    If there are no differences, a message is displayed. Otherwise the revision or revisions are shown in the Compare panel of the History tool.

To compare a file with another file:

  1. From the context menu for the file, choose Compare With > Other File.

    The Select File to Compare With dialog is opened.

  2. Select the file to be compared.

    The files are shown in the Compare panel of the History tool.

To compare two files:

  1. Select the two files in the Applications window.

  2. From the context menu for one of the files, choose Compare With > Each Other.

    The files are shown in the Compare panel of the History tool.

You can hide (and later expose) the Compare panel of the History tool to view other panels in JDeveloper.

6.7.4.2 Resolving Conflicts in File Versions

If there is a conflict between your copy of the file and the one in the Subversion repository, the icon next to the affected file will include an exclamation point. You will not be able to submit such a file to the Subversion repository. To overcome this problem, you should do one of the following:

  • Revert to a non-conflicting version of the file.

  • Resolve the conflict using the JDeveloper merge tool.

  • Indicate to the Subversion control system that the conflict has been resolved (Team > Mark Resolved), even if no changes have been made (usually necessary only for binary files).

Another reason you might need to do this is if you have resolved the conflict yourself in the file, rather than using the merge tool. This might be the case if you have chosen to merge files at the server rather than the more usual solution of merging files locally.

To revert to a non-conflicting file version:

  • Select the file in the Applications window and choose Team > Revert.

To resolve the conflicts using the merge tool:

  1. Select the file in the Applications window and choose Team > Resolve Conflicts.

    The file is opened with the Merge tab displayed, showing the merge tool.

  2. Use the merge tool to resolve the conflicts.

    For help while using the merge tool, press F1 or click Help.

To indicate that the conflict has been resolved, even if no changes have been made:

  • Select the file (usually a file with binary content) in the Applications window and choose Team > Mark Resolved.

6.7.4.3 Using the Merge Tool to Resolve Conflicts

Use this procedure to merge two revisions of a file, where the revisions contain conflicting content. Conflicts are notified in the Pending Changes window: the outgoing status is "conflicts" or "conflicts on merge", and the Resolve Conflicts button is active.

To merge two revisions with conflicting content:

  1. On the Outgoing tab of the Pending Changes window, select the revision that has conflicts and click the Resolve Conflicts button. (You can also select the revision in the Applications window.)

  2. The merge tool is opened (as the Merge tab of the file editor).

    For help while using the merge tool, press F1 or click Help.

    The merge tool has three panels. The left panel contains the content of the version in the repository. The right panel contains the content of the most recent local version. The center panel contains the results of the merge. In the margins between the panels are symbols representing suggested actions to resolve each conflict.

  3. View the suggested actions for resolving the conflicts by reading the tooltip of the margin symbols.

    More suggested actions may be available from the context menus of the margin symbols.

  4. Resolve the conflicts by implementing a suggested action in each case.

    Accepting an initial suggested action may cause the appearance of additional suggested actions.

    You can also make changes to the content of the center panel by typing into it.

  5. To complete the merge, save the changes that have been made by clicking on the Save Changes button on the merge tool (not the JDeveloper Save option).

6.7.4.4 Using the Subversion Merge Wizard

The Merge Wizard is instrumental to the way that JDeveloper supports Subversion merge tracking. Merge tracking in Subversion means in essence that Subversion remembers your merges so you don't have to. The Merge Wizard provides you with an easy way of selecting which components you wish to merge, such as specific revisions, branches, or change sets.

The Merge Wizard gives you a number of options:

Merge Selected Revision Range

Select this when merging a range of revisions to another branch, for example, when you are back-porting a group of bug fixes to the release branch.

Reintegrate a branch

Normally used when merging the changes on a branch back to the trunk, for example, if you completed the work on a feature branch and want to reintegrate the changes back to trunk.

Merge two different trees

Select this to merge the differences between two branches into the working copy.

Block specific revisions from being merged

Select this if you know that specific revisions are not yet ready, or not appropriate, to be merged into the trunk.

6.7.5 Working with File Versions and History in CVS

CVS gives you techniques that allow you to merge, compare, replace, and view different versions of the files in your repository.

6.7.5.1 Merging Files in CVS

Use this procedure to merge two revisions of a file, where the revisions contain conflicting content. Conflicts are notified in the Pending Changes window: the outgoing status is "conflicts" or "conflicts on merge", and the Resolve Conflicts button is active.

To merge two revisions with conflicting content:

  1. On the Outgoing tab of the Pending Changes window, select the revision that has conflicts and click the Resolve Conflicts button.

  2. The merge tool is opened (as the Merge tab of the file editor).

    For help while using the merge tool, press F1.

    The merge tool has three panels. The left panel contains the content of the version in the repository. The right panel contains the content of the most recent local version. The center panel contains the results of the merge. In the margins between the panels are symbols representing suggested actions to resolve each conflict.

  3. View the suggested actions for resolving the conflicts by reading the tooltip of the margin symbols.

    More suggested actions may be available from the context menus of the margin symbols.

  4. Resolve the conflicts by implementing a suggested action in each case.

    Accepting an initial suggested action may cause the appearance of additional suggested actions.

    You can also make changes to the content of the center panel by typing into it.

  5. To complete the merge, save the changes that have been made, using the Save button.

6.7.5.2 Comparing Files in CVS

Use these procedures to compare revisions of files that are under CVS source control. You can compare a file with its immediate predecessor, or you can compare with any of the file's previous revisions.

To compare a file shown in the Applications window:

  1. From the context menu for the file, choose Compare With.

  2. Select either Previous Revision, Head Revision or Other Revision.

  3. If you are comparing with previous revisions, these are listed in the Compare CVS File dialog: Select the file that you want to compare with.

    If there are no differences, a message is displayed. Otherwise the Compare tool is displayed.

To compare a file shown in the Pending Changes window:

You can compare a file in the Pending Changes window either with a previous revision or with the HEAD revision, depending on which mode the window is in. To obtain more information when using the Pending Changes window, press F1.

  • With the window in Outgoing Changes mode, select the file to be compared, then select the Compare with Previous Revision button.

  • With the window in Incoming Changes mode, select the file to be compared, then select the Compare with Head Revision button.

If there are no differences, a message is displayed. Otherwise the Compare tool is displayed.

6.7.5.3 Replacing a File with a CVS Revision

Use this procedure to replace a file with the base or head revision, or with a file with a specific revision number or tag. The head revision is the latest one. The base revision is the revision from which the one you are currently working on originated.

To replace a file with a CVS revision:

  1. In the Applications window, select the file to be replaced.

  2. Do one of the following:

    • To replace with the base revision, choose File > Replace With > Base Revision. The Replace With Base Revision dialog opens.

    • To replace with a specific revision number or tag, choose File > Replace With > Tagged Revision. The Replace With Tagged Revision dialog opens.

    • To replace with the head revision, choose File > Replace With > Head Revision. The Replace With Head Revision dialog opens.

  3. Check that the file that you want to replace is shown in the dialog.

  4. When replacing with a specific revision number or tag, enter the revision number or tag into the text box on the dialog.

  5. To replace the file, click OK.

6.7.5.4 Viewing the History and Status of a File in CVS

The history and status of a file will tell you what has been done to it, and what has been done to it last. This can help you make the determination of what you need to do to bring the file up to date, or to begin making your own modifications.

Use this procedure to open the History Viewer and view the history of CVS files.

To view the history of a project or file:

  • With the project or file selected in the Applications window, choose Team > Version History from the context menu.

    For more information while using the History Viewer, press F1.

Use this procedure to check the status of a file that is under CVS source control. You can also refresh the status of files under CVS control.

To view the status of a file:

  1. With the file selected in the Applications window, open the context menu and select Team > Properties.

  2. Select the Versioning tab. The status of the file is the first item on the tab.

Possible statuses are:

  • Changed locally - the file has been locally modified since it was copied from the repository.

  • Changed in repository - the file has been modified by another user since it was copied from the repository.

  • Locally removed - the file will be removed during the next commit.

  • Locally added - the file will be added during the next commit.

  • Up-to-date - the file is up-to-date with the latest CVS repository revision.

  • File has conflicts - these may have resulted from a file update or commit action. If necessary, consult your CVS administrator for assistance.

  • Needs merge or needs patch - the file has been updated externally, for example, by another user.

  • Modified - the file previously had merge conflicts, but the timestamp has changed since.

6.7.6 Working with File Versions in Perforce

Perforce provides tools for resolving conflicts in file versions.

6.7.6.1 Resolving Conflicts in Perforce File Versions

If there is a conflict between your copy of the file and the one in the Perforce depot, the icon next to the affected file will include an exclamation point. You will not be able to submit such a file to the Perforce depot. To overcome this problem, you should either revert to a non-conflicting version of the file, or resolve the conflict.

To revert to a non-conflicting file version:

  • Select the file in the Applications window and choose Team > Revert.

To resolve conflicting file versions (assumes use of Perforce merge tool):

  1. Open the Perforce client by choosing Team > Resolve.

  2. In the pending changelists for the client, identify the change.

  3. Resolve the conflict using the Perforce tools.

    If you cannot automerge the conflicts, run the merge tool and use its facilities to create a definitive version from the conflicting data.

  4. Accept the merge.

  5. Submit the merge.

  6. In JDeveloper, use View > Refresh to obtain the green dot on the file.

    The file will still be marked as open for edit.

  7. Submit the file.

6.7.7 Working with File Versions in Team System

Team System provides tools for working with file versions, including viewing, comparing, and resolving conflicts among different files in the repository.

6.7.7.1 Resolving Conflicts in Team System File Versions

If there is a conflict between your copy of the file and the one in the Team System server when you attempt to check it in, you will see a message box saying that the operation cannot be completed. To overcome this problem, you must first cancel the check-in operation, then do one of the following:

  • Revert to a non-conflicting version of the file.

  • Resolve the conflict using the merge tool in the Team System client software.

To revert to a non-conflicting file version:

  • Select the file in the Applications window and choose Team > Undo.

6.7.7.2 Undoing Changes to Team System Files

Use to undo the most recent change to a file.

To undo changes:

  1. In the Applications window, select the file whose last change you want to undo.

  2. Select Team > Undo.

    The Undo dialog is opened.

    The change will be undone when you click OK.

6.7.7.3 Replacing a File with the Team System Base Version

Use this procedure to replace a file with the base version. The base version is the version from which the one you are currently working on originated.

To replace a file with the Team System base revision:

  1. In the Applications window, select the file to be replaced.

  2. Choose File > Replace With > Base Version.

    The Replace With Base Version dialog opens.

  3. Check that the file that you want to replace is shown in the dialog.

  4. To replace the file, click OK.

6.7.7.4 Viewing the History of a File

Use this procedure to open the History Viewer and view the history of files held under Team System control.

To view the history of a file:

  • With the file selected in the Applications window, choose Team > Version History from the context menu.

For more information while using the History Viewer, press F1.

6.7.7.5 Comparing Files In Team System

Use these procedures to compare files that are under Team System control with other versions of the same files, or with other files.

To compare versions of a file:

  1. From the context menu for the file, choose Compare With.

  2. Select either Previous Version, Latest Version or Other Version.

If there are no differences, a message is displayed. Otherwise the version or versions are shown in the History tool.

To compare a file with another file:

  1. From the context menu for the file, choose Compare With > Other File.

    The Select File to Compare With dialog is opened.

  2. Select the file to be compared.

    The files are shown in the Compare tool.

To compare two files:

  1. Select the two files in the Applications window.

  2. From the context menu for one of the files, choose Compare With > Each Other.

The files are shown in the Compare tool.

6.7.8 How to Display the History of a ClearCase File

Use this procedure to display the history of a file that is under ClearCase source control.

To display the history:

  • With the file selected in the Applications window, choose Team > View History.

6.7.9 How to Display the Description of a ClearCase File

Use this procedure to display the description of a project or a file that is under ClearCase source control.

To display the description:

  • With the file selected in the Applications window, choose Team > View Description.

The description appears in the Messages Log window.

6.7.10 How to Use External Diff Tools

CVS allows you to use an external tool to view, locate and resolve differences in file versions.

6.7.10.1 Using an External Diff Tool with CVS

JDeveloper has an integrated compare viewer that works well for most circumstances. However, you may prefer to use another compare tool or the simple output from CVS DIFF. JDeveloper lets you integrate third party tools and applications. This procedure describes how to use the External Tools support in JDeveloper to integrate external compare viewers.

To integrate CVS DIFF:

  1. In JDeveloper, select Tools > External Tools.

  2. Click Add. This opens the Create External Tool wizard.

  3. On the External Program Options page, enter the following information:


    Program Executable
    The location of your CVS installation (for example c:\cvsnt\cvs.exe) or just cvs

    Arguments
    -d ${cvs.root} diff ${file.name}

    Alternate arguments
    -d ${cvs.root} diff -r ${cvs.revision} -r ${cvs.second.revision} ${file.name}

    Run Directory
    ${file.dir}

    Enter the alternate arguments if you want to integrate a tool that compares two specific CVS revisions when the history tool is visible.
  4. On the Display page, enter a caption for the diff tool (for example CVS Diff with Repository) in the Caption for Menu Items box.

  5. On the Integration page, choose how you want the diff tool to be integrated into JDeveloper. For example, select the Tools Menu, Navigator Context Menu, and Code Editor Context Menu items.

  6. On the Availability page, select When a File is Selected or Open in the Editor.

  7. Click Finish.

To integrate a third party diff utility:

You can use external tools macros to view differences between two revisions in the history tool using a third party utility such as Araxis Merge. The following steps will install a menu item to invoke Araxis Merge. For other utilities, consult the documentation of the utility to determine which command line arguments need to be passed in.

  1. In JDeveloper, select Tools > External Tools.

  2. Click Add. This opens the Create External Tool wizard.

  3. On the External Program Options page, enter the following information:


    Program Executable The path to the third party tool (for example c:\araxismerge\compare.exe)

    Arguments
    /wait /title1:"${file.name} revision ${cvs.revision}" /title2:"${file.name} revision ${cvs.second.revision}" /2 ${cvs.revision.file} ${cvs.second.revision.file}
  4. On the Display page, enter a caption for the third party tool (for example Araxis Diff) in the Caption for Menu Items box.

  5. Complete the remainder of the wizard as required. For help when using the wizard, press F1 or click Help.

  6. Click Finish.

To integrate other CVS commands:

You can take advantage of the supplied external tool macros to easily integrate other CVS commands into JDeveloper. An example is the CVS annotate command (sometimes referred to as ”blame”), which shows a summary of who changed each line of code and when the change was made. To integrate a tool for CVS annotate, set the following options in a new tool:

  1. In JDeveloper, select Tools > External Tools.

  2. Click Add. This opens the Create External Tool wizard.

  3. On the External Program Options page, enter the following information:


    Program Executable
    The path to the CVS executable (for example, C:\cvs\cvs.exe)

    Arguments
    -d ${cvs.root} annotate ${file.name}

    Run Directory
    ${file.dir}
  4. Complete the remainder of the wizard as required. For help when using the wizard, press F1 or click Help.

  5. Click Finish.

6.8 Working with Patches in Source Control

Many of the version control systems available in JDeveloper provide features for creating and applying patches—methods for determining changes between two revisions of a file, and then applying those changes to a third file. In addition, Subversion contains features for exporting the details about repository connections, as well as files in the repository.

Subversion (included in JDeveloper) uses the following procedures for creating and applying patches. In addition, the version control extensions for Concurrent Version System (CVS), Perforce and Team System all use the same steps for creating and applying patches.

To create a patch:

This generates a patch comprising the differences between a controlled revision of a file and a revision of the file held locally.

  1. In JDeveloper, open the file for which you want to create a patch.

  2. Click the History tab.

    The History view lists all the revisions of the file. In the lower portion of the History view, the left pane shows the contents of a local revision, and the right pane shows the contents of the controlled revision.

  3. Select the revision combination for which you want to create a patch.

  4. From the context menu, choose Generate Patch.

    The Select Patch Context dialog may open. For help while using this dialog, press F1 or click Help.

    The Generate Patch dialog opens. Complete the dialog as required. For help while using the dialog, press F1 or click Help.

To apply a patch:

  1. In the Applications window, select the resource to which you want to apply a patch.

    The resource can be an application, a project, or a source file.

  2. Select Team > Apply Patch.

    If you chose to apply a patch to a project, the Select Patch Context dialog opens, through which you should specify whether you are applying a project file (.jpr) patch, or whether you are updating the contents of a project.

    The Apply Patch dialog is opened.

  3. In the grid at the top of the Apply Patch dialog, check that the target resources are correctly identified.

  4. Choose the source of the patch. For more information about this and the other options on the dialog, press F1 or click Help.

  5. Click Preview. This opens the Apply Patch Preview window, in which you can accept or reject particular changes. For more information about the options in the Apply Patch Preview window, press F1 or click Help.

  6. To apply the patch, click OK.

6.8.1 How to Create and Apply Patches

JDeveloper provides features for creating and applying patches—methods for determining changes between two revisions of a file, and then applying those changes to a third file. You can typically save these patches either as a separate file, or as a section of text to be copy-and-pasted into the target file.

6.8.1.1 Creating Patches

You may wish to record the changes between two revisions of a file, then apply those changes to a third file. You do this by creating a patch and then applying it.

To create a patch:

This generates a patch comprising the differences between a controlled revision of a file and a revision of the file held locally.

  1. In JDeveloper, open the file for which you want to create a patch.

  2. Click the History tab.

    The History view lists all the revisions of the file. In the lower portion of the History view, the left pane shows the contents of a local revision, and the right pane shows the contents of the controlled revision.

  3. Select the revision combination for which you want to create a patch.

  4. From the context menu, choose Generate Patch.

    The Select Patch Context dialog may open. For help while using this dialog, press F1 or click Help.

    The Generate Patch dialog opens. Complete the dialog as required. For help while using the dialog, press F1 or click Help.

6.8.1.2 Applying Patches

Once you have created a patch, you apply it from the Team menu.

To apply a patch:

  1. In the navigator, select the resource to which you want to apply a patch.

    The resource can be an application, a project, or a source file.

  2. Select Team > Apply Patch.

    If you chose to apply a patch to a project, the Select Patch Context dialog opens, through which you should specify whether you are applying a project file (.jpr) patch, or whether you are updating the contents of a project.

    The Apply Patch dialog is opened.

  3. In the grid at the top of the Apply Patch dialog, check that the target resources are correctly identified.

  4. Choose the source of the patch. For more information about this and the other options on the dialog, press F1 or click Help.

  5. Click Preview. This opens the Apply Patch Preview window, in which you can accept or reject particular changes. For more information about the options in the Apply Patch Preview window, press F1 or click Help.

  6. To apply the patch, click OK.