corner imagecorner image
IDEPlatformPluginsDocs & SupportCommunityPartners

Git User Guide

The NetBeans IDE provides support for the Git version control client. The IDE's Git support allows you to perform versioning tasks directly from your project within the IDE. This document demonstrates how to perform basic versioning tasks in the IDE by guiding you through the standard workflow when using versioning software.

Git is is a free and open source, distributed version control system designed to handle everything from small to very large projects with speed and efficiency. Every Git clone is a full-fledged repository with complete history and full revision tracking capabilities, not dependent on network access or a central server. Branching and merging are fast and easy to do. Git is used for version control of files, much like tools such as Mercurial, Subversion, CVS, Perforce, etc.

Contents

Content on this page applies to NetBeans IDE 7.0

Requirements

To complete this tutorial, you need the following software and resources.

Software or Resource Version Required
NetBeans IDE Version 7.0
Java Development Kit (JDK) Version 6

Setting up Git

To take advantage of the IDE's Git support, you need to find and install the Git plugin for the NetBeans IDE 7.0 Beta2 as follows:

  1. Start the NetBeans IDE.
  2. Choose Tools > Plugins from the main menu.
  3. In the Plugins dialog box, select the Available Plugins tab.
  4. Scroll to find the Git plugin in the list and check it.

    Plugins dialog box

    Note: In case you do not see Git on the list, click Reload Catalog to check the update center and refresh the list of available plugins.

  5. Click Install.
  6. At the NetBeans IDE Installer Welcome page, click Next.
  7. At the License Agreement page, review the license agreement, click the acceptance check box, and click Install.
  8. After the installation of the Git plugin completes, select the Restart IDE Now option and click Finish.

Initializing a Git Repository

Now you need to initialize a Git repository from existing files that are not in source control yet.

  1. In the Projects window, select an unversioned project and right-click the project name.
  2. In the context menu, choose Versioning > Initialize Git Repository (alternatively, in the main menu, choose Team > Git > Initialize).

    3. Plugins dialog box

  3. Specify the path to the repository you are going to store your versioned files in the Repository root path dialog box or click Browse and browse for the directory required.
  4. Click OK.

    5. The Git repository is created. You can open Window > Output > Output to view the IDE's report about the progress of the repository creation under your local working directory.

    Output window

    A .git subfolder is created in your NetBeans project folder, which is your Git repository where all the data of your project snapshots are stored. In other words, an existing NetBeans directory is turned into a Git repository.

All the project files are marked Added in your Working Tree. To view a file status, place the cursor over the file name in the Projects window. The status of the file in the Working Tree displays in green to the right of the slash like shown in the following picture.

New in Working Tree

After you initialized the Git repository, you either add files or directly commit them to the Git repository.

Adding Files to a Git Repository

To start tracking a new file and also to stage changes to an already tracked file in the Git repository, you need to add it to the repository.

When adding files to a Git repository, the IDE composes and saves snapshots of your project first in the Index. After you perform the commit, the IDE saves those snapshots in the HEAD. The IDE allows you to choose between the two workflows described in the following table.

Workflow Description Explicitly add new or modified files to the Index and then commit only those that are staged in the Index to the HEAD Skip adding new or modified files to the Index and commit the required files directly to the HEAD
Steps to Follow the Workflow
  1. In the Projects window, right-click the file you want to add.
  2. In the context menu, choose Git > Add.
    This adds the file contents to the Index before you commit it.
  3. In the Projects window, right-click the file you want to commit.
  4. In the Commit dialog box, select the Changes between HEAD and Index ( Changes between HEAD and Index icon ) toggle button.
    This displays the list of files that are already staged.
  5. Commit the file(s) as described in the Committing Sources to a Repository section below.
  1. In the Projects window, right-click the file you want to commit.
  2. In the context menu, choose Git > Commit.
  3. In the Commit dialog box, select the Select the Changes between Index and Working Tree (Changes between HEAD and Working Tree icon) toggle button.
    This displays the list of files that are not staged.
  4. Commit the file(s) as described in the Committing Sources to a Repository section below.

Note: The status of the file in the HEAD displays in green to the left of the slash like shown in the following picture.

New in Staging Area

The action works recursively if invoked on folders while respecting the NetBeans IDE flat folder content structure.

Editing Files

Once you have a Git versioned project opened in the IDE, you can begin making changes to sources. As with any project opened in NetBeans IDE, you can open files in the Source Editor by double-clicking on their nodes, as they appear in the IDE's windows (e.g., Projects (Ctrl-1), Files (Ctrl-2), Favorites (Ctrl-3) windows).

When working with source files in the IDE, there are various UI components at your disposal, which aid in both viewing and operating version control commands:

Viewing Changes in the Source Editor

When you open a versioned file in the IDE's Source Editor, you can view real-time changes occurring to your file as you modify it against the base version from the Git repository. As you work, the IDE uses color coding in the Source Editor's margins to convey the following information:

Blue (       ) Indicates lines that have been changed since the earlier revision.
Green (       ) Indicates lines that have been added since the earlier revision.
Red (       ) Indicates lines that have been removed since the earlier revision.

The Source Editor's left margin shows changes occurring on a line-by-line basis. When you modify a given line, changes are immediately shown in the left margin.

Left Margin

Note: You can click on a color grouping in the margin to call versioning commands. For example, the picture below shows widgets available to you when clicking a red icon which indicates that lines have been removed from your local copy:

Widgets Available

The Source Editor's right margin provides you with an overview that displays changes made to your file as a whole, from top to bottom. Color coding is generated immediately when you make changes to your file.

Right Margin

Note: You can click on a specific point within the margin to bring your inline cursor immediately to that location in the file. To view the number of lines affected, hover your mouse over the colored icons in the right margin:

Widgets Available

Viewing File Status Information

When you are working in the Projects (Ctrl-1), Files (Ctrl-2), Favorites (Ctrl-3), or Versioning views, the IDE provides several visual features that aid in viewing status information about your files. In the example below, notice how the badge (e.g. Blue badge), color of the file name, and adjacent status label, all coincide with each other to provide you with a simple but effective way to keep track of versioning information on your files:

File Status Info

Badges, color coding, file status labels, and perhaps most importantly, the Git Diff Viewer all contribute to your ability to effectively view and manage versioning information in the IDE.

Badges and Color Coding

Badges are applied to project, folder, and package nodes and inform you of the status of files contained within that node:

The following table displays the color scheme used for badges:

UI Component Description
Blue Badge (Blue badge) Indicates the presence of files that have been modified, added or deleted in your working tree. For packages, this badge applies only to the package itself and not its subpackages. For projects or folders, the badge indicates changes within that item, or any of the contained subfolders.
Red Badge (Red badge) Marks projects, folders or packages that contain conflicting files. For packages, this badge applies only to the package itself and not its subpackages. For projects or folders, the badge indicates conflicts within that item, or any of the contained subfolders.

Color coding is applied to file names in order to indicate their current status against the repository:

Color Example Description
No specific color (black) Blue text Indicates that the file has no changes.
Blue Blue text Indicates that the file has been locally modified.
Green Green text Indicates that the file has been locally added.
Red Red text Indicates that the file is in a merge conflict.
Gray Gray text Indicates that the file is ignored by Git and will not be included in versioning commands (e.g. Update and Commit). Files cannot be ignored if they are versioned.

File Status Labels

The IDE displays two status values for a file:

  • A status describing differences between the files Working Tree and Index state,
  • A status describing differences between the files Index state and current HEAD commit.

File status labels provide a textual indication of the status of versioned files in the IDE's windows:

Status Label Meaning
- Unmodified
A Added
U Updated but unmerged
M Modified
D Deleted
I Ignored
R Renamed

By default, the IDE displays status (new, modified, ignored, etc.) and folder information in gray text to the right of files, as they are listed in windows.

File labels displayed next to file names

File(s) in merge conflict feature the unmerged status that is generally annotated by red color until the file(s) is not resolved by your explicit action. The status label for unmerged file(s) depends on the scenario (e.g., A/A - unmerged, both added).

File status labels can be toggled on and off by choosing View > Show Versioning Labels from the main menu.

Git Versioning View

The Git Versioning view provides you with a real-time list of all of the changes made to files within a selected folder of your local working tree. It opens by default in the bottom panel of the IDE, listing added, deleted or modified files.

To open the Versioning view, select a versioned file or folder (e.g. from the Projects, Files, or Favorites window) and either choose Git > Show Changes from the right-click menu, or choose Team > Git > Show Changes from the main menu. The following window appears in the bottom of the IDE:

Versioning view displaying changes between HEAD and working tree

By default, the Versioning view displays a list of all modified files within the selected package or folder in your Working Tree. Using the buttons in the toolbar, you can choose to display the list of files which have differences either between Index and HEAD, Working Tree and Index or Working Tree and HEAD. You can also click the column headings above the listed files to sort the files by name, status or location.

The Versioning view toolbar also includes buttons that enable you to invoke the most common Git tasks on all files displayed in the list. The following table lists the Git commands available in the toolbar of the Versioning view:

Icon Name Function
Changes between HEAD and Working Tree icon Changes between HEAD and Working Tree Displays a list of files that are either already staged or only modified/created and not staged yet.
Changes between HEAD and Index icon Changes between HEAD and Index Displays a list of files that are staged.
Changes between Index and Working Tree icon Changes between Index and Working Tree Displays files that have differences between their staged and Working Tree states.
Refresh Statuses icon Refresh Statuses Refreshes the status of the selected files and folders. Files displayed in the Versioning view can be refreshed to reflect any changes that may have been made externally.
Open Diff icon Open Diff Opens the Diff Viewer providing you with a side-by-side comparison of your local copies and the versions maintained in the repository.
Checkout Paths icon Revert Modifications Displays the Revert Modifications dialog box.
Commit Changes icon Commit Changes Displays the Commit dialog box.

You can access other Git commands in the Versioning view by selecting a table row that corresponds to a modified file, and choosing a command from the right-click menu:

Right-click menu displayed on selected file in Versioning window

Comparing File Revisions

