// 
//     Licensed to the Apache Software Foundation (ASF) under one
//     or more contributor license agreements.  See the NOTICE file
//     distributed with this work for additional information
//     regarding copyright ownership.  The ASF licenses this file
//     to you under the Apache License, Version 2.0 (the
//     "License"); you may not use this file except in compliance
//     with the License.  You may obtain a copy of the License at
// 
//       http://www.apache.org/licenses/LICENSE-2.0
// 
//     Unless required by applicable law or agreed to in writing,
//     software distributed under the License is distributed on an
//     "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
//     KIND, either express or implied.  See the License for the
//     specific language governing permissions and limitations
//     under the License.
//

= Using Support for Mercurial Queues in Apache NetBeans
:jbake-type: tutorial
:jbake-tags: tutorials 
:jbake-status: published
:syntax: true
:icons: font
:source-highlighter: pygments
:toc: left
:toc-title:
:description: Using Support for Mercurial Queues in NetBeans IDE - Apache NetBeans
:keywords: Apache NetBeans, Tutorials, Using Support for Mercurial Queues in NetBeans IDE

The NetBeans IDE provides support for the Mercurial Queues extension. The IDE's Mercurial Queues support allows you to create, review or switch between patches within the IDE, as well as refresh patches with local modifications as you fix bugs or update to a new base revision. This document demonstrates how to perform basic patch-specific tasks in the IDE by guiding you through the standard workflow when using Mercurial versioning software for managing patches.

== Enabling the Mercurial Queues Support

Since Mercurial Queues is an extension, you must explicitly enable it before you can use it.
To start running Mercurial Queues on your Mercurial repository, you need to complete the following steps:

1. On your system , browse to the  ``.hgrc``  file. The default location of the  ``.hgrc``  file on OS X and Linux is  ``$HOME/.hgrc`` , on Windows -  ``%USERPROFILE%\Mercurial.ini`` .
2. Add the lines below to your  ``.hgrc``  file.

[source,conf]
----
     [extensions]
     hgext.mq =
----


. Save the file.

== Creating a Patch

To create a patch, you need to complete the following steps:

1. In the Projects window, select a versioned project and choose  ``Team``  >  ``Queues``  >  ``Create Patch``  (alternatively, right-click the project name and select  ``Mercurial``  >  ``Queues``  >  ``Create Patch``  from the pop-up menu).
The Create Patch dialog box displays.

[.feature]
--
image::images/create-patch-small.png[role="left", link="images/create-patch.png"]
--


. Specify the name for a patch in the Patch Name text field.
. Provide the description of a patch in the Patch Message field.
Alternatively, choose either of the following options and click OK afterwards:
* click the Recent Messages button (image::images/recent.png[]) to select a message from a list of most recent commit messages
* click the Load Template button (image::images/load.png[]) to select a message template for a commit message.

NOTE: The provided description of a patch will be used as a commit message when <<finish,turning the patch into a permanent changeset>>.


. Select files to be included into the patch in the Files To Include In Patch table.
. (Optional) Specify information pertinent to an issue related to the created patch using the fields of the Update Issue area.
. Click Create Patch.
A new patch is created and added to the  ``.hg/patches``  directory.

== Refreshing a Patch With Local Modifications

To save your progress into the patch you are creating , you need to complete the following steps:

1. Choose  ``Team``  >  ``Queues``  >  ``Refresh Patch``  from the main menu (alternatively, right-click the project name and select  ``Mercurial``  >  ``Queues``  >  ``Refresh Patch``  from the pop-up menu).
The Refresh Patch dialog box displays.

[.feature]
--
image::images/refresh-patch-small.png[role="left", link="images/refresh-patch.png"]
--


. Provide the description of a patch in the Patch Message field.
Alternatively, choose either of the following options and click OK afterwards:
* click the Recent Messages button (image::images/recent.png[]) to select a message from a list of most recent commit messages
* click the Load Template button (image::images/load.png[]) to select a message template for a commit message.

NOTE: The provided description of a patch will be used as a commit message when <<finish,turning the patch into a permanent changeset>>.


. Select files to be included into the patch in the Files To Include In Patch table.
. (Optional) In the Update Issue area, specify information pertinent to an issue related to the changes being committed.
. Click Refresh Patch.
The patch you are working on is updated.

== Comparing Patch Revisions

To generate a patch for review and compare revisions of a patch side by side, you need to complete the following steps:

1. Choose  ``Team``  >  ``Queues``  >  ``Diff``  from the main menu (alternatively, right-click the project name and select  ``Mercurial``  >  ``Queues``  >  ``Diff``  from the pop-up menu).
The Diff Viewer displays differences found in the current patch and all your uncommitted/unrefreshed local changes in side-by-side panels:

[.feature]
--
image::images/qdiff-small.png[role="left", link="images/qdiff.png"]
--


. Review and revise differences found in the compared files using either Graphical or Textual Diff Viewer.

NOTE: The Graphical Diff Viewer highlights changes in the files using the following color encoding.

|===
|*Blue* (       ) |Indicates lines that have been changed since the earlier patch. 

|*Green* (       ) |Indicates lines that have been added since the earlier patch. 

|*Red* (       ) |Indicates lines that have been removed since the earlier patch. 
|===

The following icons enable you to make changes directly within the Graphical Diff Viewer.

|===
|Icon |Name |Function 

|image:images/replace.png[] |*Replace* |Inserts the highlighted text from the previous patch into the current patch. 

|image:images/replace-all.png[] |*Replace All* |Reverts current version of a patch to the state of its selected previous version. 

|image:images/remove.png[] |*Remove* |Removes the highlighted text from the current version of a patch so that it mirrors the previous version of a patch. 
|===

== Switching Between Patches

To switch to a particular patch in a patch queue series, you need to complete the following steps:

NOTE: To switch between patches there _must_ be _no_ local modifications in the working copy, otherwise the switch fails.

1. Choose  ``Team``  >  ``Queues``  >  ``Go To Patch``  from the main menu (alternatively, right-click the project name and select  ``Mercurial``  >  ``Queues``  > `` Go To Patch``  from the pop-up menu).
The Go To Patch dialog box displays a list of all patches available in a stack.

image::images/go-patch.png[]

NOTE: Names of applied patches display in bold. Choose  ``Team``  >  ``Queues``  >  ``Pop All Patches``  to remove the applied patches from the top of the stack and update the working directory to undo the effects of the applied patches.


. Select the required patch and click Go.
The IDE applies the changes contained in the selected patch to the chosen project, file, or folder.

== Finishing Applied Patches

Once your work on a patch is done, it can be turned into a permanent changeset.
To turn all applied patches in a patch queue series into regular changesets, complete the following steps:

NOTE: To apply all saved patches in the repository, choose  ``Team``  >  ``Queues``  >  ``Push All Patches``  from the main menu.

1. Choose  ``Team``  >  ``Queues``  >  ``Finish Patches``  from the main menu (alternatively, right-click the project name and select  ``Mercurial``  >  ``Queues``  >  ``Finish Patches``  from the pop-up menu).
The Finish Patches dialog box displays.

image::images/finish-patches.png[]


. Select the name of a patch to be finished in the patches field.

NOTE: All patches in the series before the selected patch will also be finished.


. Click Finish Patches.
The IDE turns all applied patches up to the selected patch into regular changesets.

== Summary

This tutorial showed how to perform basic patch-specific tasks in the IDE by guiding you through the standard workflow when using Mercurial versioning software for managing patches. It demonstrated how to enable the Mercurial Queues support in the NetBeans IDE and perform basic tasks on patches while introducing you to some of the Mercurial specific features included in the IDE.