Chapter 1. Setting Up and Managing a Repository for Your Projects

1.1. Using Git with Red Hat JBoss Developer Studio

The IDE includes the Git Perspective to allow developers to create, add, and manage their Git repositories quickly and easily with a graphical interface. This article introduces the basic workflow of a Git project and how to accomplish the most common Git-related tasks via the Git perspective. Common Git-based tasks include:

1.1.1. Setting Up the Git Perspective

Use the following instructions to locate the Git Perspective in the IDE:

  1. In the menu bar at the top of the page, click WindowPerspectiveOpen PerspectiveOther.
  2. From the list of available perspectives, select Git and click OK.

Result: The Git Repositories view appears on the upper left side of the window.

1.1.2. Setting up a Repository in the Git Perspective

The first step to using the Git Perspective in the IDE is to set up a Git repository. There are three ways to set up a Git repository in the Git Perspective:

The most common use case for developers is to clone an existing repository, or import an existing local clone of a repository into the IDE. However, the first option is an easy way to create a full repository (bare or normal) from scratch.

1.1.3. Creating a New Git Repository

If a repository is not already created and available, use the following steps to create a new repository:

  1. Click the Create a new Git Repository and add it to this view button.

    Figure 1.1. Click the Create a New Git Repository Button

    Click the Create a New Git Repository Button
  2. In the dialog box:

    1. Ensure that the automatically populated default value for the Repository Directory field is correct.
    2. Optionally, if required, check the Create a bare repository to create a new bare repository. For details about bare repositories and how they differ from a normal repository, see the Did You Know? section.

      Figure 1.2. Create a New Git Repository

      Create a New Git Repository

      Result: A new git repository is created on your local machine and is listed in the Git Repositories view.

1.1.4. Cloning an Existing Git Repository

If your repository already exists online (for example, in GitHub), use the following steps to create a local clone:

  1. Ensure that you have forked the repository online. This option is available in the repository host’s website.
  2. Click the Clone a Git Repository and add the clone to this view button.

    Figure 1.3. Click the Clone a Git Repository Button

    Click the Clone a Git Repository Button
  3. Enter the details of the source repository as follows:

    1. Add the URI for the repository’s online source. This automatically populates the Host and Repository Path fields.
    2. Add your username and password for the source repository under the Authentication details.
    3. Click Next to continue.

      Figure 1.4. Enter the Source Repository Details

      Enter the Source Repository Details
  4. Customize the local version of your Git repository as follows:

    1. Confirm that the automatically populated information for the destination Directory and Initial Branch are correctly populated.
    2. Optionally, set a non-default name for the Remote name field.
    3. Optionally, select the Add project to working sets option and use the drop down menu and the Select button to select the appropriate working sets for this repository.

      Figure 1.5. Customize the Local Version of the Git Repository

      Customize the Local Version of the Git Repository
    4. Click Finish to conclude cloning an existing Git repository.

Result: The new cloned repository is listed in the Git Repositories view.

1.1.5. Adding an Existing Local Git Repository

If you have already cloned a Git repository locally, the following instructions are necessary to add your Git repository to the IDE. If you have not yet cloned your repository, follow the instructions in the prerequisites section below:

1.1.5.1. Prerequisites

  1. Ensure that you have forked the repository online.
  2. In the command line on your local system, navigate to the location where you want to store the local copy of the repository and enter the following command to clone the repository:

    $ git clone ${repo_URL}

1.1.6. Adding an Existing Git Repository

Use the following instructions to add your existing local Git Repository to JBoss Developer Studio’s Git Perspective:

  1. Click the Add an existing local Git Repository to this view button.

    Figure 1.6. Click the Add an Existing Local Git Repository Button

    Click the Add an Existing Local Git Repository Button
  2. Select the local Git Repository as follows:

    1. Click Browse to navigate to the local directory that contains the Git repository.
    2. Optionally, select the Look for nested repositories checkbox to search for nested repositories.
    3. In the Search results box, ensure that the appropriate .git file is selected.

      Figure 1.7. Find and Add Local Repository

      Find and Add Local Repository
    4. Click Finish.

Result: The local repository now appears in the Git Repositories view.

1.1.7. Adding a Remote for the Repository

After setting up your repository for the first time, set up a remote for repository. This is a one-time set up step for newly created or added repository.

  1. In the Git Repositories view, expand the target repository.
  2. From the expanded options, right-click Remotes and then Create Remotes.
  3. In the New Remote dialog box:

    1. Add a name in the Remote name field.
    2. Ensure that the Configure Push radio button is selected.
    3. Click OK to continue.
  4. In the Configure Push dialog box:

    1. Click Change to view the Select a URI dialog box.
    2. Add the URI to your repository in the URI field. This automatically populates the Host and Repository path fields.
    3. Add your repository username and password in the Authentication section of the dialog box and click Finish to continue.
  5. Click Save to save your push configuration settings.

Result: Expand the Remotes folder in the repository view to see the newly added remote.

1.1.8. Creating and Working With a New Branch

This section provides instructions for creating a new branch and common tasks with the new branch, such as:

1.1.9. Creating a New Branch

If your repository is already set up in the IDE, create a new branch to make changes to the files.

  1. In the Git Repositories view:

    1. Expand the name of your Git Repository.
    2. Click Branches to expand the branch view.
    3. Click Remote Tracking to view all remote branches for the repository.
    4. A branch displays with a name that begins with origin/master. Right-click this branch and select Create Branch from the displayed options.

      Figure 1.8. Create a Branch from Origin/Master

      Create a Branch from Origin/Master
  2. Add the required details about the new branch:

    1. Add the desired new branch name in the Branch name field.
    2. Ensure that the Configure upstream for push and pull checkbox is selected.
    3. In the When doing a pull options, select the option that suits your requirement. The Merge upstream commits into local branch option creates commits when a merge occurs. These commits are included in the subsequent pull request. The Rebase commits of a local branch onto upstream option performs a rebase before adding your changes, which prevents additional commits in your pull request.
    4. Ensure that the Checkout new branch check box is selected.

      Figure 1.9. Add Details for a New Branch

      Add Details for a New Branch
    5. Click Finish to create the new branch.

Result: The new branch appears under Repository_NameBranchesLocal.

1.1.10. Working in the New Branch

After creating a new branch, you can implement changes in the new branch as follows:

  1. Expand Repository_NameBranchesLocal and find the new branch where changes are to be implemented.
  2. Confirm that the target branch is checked out. The currently checked-out branch displays a small black check mark:

    Figure 1.10. An Example of a Checked-out Branch

    An Example of a Checked-out Branch
  3. Right-click on the checked-out branch name and mouse-over the Show In option in the menu and then click Terminal in the submenu.

    Figure 1.11. The Show Branch in Terminal Option

    The Show Branch in Terminal Option
  4. On the right view, a Terminal tab appears. In the same row, click the icon that resembles a computer monitor to view the command line prompt in this view.

    Figure 1.12. The Open a Terminal Button

    The Open a Terminal Button
  5. In the Launch Terminal dialog box:

    1. Ensure that Local Terminal is selected in the Choose a Terminal drop-down box.
    2. Select Default (ISO-8859-1) in the Encoding box.
    3. Click OK. Note that as a default, the terminal window is at the /home/YourCurrentUser/ directory.

Result: The Terminal tab now displays a command line terminal. Use the terminal view to make the required changes to your checked-out files.

1.1.11. Updating the Branch Before Implementing Changes

When working locally on a branch, it is better to ensure the local branch is up to date before creating a pull request (PR). As an example, if someone else has checked out the same repository and created a new branch, made changes, and merged the changes, use the following procedure to update your repository and branch before committing your own changes.

In the example below, a new branch called TrackingID-1234 is created using the IDE. Assuming that someone else is working on the same repository and has created a new branch called NEWBRANCH, made changes to it, and then merged the changes back into the repository. The local branch (TrackingID-1234) is now out of date because it does not include the changes from NEWBRANCH. Use the following instructions to update the branch:

  1. Right-click the name of the repository to update.
  2. From the menu that displays, click Pull.
  3. A status menu appears that displays the progress of the pull request.
  4. When the pull completes, a Pull Result for Repository_Name menu appears that lists the results of the fetch and update operations.
  5. Click OK to conclude the operation.

Result: The repository now contains the most updated version of the contents.

1.1.12. Commiting and Merging Changes

After all required changes are complete, commit the changes and then create a Pull Request. Pull Requests are then evaluated by the repository owner and either merged into the repository or rejected.

  1. Ensure that the black and white tick mark that indicates the current branch appears at the correct working branch in the Local folder of your repository view.
  2. Right-click the name of the repository. In the displayed menu, click the Commit option.
  3. In the Commit Changes dialog box:

    1. Add a commit message describing the changes in the Commit message text box.
    2. Confirm that the automatically populated Author and Committer fields contain the correct name and email address.
    3. In the Files area, all files added using the git add command display in the box. Select the checkbox next to each file to include it in the commit. See the Did You Know? section to learn about only including some of the changed files in a commit.

      Figure 1.13. Add details to the Commit Changes Dialog Box

      Add details to the Commit Changes Dialog Box
    4. Click Commit to create a new commit (without creating a Pull Request) or click Commit and Push to commit the changes and create a Pull Request at the same time.

1.1.13. Committing Without Pushing the Changes

If you selected Commit in the previous procedure to commit changes but not push them, use the following instructions:

  1. When the operation completes, the repository is now ahead by one commit. This is represented with an arrow and the number one:

    Figure 1.14. Git Repository Status

    Git Repository Status
  2. When you are ready to create a Pull Request, right click the current branch name and click Push Branch.
  3. An automatically populated Push Branch Branch_Name dialog box appears. Confirm that the settings are correct. The settings selected when creating this branch are used for this step. Click Next to continue.
  4. A dialog box appears requesting the repository access username and password.
  5. A Push Confirmation dialog box appears. Click Finish to create the Pull Request. If requested, supply the username and password for the repository once again.
  6. When the operation completes, a Push summary dialog box appears. Click OK to dismiss this dialog box.

Result: The included changes are now committed and a Pull Request is generated for the repository owner to review.

1.1.14. Committing and Pushing the Changes

If you selected Commit and Push in the previous procedure, use the following instructions:

  1. A dialog box appears requesting the repository access username and password.
  2. When the operation completes, the repository is now ahead by one commit. This is represented with an arrow and the number one:

    Figure 1.15. Git Repository Status

    Git Repository Status
  3. After the Pull Request is evaluated and merged, right-click the repository and click Pull to manually update the repository.

Result: A Pull Request is generating and ready for the repository owner to review.

1.1.15. Did You Know?

  • Bare repositories are recommended for central repositories, but not for development environments. Bare repositories differ from normal repositories because they do not contain a working or checked out copy of any source files. This prevents editing files and committing changes in the repository. Additionally, they store the git revision history for your repository in the repository’s root folder instead of in a .git sub-folder.
  • When selecting the files to commit in the Commit Changes, you can select only the files you want included in the commit using the checkboxes next to each file name. The unchecked files are not included in the commit and no extra actions are required to reconcile the uncommitted files when committing and creating a Pull Request.
  • If you need to add a change ID to each commit message, in the Comming Changes dialog box, click the rightmost icon at the top right corner to add a change ID to the commit message.

1.2. Configuring Maven Basics

In the context of application development, Maven provides a standardized build system for projects. One of the main benefits of using Maven with your project is that it facilitates fetching dependencies from one or more repositories. This article serves as an introduction to using Maven with the IDE and contains instructions for the following tasks:

Root Maven projects can serve as aggregators for multiple Maven modules, also known as sub-projects. For each module that is part of a maven project, a <module> entry is added to the project’s pom.xml file. A pom.xml that contains <module> entries is often referred to as an aggregator pom.

When modules are included into a project it is possible to execute Maven goals across all of the modules by a single command issued from the parent project directory.

Note

Note that the provided instructions pertain to the creation of a parent+module project structure. If you prefer to create just a simple project, simply start with an archetype or don’t use the pom packaging in step 2.a.

1.2.1. Creating a New Maven Project

Use the following instructions to create the parent project of a multi-module Maven project. The instructions provided ensure that the packaging option is set to pom, which is a requirement for multi-module Maven projects. Alternately, to create a standalone Maven project instead, set the packaging option to an option other than pom.

  1. Create a new project:

    1. In the workspace, navigate to FileNewOther.
    2. Type maven in the Filter field and select Maven Project.
    3. Click Next to continue.
  2. Enter the initial project details:

    1. Check the Create a simple project (skip archetype selection) check box. If this check box is selected, the Select an Archetype step of the wizard is skipped and the project type is set to pom, which is required to create a Maven Module based on this Maven project. Alternately, to create a standalone project, uncheck the Create a simple project (skip archetype selection) check box and follow the instructions in the wizard.
    2. Ensure that the Use default Workspace location check box is not checked and specify a non-default location for your workspace files using the Browse button. Using a non-default workspace location is recommended because this allows other tools to access the workspace location easily.
    3. The following optional steps are available for further configuration, if required:

      1. (Optional) Check the Add project(s) to working set check box to add the newly created projects to a working set.
      2. (Optional) Click Advanced to view additional optional advanced configuration for the new Maven project, such as:

        1. Resolve Workspace projects: dependencies opened as workspace projects will be resolved without having to install them to your local Maven repository first. This way, any changes made to one of these dependencies will have an immediate effect on other projects consuming it (compilation, refactoring, etc.). When Resolve Workspace projects is disabled, dependencies existing in the workspace must be installed to your local Maven repository after any change (by running mvn install), in order to see effects in projects consuming them.
        2. Profiles: select a set of Maven profiles to activate or deactivate in the workspace. Profiles are defined in the project pom.xml, or inherited from a parent pom.xml, or defined in the relevant settings.xml.
        3. Name templates: allows you to disambiguate projects names in the workspace by prepending or appending the group ID or SCM branch names to the default artifact ID.

          Figure 1.16. Create a New Maven Project

          Create a New Maven Project
    4. When the configuration is complete, click Next to continue.
  3. Configure the project details:

    1. Enter the desired group ID, which is similar to an organization namespace (for example, com.company.businessunit.project), in the Group Id field.
    2. Enter the desired artifact ID value, which is the name for your project, in the Artifact Id field. This value must not include any spaces and the only special characters allowed are periods ('.'), underscores ('_'), and dashes ('-').
    3. Set the Version field’s value to 0.0.1-SNAPSHOT or a similar value. For details about the appropriate version build numbers, see Project Versions
    4. Set the value of the Packaging field to pom.
    5. (Optional) Add a name for your project in the Name field.
    6. (Optional) Add a description for your project in the Description field.

      Figure 1.17. Configure Project Details

      Configure Project Details
    7. Click Finish to conclude the new Maven project creation wizard.

Result: Your new Maven project is created and appears in the Project Explorer view.

1.2.2. Creating a New Maven Module

Each Maven project with a packaging pom can include multiple Maven modules. Follow the instructions to create your first Maven module:

1.2.2.1. Prerequisites

  1. You must have an existing Maven project available with the packaging type pom. See Create a New Maven Project for instructions to create a new Maven project.

1.2.2.2. Creating a New Maven Module

  1. Create a new Maven module as follows:

    1. In the Project Explorer view, right-click the recently created pom project and select NewProject.
    2. From the wizard selection screen, expand Maven and select Maven Module.
    3. Click Next > to continue.
  2. Enter the initial module details:

    1. Ensure that the Create a simple project (skip archetype selection) check box is not checked. If this check box is selected, the Select an Archetype step of the wizard is skipped.
    2. Enter the desired module name in the Module Name field. This value corresponds to the Maven project’s Project ID.
    3. Use the Browse button to locate the desired parent project and select it.
    4. The following optional steps are available for further configuration, if required:

      1. (Optional) Check the Add project(s) to working set check box to add the newly created projects to a working set.
      2. (Optional) Click Advanced to view additional optional advanced configuration for the new Maven project, such as:

        1. Resolve Workspace projects: dependencies opened as workspace projects will be resolved without having to install them to your local Maven repository first. This way, any changes made to one of these dependencies will have an immediate effect on other projects consuming it (compilation, refactoring, etc.). When Resolve Workspace projects is disabled, dependencies existing in the workspace must be installed to your local Maven repository after any change (by running mvn install), in order to see effects in projects consuming them.
        2. Profiles: select a set of Maven profiles to activate or deactivate in the workspace. Profiles are defined in the project pom.xml, or inherited from a parent pom.xml, or defined in the relevant settings.xml.
        3. Name templates: allows you to disambiguate projects names in the workspace by prepending or appending the group ID or SCM branch names to the default artifact ID.

          Figure 1.18. Set the Module Name and Parent

          Set the Module Name and Parent
    5. When the configuration is complete, click Next to continue.
  3. Enter the module archetype information:

    1. Ensure that the Show the last version of Archetype only check box is checked. This ensures that only the latest version of each archetype displays.
    2. Select an archetype based on the purpose of the project you are creating. Use the keyword maven-archetype-quickstart in the Filter field to locate a sample Maven project archetype.

      Figure 1.19. Select a Module Archetype

      Select a Module Archetype
    3. Click Next to continue.
  4. Enter the module details:

    1. Add the same group ID value that was used for the Maven project to the Group Id field.
    2. Add the desired version number in the Version field. For details about the appropriate version build numbers, see Project Versions
    3. The Artefact Id and Package fields are automatically populated based on the parent project details.

      Figure 1.20. Configure the Module Archetype Parameters

      Configure the Module Archetype Parameters
    4. Click Finish to conclude setting up the Maven module.
  5. (Optional) To change the settings for the created Maven module, expand the module name in the Project Explorer view and double click pom.xml from the expanded list. An Overview tab appears and all settings can be changed from this tab.

    Figure 1.21. Change the Module Settings from the Overview View

    Change the Module Settings from the Overview View

    Result: Your new Maven module is created and appears in the Project Explorer view. Additionally, a hierarchical view of the nested projects is now available in the Project Explorer view as well (see Nested/Hierarchical view of projects).

1.2.3. Adding Maven Support to an Existing Non-Maven Project

The previous tasks contain instructions to create a new Maven project and Maven module. However, for an existing application that was not created with Maven support, use the following instructions to add Maven support to the non-Maven project:

  1. Right-click the project name in the Project Explorer view.
  2. From the displayed options, click Configure.
  3. From the displayed sub-menu, click Convert to Maven Project.
  4. Configure details for the new pom file:

    1. The basic fields for the new pom file are prepopulated based on the project details. If required, edit the existing values.
    2. (Optional) Add a name for the new project in the Name field.
    3. (Optional) Add a brief description for the project in the Description field.

      Figure 1.22. Create a New Pom Descriptor

      Create a New Pom Descriptor
    4. Click Finish to finalize the pom information.
  5. If the project references java dependencies, a wizard appears displaying all these dependencies and a green check mark when each dependency is identified. Learn more about dependency identification in the Did You Know section.
  6. Check the Delete original references from project check box to avoid retaining duplicate or stale dependencies in your project.

    Figure 1.23. Identify Maven Dependencies

    Identify Maven Dependencies
  7. Click Finish when all dependencies are converted.

Result: The existing project is now configured for Maven support.

1.2.4. Did You Know?

  • The wizard used to convert a non-Maven project to a Maven project attempts to identify all the project’s classpath entries and their equivalent Maven dependencies. From the list of identified dependencies, users can select which ones will be added to the generated Maven pom.xml file. When identifying dependencies, one of several strategies may be used:

    • Checking if the jar contains the relevant maven metadata.
    • Identify the dependency using the Nexus indexer.
    • Identify the dependency using the JBoss Nexus instance REST API (if we are online) via a SHA1 search.
    • Identify the dependency using the search.maven.org REST API (if we are online) via a SHA1 search.
  • All unchecked dependencies will be ignored and are not added to the generated pom.xml. However, some of these can be added as transitive dependencies to your project. For instance, if you add jsp-api but remove servlet-api, the latter appears in the project classpath, as it is a dependency of jsp-api.
  • You can double-click on a dependency from a list (or click the Edit button) to edit its Maven coordinates or scope. Selecting several dependencies (ctrl+click) and clicking the Edit button allows batch editing of their scope.

1.2.5. Troubleshooting

  1. Error Message: Unidentifiable Dependency in the Maven Dependency column.

    Figure 1.24. Unidentifiable Dependency

    Unidentifiable Dependency
    1. Issue: Either:

      1. the jar file is corrupted/invalid.
      2. the jar file is valid but does not contain any metadata used for identification.
    2. Resolution:

      1. Make sure that jar exists as a Maven artifact. If needed, you can install it to your local repository and then Click on the Identify dependencies button.
      2. Double click on the dependency, or click on the Edit…​ button and set the expected maven coordinates.
  2. Error Message: Some selected dependencies can not be resolved. Click here to configure repositories in your settings.xml.

    Figure 1.25. Dependencies Can Not Be Resolved Error

    Dependencies Can Not Be Resolved Error
    1. Issue:: This error displays when a dependency can be identified (that is, whether it contains the pom properties or other metadata) but the dependency is not available in any repository defined in your settings.xml.
    2. Resolution: Click the here link in the error message and compare the old and new settings for the dependency and add a new and correct repository. Users may choose to use one of the predefined repositories from Red Hat.