Mercurial User Guide
NetBeans IDE provides support for the Mercurial version control client versions 1.0.x and higher. The IDE's Mercurial 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.
Mercurial is a fast, lightweight source control management system designed for efficient handling of very large distributed projects. Unlike CVS and Subversion, Mercurial works with distributed repositories which are commonly used in many open source projects and supports distributed development without any centralized control. You can use Mercurial commands on both files and directories. The IDE provides a graphical Diff Viewer that enables you to compare file revisions and also supports inline diffs directly in the editor.
The IDE's Mercurial support is similar to the IDE's Subversion support. The main difference is that Mercurial is a distributed revision control system. Users typically begin by cloning an external repository to work with. This clone is a complete copy of the repository including the revision history. You can clone the local copy as often as needed and when ready, push locally made changes back to the original repository if you have permissions, or export the changes and send them to the repository owner if you do not have permissions.
To complete this tutorial, you need the following software and resources.
Setting up Mercurial
Before you can take advantage of the IDE's Mercurial support, you need to have Mercurial client software installed on your system. The IDE supports Mercurial client versions 1.04 and higher. The IDE's Mercurial support works by using the same commands as the Mercurial command line interface.
You can download Mercurial as either sources or as a binary package from the Mercurial website.
To set the path to the Mercurial executable file in the IDE:
You can run Mercurial commands from the IDE's Team > Mercurial menu after the Mercurial client is set up. To clone an external Mercurial repository, choose Team > Mercurial > Clone Other. In the process of cloning, the IDE automatically imports all of the history and status information for the cloned files.
If you have an existing Mercurial repository, the IDE automatically recognizes them as versioned files if those files are opened in an IDE project or if they are added to the Favorites window. You can use Mercurial commands on the files from the Mercurial menu or by right-clicking a file or folder and choosing from the Mercurial contextual menu.
To create a Mercurial repository on your computer using the command-line, type in the following:
hg clone /path/to/your/repository
Note: The NetBeans Mercurial repositories (http://hg.netbeans.org/) are used for demonstration purposes in this tutorial.
Synchronizing Local Files with a Repository
When using a version control system, you work by synchronizing local files with a repository, making changes to your local copy, then committing them to the repository. The following list describes various ways you can synchronize a project in the NetBeans IDE, depending on your specific situation:
Opening a Mercurial Project in the IDE
If you already have a Mercurial versioned project which you have been working with outside of the IDE, you can open it in the IDE and versioning features will automatically become available to you. The IDE scans the open projects, file status and context-sensitive support automatically becomes active for Mercurial versioned projects.
Checking out Files from a Repository
If you want to connect to a remote repository from the IDE, then check out files and immediately begin working with them, do the following:
Importing Files into a Repository
Alternately, you can import a project you have been working on in the IDE to a remote repository, then continue to work on it in the IDE after it has become synchronized.
Note: While you are actually exporting files from your system, the term 'import' is used in version control systems to signify that files are being imported into a repository.
To import a project to a repository:
Once you have a Mercurial 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 on Windows/Command-1 on OS X), Files (Ctrl-2 on Windows/Command-2 on OS X), Favorites (Ctrl-3 on Windows/Command-3 on OS X) windows).
When working with sources 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 your previously checked-out base version from the repository. As you work, the IDE uses color encoding in the Source Editor's margins to convey the following information:
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.
You can click on a color grouping in the margin to call versioning commands. For example, the screen capture below left shows widgets available to you when clicking a red icon, indicating that lines have been removed from your local copy.
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 encoding is generated immediately when you make changes to your file.
Note that 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:
Viewing File Status Information
When you are working in the Projects (Ctrl-1 on Windows/Command-1 on OS X), Files (Ctrl-2 on Windows/Command-2 on OS X), Favorites (Ctrl-3 on Windows/Command-3 on OS X), or Versioning windows, 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. ), 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:
Note: Status labels are textual indication of file status in the Versioning, Projects, and Files windows. To display status labels, choose View > Show Versioning Labels from the main toolbar.
Badges, color coding, file status labels, and perhaps most importantly, the Versioning window all contribute to your ability to effectively view and manage and 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:
Color coding is applied to file names in order to indicate their current status against the repository:
File Status Labels
File status labels provide a textual indication of the status of versioned files in the IDE's windows. 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. You can, however, modify this format to suit your own needs. For example, if you want to add revision numbers to status labels, do the following:
File status labels can be toggled on and off by choosing View > Show Versioning Labels from the main menu.
The Versioning Window
The Mercurial Versioning window provides you with a real-time list of all of the changes made to files within a selected folder of your local working copy. It opens by default in the bottom panel of the IDE, listing added, deleted or modified files.
To open the Versioning window, select a versioned file or folder (e.g. from the Projects, Files, or Favorites window) and either choose Mercurial > Status from the right-click menu, or choose Team > Mercurial > Status from the main menu. The following window appears in the bottom of the IDE:
By default, the Versioning window displays a list of all modified files within the selected package or folder. Using the buttons in the toolbar, you can choose to display all changes or limit the list of displayed files to either locally or remotely modified files. You can also click the column headings above the listed files to sort the files by name, status or location.
The Versioning window toolbar also includes buttons that enable you to invoke the most common Mercurial tasks on all files displayed in the list. The following table lists the Mercurial commands available in the toolbar of the Versioning window:
You can access other Mercurial commands in the Versioning window by selecting a table row that corresponds to a modified file, and choosing a command from the right-click menu:
For example, you can perform the following actions on a file:
Comparing File Revisions
Comparing file revisions is a common task when working with versioned projects. The IDE enables you to compare revisions by using the Diff command, which is available from the right-click menu of a selected item (Mercurial > Diff), as well as from the Versioning window. In the Versioning window, you can perform diffs by either double-clicking a listed file, otherwise you can click the Diff All icon () located in the toolbar at the top.
When you perform a diff, 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 copy, the working copy displays in the right panel:
The Diff Viewer makes use of the same color encoding 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).
Also, when performing a diff on a group of files, such as on a project, package, or folder, or when clicking Diff All (), you can switch between diffs by clicking files listed in the upper region of the Diff Viewer.
The Diff Viewer also provides you with the following functionality:
Make Changes to your Local Working Copy
If you are performing a diff on your local working copy, 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:
Navigate among Differences between Compared Files
If your diff contains multiple differences, you can navigate among them by using the arrow icons displayed in the toolbar. The arrow icons enable you to view differences as they appear from top to bottom:
Merging File Revisions
NetBeans IDE enables you to merge changes between repository revisions and your local working copy. Specifically, this combines two separate changesets in a repository into a new changeset that describes how they combine.
Note: After merging revisions to your local working copy, you must still commit changes using the Commit command in order for them to be added to the repository.
Committing Sources to a Repository
After making changes to sources, you commit them to the repository. It is generally a good idea to update any copies you have against the repository prior to performing a commit in order to ensure that conflicts do not arise. Conflicts can occur however, and should be thought of as a natural event when numerous developers are working on a project simultaneously. The IDE provides flexible support that enables you to perform all of these functions. It also provides a Conflict Resolver which allows you to safely deal with any conflicts as they occur.
Updating Local Copies
You can perform updates by choosing Team > Update from the main menu.
To perform an update on sources that you have modified, you can click the Update All icon (), which displays in the toolbars located at the top of both the Versioning Window, as well as the Diff Viewer. Any changes that may have occurred in the repository are displayed in the Versioning Output window.
Performing the Commit
After editing source files, performing an update and resolving any conflicts, you commit files from your local working copy to the repository. The IDE enables you to call the commit command in the following ways:
The Commit dialog opens, displaying files that are about to be committed to the repository:
The Commit dialog lists:
From the Commit dialog, it is possible to specify whether to exclude individual files from the commit. To do so, click the Commit Action column of a selected file and choose Exclude from Commit from the drop-down list.
To perform the commit:
You can update an issue by associating your commit action with an existing issue in your repository's issue tracker. To do so, click on the Update Issue heading in the Commit dialog box to expand it, then specify the following:
You can also specify the following options:
Pushing Local Changes to the Shared Repository
Before pushing changes that you have committed locally to the shared repository, you need to synchronize your local repository with the shared repository. To do this with the Fetch command, choose Team > (Mercurial >) Fetch - [Mercurial repository name] from the main menu. After you perform a successful Fetch, your local repository becomes synchronized with the shared repository.
To push changes, choose Team > (Mercurial >) Share > Push to - [Mercurial repository name] from the main menu. The output from a successful Push will list any changesets created.
Note: Since you maintain a copy of the entire repository on your system, the general practice is to make multiple commits to your local repository and only after the particular task is complete, perform the push to the shared repository.
This tutorial showed how to perform basic versioning tasks in the IDE by guiding you through the standard workflow when using the IDE's Mercurial support. It demonstrated how to set up a versioned project and perform basic tasks on versioned files while introducing you to some of the Mercurial specific features included in the IDE.
For related material see the following documents: