Red Hat Training

A Red Hat training course is available for Red Hat JBoss Developer Studio

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.

1.1.1. Setting Up the Git Perspective

To locate the Git Perspective in the IDE:

  1. In the IDE, click Window > Perspective > Open Perspective > Other.
  2. In the Open Perspective window, click Git and click Open. The Git Repositories view appears.

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.

1.1.2.1. 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 icon.

    Figure 1.1. Click the Create a New Git Repository Button

    Click the Create a New Git Repository Button

  2. In the Create a Git Repository window:

    1. Ensure that the automatically populated default value for the Repository directory field is correct.

    2. Optionally, click the Create a bare repository checkbox to create a new bare repository. For details about bare repositories and how they differ from a normal repository, see the Additional Resources section.

      Figure 1.2. Create a New Git Repository

      Create a New Git Repository

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

1.1.2.2. 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 icon.

    Figure 1.3. Click the Clone a Git Repository Icon

    Click the Clone a Git Repository Icon
  3. Click the Clone a Git Repository icon.

  4. 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. In the Authentication pane, add your username and password for the source repository.

    3. Click Next to continue.

      Figure 1.4. Enter the Source Repository Details

      Enter the Source Repository Details
  5. In the Clone Git Repository window, select the branches that you want to clone and click Next.

  6. 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 check box 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
  7. Click Finish to conclude cloning an existing Git repository. The new cloned repository is listed in the Git Repositories view.

1.1.2.3. 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 following prerequisites section.

Prerequisites
  1. Ensure that you have forked the repository online.

  2. On 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 _<repository URL>_

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

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

    Click the Add an Existing Local Git Repository Icon

  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 pane, ensure that the appropriate .git file is selected and click Finish.

      Figure 1.7. Find and Add Local Repository

      Find and Add Local Repository

      The local repository now appears in the Git Repositories view.

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

To set up the remote for your repository:

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

  3. In the New Remote dialog box:

    1. Add a name in the Remote name field.
    2. Ensure that Configure push 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. In the URI field, add the URI to your repository . This automatically populates the Host and Repository path fields.
    3. In the Authentication pane, add your repository username and password and click Finish to continue.
  5. Click Save to save your push configuration settings. Expand the Remotes folder in the repository view to see the newly added remote.

1.1.4. Creating and Working With a New Branch

This section provides instructions for creating a new branch and common tasks that you can perfrom with the new branch.

1.1.4.1. Creating a New Branch

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

To create a new branch:

  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 click Create Branch.

      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. In the Branch name field, add the desired new branch name.
    2. Ensure that the Configure upstream for push and pull checkbox is selected.
    3. In the When pulling options, select the option that suits your requirement.

    4. Ensure that the Checkout new branch check box is selected and click Finish.

      Figure 1.9. Add Details for a New Branch

      Add Details for a New Branch

      The new branch appears under {Repository_Name} > Branches > Local.

1.1.4.2. Working in the New Branch

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

  1. Expand {Repository_Name} > Branches > Local 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 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 click Show In > Terminal.

    Figure 1.11. The Show Branch in Terminal Option

    The Show Branch in Terminal Option

  4. Next to the Terminal tab that has just opened, click the Open a Terminal icon to view the command line prompt in this view.

    Figure 1.12. The Open a Terminal Icon

    The Open a Terminal Icon

  5. In the Launch Terminal dialog box:

    1. In the Choose a Terminal list, ensure that Local Terminal is selected.
    2. In the Encoding list, click Default (ISO-8859-1). Click OK. Note that as a default, the terminal window is at the /home/YourCurrentUser/ directory.

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.4.3. Updating the Branch Before Implementing the 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 and click Pull. A status menu appears that displays the progress of the pull request. When the pull is complete, the Pull Result for {Repository_Name} window appears showing the results of the fetch and update operations.
  2. Click Close to conclude the operation. The repository now contains the most updated version of the contents.

1.1.5. Committing and Merging the Changes

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

To commit and merge the changes:

  1. Expand {Repository_Name} > Branches > Local. Ensure that the check mark that indicates the current branch appears at the correct working branch.
  2. Right-click the name of the repository and click Commit.

  3. In the Git Staging view:

    1. In the Commit message field, add a commit message describing the changes.

    2. Confirm that the automatically populated Author and Committer fields display the correct name and email address.

      Figure 1.13. Add details in the Commit Changes Field

      Add details in the Commit Changes Field
    3. 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.5.1. Committing and Pushing the Changes

If you selected Commit and Push in Section 1.1.5, “Committing and Merging the Changes”, use the following instructions:

  1. In the Login dialog box, enter your repository access username and password and click OK.

  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.14. 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. A Pull Request is generating and ready for the repository owner to review.

1.1.5.2. Committing Without Pushing the Changes

If you selected Commit in Section 1.1.5, “Committing and Merging the Changes” 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.15. 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 {branch_name}.
  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. In the Login dialog box, enter your repository access username and password and click OK.
  5. In the Push Confirmation dialog box, 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. The included changes are now committed and a Pull Request is generated for the repository owner to review.

Additional Resources

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