Implementing Mercurial Version Control System with Netbeans
Implementing a version control system to manage your code is an essential part of any efficient web development team or open source project. You can also use it to manage your own personal coding projects. If you are unfamiliar with how a version control system works, there are some great articles on the concepts of version control on the Internet. In this article, I will share how to integrate the Mercurial VCS with Netbeans IDE.
Why I Chose BitBucket/Mercurial
I chose BitBucket for my current development project because it offered free private repositories, unlike Github. Github does have some cool features that BitBucket lacks, like the Network Graph, so I'll probably use it if I ever start a public open-source project.
Preliminary Setup
Before you set up the main configuration, you have to do this things:
Main Setup
The next thing is to check for mercurial.ini at the following location:
- UNIX-based systems: ~/.hgrc
- Windows XP: C:/Documents and Settings/MY_NAME/mercurial.ini
- Windows 7: C:/Users/MY_NAME/mercurial.ini
On Windows, you may have to create the file. Enter this into the file:
[ui]
; editor used to enter commit logs, etc. Most text editors will work.
editor = notepad
username = MY_FIRST_NAME MY_LAST_NAME <MY_NAME@example.com>
The email address should stay enclosed in the less-than/greater-than symbols.
Next, fire up Netbeans and click "New Project". When I create the project, I like to keep the Netbeans metadata in a separate directory as it is irrelevant to collaborators. My structure may look like this:
- /project_dir
| - /nbproject (netbeans metedata files)
| - /source_files (project source files)
When we sync a folder to our repo, we will just sync the source files' folder. Before we initialize the project, we need to create the repo on BB. After that is done, we can initialize the project.
Initializing the Project with HTTPS
Skip to the next section if you would rather use SSH.
After you create the repository on BB, you will see a command to clone your repo. Instead of copying the entire command ($ hg clone https://me@bitbucket.org/my/repo), just grab the HTTPS url.
Back to Netbeans. Go to Team > Mercurial > Initialize Project. Select the sources folder of your project and click OK. After that, open Team > Mercurial > Properties.... Then paste the URL into the "default-push" and "default-pull" fields. The Mercurial username should already have been pulled from the mercurial.ini file, but if it isn't there, enter MY_FIRST_NAME MY_LAST_NAME <MY_NAME@example.com> as the value for username.
When you save those connection settings, Netbeans will attempt to connect to BB. If it finds your account, it will ask for your BitBucket credentials. If you enter those correctly, then you will have full access to your remote BitBucket repo.
Using BitBucket, Mercurial, and SSH
Many developers like to connect and authenticate their VCS with SSH instead of HTTPS because SSH is more secure and better for syncing large projects. It is a little harder to set up your VCS configuration with SSH, but it is still possible.
First, download and install PuTTY, a well known SSH client for Windows. I would recommend downloading the MSI installer that includes all of the PuTTY tools (other than PuTTYtel). We will need PuTTY, PuTTYgen, and Pageant.
Generating the SSH key
After you install the PuTTY program package, open PuTTYgen. At the bottom of the window, make sure SSH2-RSA is selected. Then click "Generate". It will ask you to wave you cursor over a black area to create randomness. After you create enough randomness, it will produce an SSH key. Change the "Key Comment" field to something you will remember. I would make it the email address that you used to register on BitBucket. Then write a secure password that you will remember in the "Key Passphrase" field. Confirm the password in the following field.
Saving the SSH Key
Now we want to export a public SSH key, but this it is a convoluted process as BitBucket doesn't accept the syntax that PuTTY uses to export and save public SSH keys. We will have to do a short workaround to fix that.
Click the "Save public key" button. The standard place to save SSH key files is in C:/Users/You/.ssh (you may have to create the folder). In XP, the folder would be at C:/Documents and Settings/You/.ssh. The period in the front of the ".ssh" folder means it is hidden. Hidden folders are invisible by default, so you should make them visible for this to work. Save your public key in the .ssh folder. Name the file something like "yourname_pub". Also save a private key in the same folder preferably with the same name (minus "_pub").
Syntax Incompatibility Workaround
Since BitBucket doesn't read the public SSH key files that PuTTY creates, we have to adjust our generated file a bit. Minimize PuTTYgen (don't close it), and open the .ssh folder. Open the yourname_pub public SSH key file in a text editor (notepad or your favorite code editor will work). Go back to PuTTY and copy the public key from the frame. It looks something like this:
ssh-rsa a&bnuch0f-r@dom^ChaRatcers345a&bnuch0f-r@D0m= my@email.com
After you copy this key, go over to the public key file you opened and paste it over the entire file so the pasted key is all that the file contains. Make sure it is all on one line. Now go back to BitBucket and click on the Admin tab which is the rightmost tab on the page. Scroll down to section of the page where you can add an SSH key to your account. Either you can paste the public key (the one you just pasted into the file) into the form field, or you can upload the public key file ("yourname_pub").
Integrating SSH/Mercurial with NetBeans
After you add the key, go back to the "Overview" tab all the way to the left of the page. Underneath your repository's name, there is a command to clone your repo. Click on SSH and copy just the ssh:// URL, not the whole command ("hg clone ssh://...."). Go to NetBeans and open Team > Mercurial > Initiate Project. Select the sources folder in your project and click OK. Next, go to Team > Mercurial > Properties.... Paste the ssh:// URL that you copied into the default-push and default-pull fields.
Other Necessary Configurations
Now that you've initiated the project, you need to make some modifications to a Mercurial configuration file. Open the sources folder of your project. Look for the .hg folder (again, a hidden folder) and open the hgrc file that is in that folder. At the top of the file, add this code:
[ui]
# path to the plink executable
ssh = "C:/Program Files/PuTTY/plink.exe" -l hg -i "C:/Users/YOU/.ssh/YOU.ppk"
# modify this path to lead to your private SSH key
Now open Pageant, one of the programs bundled with PuTTY. You should see an icon appear on your system tray. Click (or right-click depending on your version of Windows) the icon and click Add Key. Navigate to your private SSH key and open it. It will ask you for the key's password. Enter the password, and it will cache it so that you will not have to enter the password every time you connect via SSH. Now you are set! Go to Netbeans, commit your project in the Team menu, and you can make your first push to BitBucket over SSH!
Conclusion
Now you can do the repository commits and pushes right through Netbeans, never touching the command line. The Team menu in Netbeans will give you even more commands you can use to manage your repository. If I was unclear about anything in this post and it is hanging you up, please let me know.
Posted September 7, 2011 at 10:07AM by Eli Mitchell in workflow, Neatbeans, Mercurial, VCS with 0 responses
