| <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> | |
| <!-- | |
| Copyright (c) 2009, 2012, Oracle and/or its affiliates. All rights reserved. | |
| --> | |
| <html> | |
| <head> | |
| <title>Mercurial User Guide - NetBeans IDE Tutorial</title> | |
| <meta http-equiv="content-type" content="text/html; charset=UTF-8"> | |
| <meta name="author" content="psunb@netbeans.org"> | |
| <meta name="description" content="Overview of Mercurial Features in NetBeans IDE"> | |
| <meta name="keywords" content="NetBeans, IDE, integrated development environment, Mercurial, | |
| versioning software, open source, developers, collaborate"> | |
| <link rel="stylesheet" type="text/css" href="../../../netbeans.css"> | |
| <link rel="stylesheet" type="text/css" href="../../../lytebox.css" media="screen"> | |
| <script type="text/javascript" src="../../../images_www/js/lytebox-compressed.js"></script> | |
| </head> | |
| <body> | |
| <h1>Mercurial User Guide</h1> | |
| <p>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.</p> | |
| <p><a href="http://www.selenic.com/mercurial/wiki/" target="_blank">Mercurial</a> 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.</p> | |
| <p>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 <em>cloning</em> 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 | |
| <em>export</em> the changes and send them to the repository owner if you do not have permissions. | |
| </p> | |
| <h3>Contents</h3> | |
| <img src="../../../images_www/articles/71/netbeans-stamp-71-72-73.png" | |
| class="stamp" | |
| alt="Content on this page applies to NetBeans IDE 6.9, 7.0, 7.1, 7.2 or 7.3" | |
| title="Content on this page applies to the NetBeans IDE 6.9, 7.0, 7.1, 7.2 or 7.3" > | |
| <ul class="toc"> | |
| <li><a href="#settingUp">Setting up Mercurial</a></li> | |
| <li><a href="#synchronizing">Synchronizing Local Files with a Repository</a></li> | |
| <li><a href="#editing">Editing Sources</a> | |
| <ul> | |
| <li><a href="#viewingChanges">Viewing Changes in the Source Editor</a></li> | |
| <li><a href="#viewingFileStatus">Viewing File Status Information</a></li> | |
| <li><a href="#comparing">Comparing File Revisions</a></li> | |
| </ul></li> | |
| <li><a href="#committing">Committing Sources to a Repository</a> | |
| <ul> | |
| <li><a href="#updating">Updating Local Copies</a></li> | |
| <li><a href="#committing">Performing the Commit</a></li> | |
| <li><a href="#issues">Updating Issues</a></li> | |
| <li><a href="#pushing">Pushing Local Changes to the Shared Repository</a></li> | |
| </ul> | |
| </li> | |
| <li><a href="#summary">Summary</a></li> | |
| <li><a href="#seeAlso">See Also</a></li> | |
| </ul> | |
| <h2><a name="reqs"></a>Requirements</h2> | |
| <p><strong>To complete this tutorial, you need the following software and resources.</strong></p> | |
| <table> | |
| <tbody> | |
| <tr> | |
| <th class="tblheader" scope="col">Software or Resource</th> | |
| <th class="tblheader" scope="col">Version Required</th> | |
| </tr> | |
| <tr> | |
| <td class="tbltd1"><a href="http://www.netbeans.org/downloads/index.html" target="_blank">NetBeans IDE</a></td> | |
| <td class="tbltd1">Version 6.9, 7.0, 7.1, 7.2, or 7.3</td> | |
| </tr> | |
| <tr> | |
| <td class="tbltd1"><a href="http://www.oracle.com/technetwork/java/javase/downloads/index.html" target="_blank">Java Development Kit</a> (JDK)</td> | |
| <td class="tbltd1">Version 6 or 7</td> | |
| </tr> | |
| <tr> | |
| <td class="tbltd1"><a href="http://www.selenic.com/mercurial/" target="_blank">Mercurial client software</a></td> | |
| <td class="tbltd1">1.04 or more recent</td> | |
| </tr> | |
| </tbody> | |
| </table> | |
| <a name="settingUp"></a> | |
| <h2>Setting up Mercurial</h2> | |
| <p> 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.</p> | |
| <p>You can download Mercurial as either sources or as a binary package from <a href="http://www.selenic.com/mercurial/" target="_blank"> | |
| the Mercurial website</a>.</p> | |
| <p>To set the path to the Mercurial executable file in the IDE:</p> | |
| <ol> | |
| <li>Choose <tt>Tools</tt> > <tt>Options</tt> (<tt>NetBeans</tt> > <tt>Preferences</tt> on OS X) from the main | |
| menu. The Options dialog opens.</li> | |
| <li>Select the Miscellaneous icon along the top of the dialog, then click the | |
| Versioning tab. In the left pane under Versioning Systems, select Mercurial. | |
| User-defined options for Mercurial display in the main window of the dialog: | |
| <p class="align-center"> | |
| <a href="../../../images_www/articles/73/ide/mercurial/options-dialog.png" rel="lytebox" | |
| title="Mercurial Options dialog"> | |
| <img src="../../../images_www/articles/73/ide/mercurial/options-dialog-small.png" class="margin-around" | |
| alt="Mercurial Options dialog"></a></p></li> | |
| <li>In the Mercurial Executable Path text field, either type in the path to the | |
| executable file or click Browse to navigate to it on your system. Note that | |
| you need not <em>include</em> the Mercurial executable file in the path.</li> | |
| <li>Click OK.</li> | |
| </ol> | |
| <p>You can run Mercurial commands from the IDE's <tt>Team</tt> > <tt>Mercurial</tt> menu after the Mercurial client is set up. To clone an external Mercurial | |
| repository, choose <tt>Team</tt> > <tt>Mercurial</tt> > <tt>Clone Other</tt>. In the process of cloning, the IDE automatically imports all of the history and status | |
| information for the cloned files.</p> | |
| <p>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.</p> | |
| <p>To create a Mercurial repository on your computer using the command-line, type in the following:</p> | |
| <pre class="examplecode">hg clone /path/to/your/repository</pre> | |
| <p class="notes"><b>Note:</b> The NetBeans Mercurial repositories (<a href="http://hg.netbeans.org/">http://hg.netbeans.org/</a>) are used for demonstration purposes in this tutorial. </p> | |
| <a name="synchronizing"></a> | |
| <h2>Synchronizing Local Files with a Repository</h2> | |
| <p>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:</p> | |
| <ul> | |
| <li><a href="#opening">Opening a Mercurial Project in the IDE</a> </li> | |
| <li><a href="#checking">Checking out Files from a Repository</a></li> | |
| <li><a href="#importing">Importing Files into a Repository</a></li> | |
| </ul> | |
| <div class="indent"> | |
| <a name="opening"></a> | |
| <h3>Opening a Mercurial Project in the IDE</h3> | |
| <p>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.</p> | |
| <a name="checking"></a> | |
| <h3>Checking out Files from a Repository</h3> | |
| <p>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:</p> | |
| <ol> | |
| <li>In NetBeans IDE, choose <tt>Team</tt> > <tt>Mercurial</tt> > <tt>Clone</tt> other from | |
| the main menu. The Clone wizard opens. | |
| <p class="align-center"> | |
| <a href="../../../images_www/articles/73/ide/mercurial/clone-repository.png" rel="lytebox" | |
| title="Mercurial Clone Wizard"> | |
| <img src="../../../images_www/articles/73/ide/mercurial/clone-repository-small.png" class="margin-around" | |
| alt="Mercurial Clone Wizard"></a></p> | |
| <p class="notes"><b>Note:</b> The IDE's drop-down menus are context-sensitive, | |
| i.e. the available options depend on the item currently selected. | |
| Therefore, if you are already working within a Mercurial project, | |
| you can choose <tt>Versioning</tt> > <tt>Checkout</tt> from the main menu.</p></li> | |
| <li>In Repository URL, enter the path to the repository (e.g. <tt>http://hg.netbeans.org/main</tt>).</li> | |
| <li>In the User and Password fields that the Clone wizard displays, enter your netbeans.org username and password. | |
| <p class="align-center"> <a href="../../../images_www/articles/73/ide/mercurial/clone-username.png" rel="lytebox" title="Mercurial Clone Wizard"> | |
| <img src="../../../images_www/articles/73/ide/mercurial/clone-username-small.png" class="margin-around" alt="Mercurial Clone Wizard"></a></p></li> | |
| <li>If you are using a proxy, be sure to click the Proxy Configuration button | |
| and enter any required information in the Options dialog box. When you are certain your connection | |
| settings to the repository are correct, click Next.</li> | |
| <li>In the second step, click Change to the right of the Default Push Path field. The Change Push Path dialog box opens. | |
| <p class="align-center"><a href="../../../images_www/articles/73/ide/mercurial/clone-push.png" rel="lytebox" title="Change Push Path Dialog"> | |
| <img src="../../../images_www/articles/73/ide/mercurial/clone-push-small.png" class="margin-around" alt="Change Push Path Dialog"></a></p></li> | |
| <li> Modify your default push entry by adding your NetBeans username and password and changing the protocol to <tt>https</tt>. </li> | |
| <li>Click Set Path. The Change Push Path dialog box closes.</li> | |
| <li>Click Next to pass to the third step of the wizard. </li> | |
| <li>In the Parent Directory field, enter a location on your computer where you want | |
| repository files to be checked out to (alternatively, you can use the Browse button). | |
| <p class="align-center"> <a href="../../../images_www/articles/73/ide/mercurial/clone-destination.png" rel="lytebox" title="Mercurial Clone Wizard"> | |
| <img src="../../../images_www/articles/73/ide/mercurial/clone-destination-small.png" class="margin-around" alt="Mercurial Clone Wizard"></a></p> | |
| <p class="note"><b>Note:</b> If you are running Windows, be careful of the path length that you specify; i.e., <tt>C:\Documents and Settings\myName\My Documents\NetBeans\etc\etc</tt> can cause an unsuccessful clone due to very long file paths. Try using <tt>C:\</tt> instead.</p></li> | |
| <li>Leave the Scan for NetBeans Projects after | |
| Checkout option selected, then click Finish to initiate the check out | |
| action. <br>The IDE checks out the specified sources and the IDE's status bar | |
| indicates the progress of the files downloading from the repository to your | |
| local working directory. You can also view files as they are being checked | |
| out from the Output window (Ctrl-4 on Windows/Command-4 on OS X). | |
| <p class="notes"><b>Note: </b>If the checked out sources contain NetBeans projects, | |
| a dialog box appears prompting you to open them in the IDE. If the sources do not | |
| contain a project, the dialog appears prompting you to create a new project | |
| from the sources and then open them in the IDE. If you create a new project | |
| for such sources, select the appropriate project category (in the New | |
| Project wizard) and then use the With Existing Sources option within that | |
| category.</p></li> | |
| </ol> | |
| <a name="importing"></a> | |
| <h3>Importing Files into a Repository</h3> | |
| <p>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.</p> | |
| <p><strong class="notes">Note: </strong>While you are actually <em>exporting</em> files | |
| from your system, the term 'import' is used in version control systems to | |
| signify that files are being <em>imported into</em> a repository.</p> | |
| <p>To import a project to a repository:</p> | |
| <ol> | |
| <li>From the Projects window (Ctrl-1 on Windows/Command-1 on OS X), select an unversioned project and | |
| choose <tt>Versioning</tt> > <tt>Initialize Mercurial Project</tt> from the | |
| node's right-click menu. The Repository root path dialog box opens. | |
| <p class="align-center"><a href="../../../images_www/articles/73/ide/mercurial/repositoryrootpath.png" rel="lytebox" | |
| title="Repository root path dialog box"> | |
| <img src="../../../images_www/articles/73/ide/mercurial/repositoryrootpath.png" class="margin-around" | |
| alt="Repository root path dialog box"></a></p></li> | |
| <li>Specify the repository folder in which you | |
| want to place the project in the repository. A folder containing the name | |
| of your project is suggested for you in the Root Path text field | |
| by default. </li> | |
| <li>Click | |
| OK to initiate the Mercurial initialize action.<br> | |
| Upon clicking OK, the IDE uploads the project files to the repository | |
| and the Output window opens to display the progress. | |
| <p class="align-center"> | |
| <a href="../../../images_www/articles/73/ide/mercurial/output.png" rel="lytebox" | |
| title="Output"> | |
| <img src="../../../images_www/articles/73/ide/mercurial/output-small.png" class="margin-around" | |
| alt="Output"></a></p> | |
| <p class="notes"><b>Note:</b> After the project files are placed under Mercurial version control, they get registered in the repository as <tt>Locally New</tt>. The new files and their status can be viewed by clicking on <tt>Mercurial</tt> > <tt>Status</tt> from the right-click menu.</p> | |
| <p class="align-center"><a href="../../../images_www/articles/73/ide/mercurial/status.png" rel="lytebox" | |
| title="Status"> | |
| <img src="../../../images_www/articles/73/ide/mercurial/status-small.png" class="margin-around" | |
| alt="Status"></a></p></li> | |
| <li>Choose <tt>Mercurial</tt> > <tt>Status</tt> from the project's right-click menu to commit these project files to the Mercurial repository. The Commit - [ProjectName] dialog box opens. | |
| <p class="align-center"><a href="../../../images_www/articles/73/ide/mercurial/commit-dialog.png" rel="lytebox" | |
| title="Commit Dialog Box"> | |
| <img src="../../../images_www/articles/73/ide/mercurial/commit-dialog-small.png" class="margin-around" | |
| alt="Commit Dialog Box"></a></p></li> | |
| <li>Type your message in the Commit Message text area and click Commit. | |
| <p class="notes"><b>Note:</b> The committed files are placed together with the <tt>.hg</tt> directory in the Mercurial repository directory. The commit details are available in the IDE Output window (Ctrl-4 on Windows/Command-4 on OS X).</p></li> | |
| </ol> | |
| </div> | |
| <a name="editing"></a> | |
| <h2>Editing Sources</h2> | |
| <p>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).</p> | |
| <p>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:</p> | |
| <ul> | |
| <li><a href="#viewingChanges">Viewing Changes in the Source Editor</a></li> | |
| <li><a href="#viewingFileStatus">Viewing File Status Information</a></li> | |
| <li><a href="#comparing">Comparing File Revisions</a></li> | |
| <li><a href="#merging">Merging File Revisions</a></li> | |
| </ul> | |
| <div class="indent"> | |
| <a name="viewingChanges"></a> | |
| <h3>Viewing Changes in the Source Editor</h3> | |
| <p>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:</p> | |
| <table class="cell"> | |
| <tr> | |
| <td class="align-right cell"><strong>Blue</strong> | |
| ( <span style="background-color:#b8cfe5"> </span> )</td> | |
| <td>Indicates lines that have been changed since the earlier revision.</td> | |
| </tr> | |
| <tr> | |
| <td class="align-right cell"><strong>Green</strong> | |
| ( <span style="background-color:#b4ffb4"> </span> )</td> | |
| <td>Indicates lines that have been added since the earlier revision.</td> | |
| </tr> | |
| <tr> | |
| <td class="align-right cell"><strong>Red</strong> | |
| ( <span style="background-color:#ffa0b4"> </span> )</td> | |
| <td>Indicates lines that have been removed since the earlier revision.</td> | |
| </tr> | |
| </table> | |
| <p>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.</p> | |
| <p>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.</p> | |
| <p>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.</p> | |
| <p>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:</p> | |
| <table class="cell" style="width:500px"> | |
| <tr> | |
| <td><a href="../../../images_www/articles/73/ide/mercurial/left-ui.png" rel="lytebox" | |
| title="versioning color encoding displayed in editor's left margin"> | |
| <img src="../../../images_www/articles/73/ide/mercurial/left-ui-small.png" class="b-all" | |
| alt="Versioning color encoding displayed in editor's left margin"></a><br> | |
| <strong>Left margin</strong></td> | |
| <td><a href="../../../images_www/articles/73/ide/mercurial/right-ui.png" rel="lytebox" | |
| title="versioning color encoding displayed in editor's right margin"> | |
| <img src="../../../images_www/articles/73/ide/mercurial/right-ui-small.png" class="b-all" | |
| alt="Versioning color encoding displayed in editor's right margin"></a> | |
| <br><strong>Right margin</strong></td> | |
| </tr> | |
| </table> | |
| <a name="viewingFileStatus"></a> | |
| <h3>Viewing File Status Information</h3> | |
| <p>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. | |
| <img src="../../../images_www/articles/73/ide/mercurial/blue-badge.png" | |
| alt="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: | |
| </p> | |
| <p class="align-center"><img src="../../../images_www/articles/73/ide/mercurial/badge-example.png" | |
| class="b-all" alt="Blue badge displayed in Favorites window"></p> | |
| <p class="notes"><b>Note:</b> 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.</p> | |
| <p>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.</p> | |
| <ul> | |
| <li><a href="#badges">Badges and Color Coding</a></li> | |
| <li><a href="#fileStatus">File Status Labels</a></li> | |
| <li><a href="#versioning">The Versioning Window</a></li> | |
| </ul> | |
| <div class="indent"> | |
| <a name="badges"></a> | |
| <h4>Badges and Color Coding</h4> | |
| <p>Badges are applied to project, folder, and package nodes and | |
| inform you of the status of files contained within that node:</p> | |
| <p>The following table displays the color scheme used for badges:</p> | |
| <table > | |
| <tr> | |
| <th class="tblheader" scope="col" style="width:110px">UI Component</th> | |
| <th class="tblheader" scope="col" style="width:490px">Description</th> | |
| </tr> | |
| <tr> | |
| <td class="tbltd0 align-center"><strong>Blue Badge</strong> | |
| (<img src="../../../images_www/articles/73/ide/mercurial/blue-badge.png" | |
| alt="Blue badge">)</td> | |
| <td class="tbltd0">Indicates the presence of files that have been locally modified, added or | |
| deleted. 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.</td> | |
| </tr> | |
| <tr> | |
| <td class="tbltd1 align-center"><strong>Red Badge</strong> | |
| (<img src="../../../images_www/articles/73/ide/mercurial/red-badge.png" | |
| alt="Red badge">)</td> | |
| <td class="tbltd1">Marks projects, folders or packages that contain <em>conflicting</em> | |
| files (i.e. local versions that conflict with versions maintained in | |
| the repository). 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.</td> | |
| </tr> | |
| </table> | |
| <a name="color-coding-table"></a> | |
| <p>Color coding is applied to file names in order to indicate their current | |
| status against the repository:</p> | |
| <table > | |
| <tr> | |
| <th class="tblheader" scope="col" style="width:40px">Color</th> | |
| <th class="tblheader" scope="col">Example</th> | |
| <th class="tblheader" scope="col">Description</th> | |
| </tr> | |
| <tr> | |
| <td class="tbltd0 align-center"><strong>Blue</strong></td> | |
| <td class="tbltd0"><img src="../../../images_www/articles/73/ide/mercurial/blue-text.png" | |
| alt="Blue text"></td> | |
| <td class="tbltd0">Indicates that the file has been locally modified.</td> | |
| </tr> | |
| <tr> | |
| <td class="tbltd1 align-center"><strong>Green</strong></td> | |
| <td class="tbltd1"><img src="../../../images_www/articles/73/ide/mercurial/green-text.png" | |
| alt="Green text"></td> | |
| <td class="tbltd1">Indicates that the file has been locally added.</td> | |
| </tr> | |
| <tr> | |
| <td class="tbltd0 align-center"><strong>Red</strong></td> | |
| <td class="tbltd0"><img src="../../../images_www/articles/73/ide/mercurial/red-text.png" | |
| alt="Red text"></td> | |
| <td class="tbltd0">Indicates that the file contains conflicts between your local | |
| working copy and the repository's version.</td> | |
| </tr> | |
| <tr> | |
| <td class="tbltd1 align-center"><strong>Gray</strong></td> | |
| <td class="tbltd1"><img src="../../../images_www/articles/73/ide/mercurial/gray-text.png" | |
| alt="Gray text"></td> | |
| <td class="tbltd1">Indicates that the file is ignored by Mercurial and will not | |
| be included in versioning commands (e.g. Update and Commit). Files | |
| can only be made to be ignored if they have not yet been versioned.</td> | |
| </tr> | |
| <tr> | |
| <td class="tbltd0 align-center" style="width:120px"><strong>Strike-Through</strong></td> | |
| <td class="tbltd0 align-center"><img alt="Strike-through text" | |
| src="../../../images_www/articles/73/ide/mercurial/strike-through-text.png"></td> | |
| <td class="tbltd0">Indicates that the file is excluded from commit operations. | |
| Strike-through text only appears in specific locations, such as the Versioning | |
| window or Commit dialog, when you choose to exclude individual files from a | |
| commit action. Such files are still affected by other Mercurial commands, | |
| such as Update.</td> | |
| </tr> | |
| </table> | |
| <a name="fileStatus"></a> | |
| <h4>File Status Labels</h4> | |
| <p>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:</p> | |
| <ol> | |
| <li>Choose <tt>Tools</tt> > <tt>Options</tt> (<tt>NetBeans</tt> > <tt>Preferences</tt> on OS X) from the | |
| main menu. The Options window opens.</li> | |
| <li>Select the Miscellaneous button along the top of the window, then click | |
| the Versioning tab beneath it. Make sure Mercurial is selected beneath | |
| Versioning Systems in the left panel. </li> | |
| <li>To reformat status labels so that only status and folder display to | |
| the right of files, rearrange the contents of the Status Label Format | |
| text field to the following: | |
| <pre class="examplecode">[{status}; {folder}]</pre> | |
| Click OK. Status labels now list file status and folder | |
| (where applicable): </li></ol> | |
| <p class="align-center"><img src="../../../images_www/articles/73/ide/mercurial/file-labels.png" | |
| class="b-all margin-around" alt="File labels displayed next to file names"></p> | |
| <p class="tips">File status labels can be toggled on and off by choosing | |
| <tt>View</tt> > <tt>Show Versioning Labels</tt> from the main menu.</p> | |
| <a name="versioning"></a> | |
| <h4>The Versioning Window</h4> | |
| <p>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.</p> | |
| <p>To open the Versioning window, select a versioned file or folder (e.g. from | |
| the Projects, Files, or Favorites window) and either choose <tt>Mercurial</tt> > | |
| <tt>Status</tt> from the right-click menu, or choose <tt>Team</tt> > <tt>Mercurial</tt> > <tt>Status</tt> | |
| from the main menu. The following window appears in the bottom of the IDE: | |
| </p> | |
| <p class="align-center"><img src="../../../images_www/articles/73/ide/mercurial/versioning-window.png" | |
| class="b-none margin-around" alt="Versioning window displaying locally modified files"></p> | |
| <p>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.</p> | |
| <p>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:</p> | |
| <table > | |
| <tr> | |
| <th class="tblheader" scope="col">Icon</th> | |
| <th class="tblheader" scope="col" style="width:110px">Name</th> | |
| <th class="tblheader" scope="col">Function</th> | |
| </tr> | |
| <tr> | |
| <td class="tbltd0 align-center"><img src="../../../images_www/articles/73/ide/mercurial/refresh.png" | |
| alt="refresh status icon"></td> | |
| <td class="tbltd0 align-center"><strong>Refresh Status</strong></td> | |
| <td class="tbltd0">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.</td> | |
| </tr> | |
| <tr> | |
| <td class="tbltd1 align-center"><img src="../../../images_www/articles/73/ide/mercurial/diff.png" | |
| alt="Diff all icon"></td> | |
| <td class="tbltd1 align-center"><strong>Diff All</strong></td> | |
| <td class="tbltd1">Opens the Diff Viewer providing you with a side-by-side | |
| comparison of your local copies and the versions maintained in the | |
| repository.</td> | |
| </tr> | |
| <tr> | |
| <td class="tbltd0 align-center"><img src="../../../images_www/articles/73/ide/mercurial/update.png" | |
| alt="update all icon"></td> | |
| <td class="tbltd0 align-center"><strong>Update All</strong></td> | |
| <td class="tbltd0">Updates all selected files from the repository.</td> | |
| </tr> | |
| <tr> | |
| <td class="tbltd1 align-center"><img src="../../../images_www/articles/73/ide/mercurial/commit.png" | |
| alt="Commit all icon"></td> | |
| <td class="tbltd1 align-center"><strong>Commit All</strong></td> | |
| <td class="tbltd1">Enables you to commit local changes to the repository.</td> | |
| </tr> | |
| </table> | |
| <p>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:</p> | |
| <p class="align-center"><img src="../../../images_www/articles/73/ide/mercurial/versioning-right-click.png" class="b-none margin-around" | |
| alt="Right-click menu displayed on selected file in Versioning window"></p> | |
| <p>For example, you can perform the following actions on a file:</p> | |
| <table > | |
| <tr> | |
| <td> | |
| <ul> | |
| <li><strong>Show Annotations</strong>: | |
| Displays author and revision number information in the left margin of | |
| files opened in the Source Editor.</li> | |
| </ul></td> | |
| <td class="f-page-cell"> | |
| <img src="../../../images_www/articles/73/ide/mercurial/annotations.png" | |
| alt="Annotations displayed in Source Editor's left margin" class="b-all"></td> | |
| </tr> | |
| <tr> | |
| <td> | |
| <ul> | |
| <li><strong>Revert Modifications</strong>: | |
| Opens the Revert Modifications dialog which you can use to specify | |
| parameters for reverting any local changes to revisions maintained | |
| in the repository.</li> | |
| </ul></td> | |
| <td class="f-page-cell"> | |
| <a href="../../../images_www/articles/73/ide/mercurial/search-rev.png" rel="lytebox" | |
| title="Search Revisions dialog lists file revisions according to date"> | |
| <img src="../../../images_www/articles/73/ide/mercurial/search-rev-small.png" | |
| alt="Revert Modifications dialog" | |
| class="b-right b-bottom"></a></td> | |
| </tr> | |
| </table> | |
| </div> | |
| <a name="comparing"></a> | |
| <h3>Comparing File Revisions</h3> | |
| <p>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 (<tt>Mercurial</tt> > <tt>Diff</tt>), 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 (<img alt="Diff all icon" | |
| src="../../../images_www/articles/73/ide/mercurial/diff.png">) located in the | |
| toolbar at the top.</p> | |
| <p>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:</p> | |
| <p class="align-center"><a href="../../../images_www/articles/73/ide/mercurial/diff-viewer.png" rel="lytebox" | |
| title="Mercurial Diff Viewer"> | |
| <img src="../../../images_www/articles/73/ide/mercurial/diff-viewer-small.png" | |
| class="b-all margin-around" alt="Mercurial Diff Viewer"></a></p> | |
| <p>The Diff Viewer makes use of the same <a href="#viewingChanges">color encoding</a> | |
| 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).</p> | |
| <p>Also, when performing a diff on a group of files, such as on a project, | |
| package, or folder, or when clicking Diff All | |
| (<img src="../../../images_www/articles/73/ide/mercurial/diff.png" | |
| alt="Diff all icon">), you can switch between diffs by clicking files | |
| listed in the upper region of the Diff Viewer.</p> | |
| <p>The Diff Viewer also provides you with the following functionality:</p> | |
| <ul> | |
| <li><a href="#makeChanges">Make Changes to your Local Working Copy</a></li> | |
| <li><a href="#navigateDifferences">Navigate Among Differences</a></li> | |
| </ul> | |
| <div class="indent"> | |
| <a name="makeChanges"></a> | |
| <h4>Make Changes to your Local Working Copy</h4> | |
| <p>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:</p> | |
| <table> | |
| <tr> | |
| <td class="align-right cell" style="width:120px"><strong>Replace</strong> (<img alt="Replace icon" | |
| src="../../../images_www/articles/73/ide/mercurial/insert.png">):</td> | |
| <td>Inserts the highlighted text from the previous revision into | |
| the current revision</td> | |
| </tr> | |
| <tr> | |
| <td class="align-right cell" style="width:120px"><strong>Move All</strong> (<img alt="Move all icon" | |
| src="../../../images_www/articles/73/ide/mercurial/arrow.png">):</td> | |
| <td>Reverts the file's current revision to the state of the selected | |
| previous revision</td> | |
| </tr> | |
| <tr> | |
| <td class="align-right cell" style="width:120px"><strong>Remove</strong> (<img alt="Remove icon" | |
| src="../../../images_www/articles/73/ide/mercurial/remove.png">):</td> | |
| <td>Removes the highlighted text from the current revision so that it | |
| mirrors the previous revision</td> | |
| </tr> | |
| </table> | |
| <a name="navigateDifferences"></a> | |
| <h4>Navigate among Differences between Compared Files</h4> | |
| <p>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:</p> | |
| <table> | |
| <tr> | |
| <td class="align-right cell" style="width:120px"><strong>Previous</strong> | |
| (<img src="../../../images_www/articles/73/ide/mercurial/diff-prev.png" | |
| alt="Previous difference button">):</td> | |
| <td>Goes to previous difference displayed in the diff</td> | |
| </tr> | |
| <tr> | |
| <td class="align-right cell" style="width:120px"><strong>Next</strong> | |
| (<img src="../../../images_www/articles/73/ide/mercurial/diff-next.png" | |
| alt="Next difference button">):</td> | |
| <td>Goes to next difference displayed in the diff</td> | |
| </tr> | |
| </table> | |
| </div> | |
| <a name="merging"></a> | |
| <h3>Merging File Revisions</h3> | |
| <p>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.</p> | |
| <ol> | |
| <li>In the Projects, Files, or Favorites window, right-click the files or | |
| folders on which you want to perform the merge operation and choose | |
| <tt>Mercurial</tt> > <tt>Merge Changes</tt>. The Merge with Revision dialog displays.</li> | |
| <li>In the Choose From Revisions drop-down list, select the revision. You are porting all changes made on a local working copy file from | |
| the time it was created.</li> | |
| <li>Ensure the Description, Author, and Date data are correct. | |
| <p class="align-center"> <a href="../../../images_www/articles/73/ide/mercurial/mercurial-merge.png" rel="lytebox" | |
| title="Mercurial Merge dialog"> | |
| <img src="../../../images_www/articles/73/ide/mercurial/mercurial-merge-small.png" | |
| class="margin-around b-none" alt="Mercurial Merge dialog"></a></p></li> | |
| <li>Click Merge. The IDE incorporates any differences found between the | |
| repository revisions and your local copy of the file. If merge conflicts | |
| occur, the file's status is updated to <a href="#resolving">Merge | |
| Conflict</a> to indicate this.</li> | |
| </ol> | |
| <p><strong class="notes">Note: </strong>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.</p> | |
| </div> | |
| <a name="committing"></a> | |
| <h2>Committing Sources to a Repository</h2> | |
| <p>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.</p> | |
| <ul> | |
| <li><a href="#updating">Updating Local Copies</a></li> | |
| <li><a href="#performing">Performing the Commit</a></li> | |
| <li><a href="#issues">Updating Issues</a></li> | |
| </ul> | |
| <div class="indent"> | |
| <a name="updating"></a> | |
| <h3>Updating Local Copies</h3> | |
| <p>You can perform updates by choosing <tt>Team</tt> > <tt>Update</tt> from the | |
| main menu.</p> | |
| <p>To perform an update on sources that you have modified, you can click | |
| the Update All icon (<img src="../../../images_www/articles/73/ide/mercurial/update.png" | |
| alt="Update all icon">), which displays in the toolbars located | |
| at the top of both the <a href="#versioning">Versioning Window</a>, | |
| as well as the <a href="#comparing">Diff Viewer</a>. Any changes that | |
| may have occurred in the repository are displayed in the Versioning | |
| Output window.</p> | |
| <a name="comitting"></a> | |
| <h3>Performing the Commit</h3> | |
| <p>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:</p> | |
| <ul> | |
| <li>From the Projects, Files or Favorites windows, right-click new or | |
| modified items and choose <tt>Mercurial</tt> > <tt>Commit</tt>.</li> | |
| <li>From the Versioning window or Diff Viewer, click the Commit All | |
| (<img src="../../../images_www/articles/73/ide/mercurial/commit.png" | |
| alt="Commit all icon">) button located in the toolbar.</li> | |
| </ul> | |
| <p>The Commit dialog opens, displaying files that are about to be committed | |
| to the repository:</p> | |
| <p class="align-center"><a href="../../../images_www/articles/73/ide/mercurial/mercurial-commit-dialog.png" rel="lytebox" | |
| title="Commit dialog displaying files about to be committed"> | |
| <img src="../../../images_www/articles/73/ide/mercurial/mercurial-commit-dialog-small.png" | |
| class="b-none margin-around" alt="Commit dialog displaying files about to be committed"></a></p> | |
| <p>The Commit dialog lists:</p> | |
| <ul> | |
| <li>all locally modified files</li> | |
| <li>all files that have been deleted locally</li> | |
| <li>all new files (i.e. files that do not yet exist in the repository)</li> | |
| <li>all files that you have renamed. Mercurial handles renamed files by | |
| deleting the original file, and creating a duplicate using the new | |
| name.</li> | |
| </ul> | |
| <p>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.</p> | |
| <p>To perform the commit:</p> | |
| <ol> | |
| <li>Type in a commit message in the Commit Message text area. Alternatively, | |
| click the Recent Messages ( <img src="../../../images_www/articles/73/ide/mercurial/recent-msgs.png" | |
| alt="Recent messages icon"> ) icon located in the upper right corner to | |
| view and select from a list of messages that you have previously used.</li> | |
| <li>After specifying actions for individual files, click Commit. The IDE | |
| executes the commit and sends your local changes 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 encoding of committed files returns to black.</li> | |
| </ol> | |
| <a name="issues"></a> | |
| <h3>Updating Issues</h3> | |
| <p>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:</p> | |
| <ul> | |
| <li><strong>Issue Tracker:</strong> Specify the issue tracker that your repository uses, by selecting an issue tracker from the drop-down list. The drop-down provides you with a list of all issue trackers registered with the IDE. If your repository's issue tracker is not registered, click the New button to register it.</li> | |
| <li><strong>Issue:</strong> Specify the issue ID. You can do this by typing in the ID, or part of the description.</li> | |
| </ul> | |
| <p>You can also specify the following options:</p> | |
| <ul><li><strong>Resolve as FIXED:</strong> When selected, the status of the issue is marked as Resolved.</li> | |
| <li><strong>Add Commit Message from Above:</strong> When selected, the commit message is added to the issue.</li> | |
| <li><strong>Add Revision Information to the Issue:</strong> When selected, the issue is updated to include the revision information such as the author, date, etc. You can click Change Format to modify the format of the revision information that is added to the issue.</li> | |
| <li><strong>Add Issue Information to Commit Message:</strong> When selected, the issue ID and summary are added to the commit message. You can click Change Format to modify the format of the issue information that is added to the message.</li> | |
| <li><strong>After Commit:</strong> When selected, the issue is updated after you commit the changes.</li> | |
| <li><strong>After Push:</strong> When selected, the issue is updated only after the changes are pushed to the repository.</li></ul> | |
| <a name="pushing"></a> | |
| <h3>Pushing Local Changes to the Shared Repository</h3> | |
| <p>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 <tt>Team</tt> > (<tt>Mercurial</tt> >) <tt>Fetch - [Mercurial repository name] </tt> from the | |
| main menu. | |
| After you perform a successful Fetch, your local repository becomes synchronized with the shared repository.</p> | |
| <p>To push changes, choose <tt>Team</tt> > (<tt>Mercurial</tt> >) <tt>Share</tt> > <tt>Push to - [Mercurial repository name]</tt> from the | |
| main menu. The output from a successful Push will list any changesets created.</p> | |
| <p class="notes"><b>Note:</b> 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.</p> | |
| </div> | |
| <a name="summary"></a> | |
| <h2>Summary</h2> | |
| <p>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.</p> | |
| <div class="feedback-box"> | |
| <a href="/about/contact_form.html?to=3&subject=Feedback:%20Mercurial%20User%20Guide">Send Feedback on This Tutorial</a></div> | |
| <br style="clear:both;"> | |
| <a name="seeAlso"></a> | |
| <h2>See Also</h2> | |
| <p>For related material see the following documents:</p> | |
| <ul> | |
| <li><a href="http://wiki.netbeans.org/HgNetBeansSources">Using Mercurial to work with NetBeans Sources in the IDE</a></li> | |
| <li><a href="mercurial-queues.html">Mercurial Queues User Guide</a></li> | |
| </ul> | |
| </body> | |
| </html> |