Comparing file versions is a common task when working with versioned projects. The IDE enables you to compare revisions by using the Diff command:

  1. Select a versioned file or folder (e.g. from the Projects, Files, or Favorites window).
  2. Choose Team > Diff from the main menu.
    A graphical Diff Viewer opens for the selected file(s) and revisions in the IDE's main window. The Diff Viewer displays two copies in side-by-side panels. The more current copy appears on the right side, so if you are comparing a repository revision against your working tree, the working tree displays in the right panel:

    3. Diff Viewer

    The Diff Viewer makes use of the same color coding used elsewhere to display version control changes. In the screen capture displayed above, the green block indicates content that has been added to the more current revision. The red block indicates that content from the earlier revision has been removed from the later. Blue indicates that changes have occurred within the highlighted line(s).

The Diff Viewer toolbar also includes buttons that enable you to invoke the most common Git tasks on all files displayed in the list. The following table lists the Git commands available in the toolbar of the Diff Viewer:

Icon Name Function
Changes between HEAD and Working Tree icon Changes between HEAD and Working Tree Displays a list of files that are either already staged or only modified/created and not staged yet.
Changes between HEAD and Index icon Changes between HEAD and Index Displays a list of files that are staged.
Changes between Index and Working Tree icon Changes between Index and Working Tree Displays files that have differences between their staged and working tree states.
Go to Next Difference icon Go to Next Difference Displays next difference in the file.
Go to Previous Difference icon Go to Previous Difference Displays previous difference in the file.
Refresh Statuses icon Refresh Statuses Refreshes the status of the selected files and folders. Files displayed in the Versioning window can be refreshed to reflect any changes that may have been made externally.
Checkout Paths icon Revert Modifications Displays the Revert Modifications dialog box.
Commit Changes icon Commit Changes Displays the Commit dialog box.

If you are performing a diff on your local copy in the Working Tree, the IDE enables you to make changes directly from within the Diff Viewer. To do so, you can either place your cursor within the right pane of the Diff Viewer and modify your file accordingly, otherwise make use of the inline icons that display adjacent to each highlighted change:

Icon Name Function
Replace icon Replace Inserts the highlighted text into your Working Tree copy.
Move all icon Move All Reverts the whole local Working Tree copy.
Remove icon Remove Removes the highlighted text from the local Working Tree copy.

Reverting Changes

To throw away local changes made to selected files in your Working Tree and replace those files with the ones in the Index or HEAD:

  1. Select a versioned file or folder (e.g. from the Projects, Files, or Favorites window).
  2. Choose Team > Revert Modifications from the main menu.
    The Revert Modifications dialog box displays.

    3. Revert Modifications Dialog Box

  3. Specify additional options (e.g., Revert only Uncommitted Changes in Index to HEAD) .
  4. Click Revert.

The IDE replaces the selected files with those specified in step 3 above.

Committing Sources to a Repository

To commit files to the Git repository:

  1. In the Projects window, right-click the file(s) you want to commit.
  2. In the context menu, choose Git > Commit.

    3. The Commit dialog box displays.

    Commit dialog box

    The Commit dialog box contains the following components:

    • Commit Message text area intended for describing the change being committed
    • Author and Commiter drop-down lists that allow to differentiate between those who made the change and who physically committed the file if necessary.
    • Files to Commit section that lists:
      • all files modified,
      • all files that have been deleted in the Working Tree (locally),
      • all new files (i.e. files that do not yet exist in the Git repository),
      • all files that you have renamed.

        • Two toggle buttons that switch the mode in which the actual commit is to be performed are available here:

        UI Component Name Description
        Changes between HEAD and Index Changes between HEAD and Index Displays a list of files that are staged.
        Changes between HEAD and Working Tree Changes between HEAD and Working Tree Displays a list of files that are either already staged or only modified/created and not staged yet.

      Note: To specify here whether to exclude individual files from the commit, either deselect the checkbox in the first column called Commit or right-click a file row in the Commit Action column and choose Exclude from commit from the pop-up menu. To display the Diff Viewer here, right-click a file row in the Commit Action column and choose Diff from the pop-up menu.

    • Update Issue section intended for tracking issues related to the change being committed.

      • Note: You need to install the JIRA or Subversion plugin to start tracking issues in the IDE.

  3. Type in a commit message in the Commit Message text area. Alternatively, you can do any of the following:
    • click the Recent Messages ( Recent messages icon ) icon located in the upper right corner to view and select from a list of messages that you have previously used,
    • click the Load Template (Select template icon) icon located in the upper right corner to select a message template.
  4. After specifying actions for individual files, click Commit.
    The IDE executes the commit and stores your snapshots to the repository. The IDE's status bar, located in the bottom right of the interface, displays as the commit action takes place. Upon a successful commit, versioning badges disappear in the Projects, Files and Favorites windows, and the color coding of committed files returns to black.

Summary

This tutorial showed how to perform basic versioning tasks in the IDE by guiding you through the standard workflow when using the IDE's GIT support. It demonstrated how to set up a versioned project and perform basic tasks on versioned files while introducing you to some of the GIT specific features included in the IDE.


See Also

For related material see the following documents: