A Guide To Mercurial

http://java.dzone.com/articles/mercurial-guide?utm_source=feedburner&utm_medium=feed&utm_campaign=Feed:+javalobby/frontpage+(Javalobby+/+Java+Zone)

Mercurial is a distributed version control system. Each user has revisions in their local repository. There is also one shared repository, typically hosted on the internet. Mercurial is convenient for teamworking, as well as working alone where you can easily roll back to an older version of the project.

Important: You should read the entire guide first, before you start working with Mercurial, especially the working rules at the end. Also, it's a good idea to save a manual backup of your files (although not required)

There are many ways to use Mercurial. In this article we'll explain how to use Mercurial in a Java project with a plug-in for Eclipse.

(This is partially based on: http://ekkescorner.wordpress.com/blog-series/git-mercurial/step-by-step-install-mercurial-on-osx-ubuntu-and-windows/ )

1. Download Mercurial from http://mercurial.berkwood.com, install, and verify that the second option is checked. Add the installation path to the search path
   
   
2. Hit “Finish” and you’re ready. Open “Cmd” and type:
   
   
   view source

   print?

   1.hg --version
   Now you’re done. Mercurial is installed on Windows.(Now you have verified that you can use it from command prompt on Windows)
3. In Eclipse, go to Help/Install New Software and install from the  following update site:http://hge.javaforge.com/hgeclipse
   
   
   
   It can take a while. Also, if there is a problem at the intallation, you can uncheck the second option and try again.

Now we'll see how to work with Mercurial, broken into two parts: for the user who initially created the project, and for the user(s) who are also working with this project.

For the user who initially created the project

• Create a new Java project in Eclipse, hit right mouse click on it: Team /Share Project…  This will cause a star to appear next to the project 
  
  and confirm.
• Create a repository on the internet, for example on one of these sites:
  http://www.selenic.com/mercurial/wiki/index.cgi/MercurialHosting (Google code, Codeplex, etc', notice the clone address that the sites give you)
  

Now we'll see an example of using the repository.

Create a class and write in something, i.e. "try1" as a comment. Now right click on Project/Team/Commit.



A window will open, write your commit message, check all the files, and confirm. Now the revision is saved on the local repository on your computer.

Again, right click on  project, click Team/Push, and enter the clone project address from the internet repository, with your username and password and confirm.

Now the revisions from your computer are uploaded to the shared repository on the internet.

Now we'll change the line "try1" to "try2", save, and commit.

At this point, imagine if you had made a lot of changes to the project, and now it's not working and you don't remember all the changes you made. So we want to return to the previous revision – "try1".

Right click on the project, and click Team/Pull. 



Do not click on merge/update or anything like that at this point!. Now the revision from the internet repository is downloaded to your local repository.

Using the Team/Switch To.. menu item, choose the "Revisions" tab on the dialog, and choose the revision with the message you want to rollback to, (i.e. "try1"), and confirm.

 

That's it, we're back to the revision we wanted. There is also a revert option.

 For Users Working on an Existing Project

The more convenient option, but which causes the project hierarchy (on the left) to look a bit different.Using the File / Import / Mercurial / Clone repository using Mercurial. 


Type in the clone project address, and click confirm.

There are a lot of options under the Team menu, such as options for branches, and merge, which can be problematic (see below)

Important working rule

Without maintaining these rules, working with Mercurial can be very frustrating and cause problems, mainly when trying tomerge. In fact, the merge option can still be problematic even when maintaining these rules!

Do not create a situation where more than one user is working on the same file on the same time (What will happened to this file on merge and which file will be chosen ?)

Short explanations of actions:

Commit 
Save the changes you made on the revision to your local repository.

Push
Upload all the revisions from your local repository to the internet.

Pull 
Note, this meaning is just for pull, without checking the merge/update option, no merge afterwards
Download all revisions that other users have uploaded to your local repository from the server (shared repository). If the merge option is chosen, it merges your revision with the latest changes, otherwise, no changes will be made at your project.

Switch to 
Make sure to commit first! 
Switches to another revision.

Merge
Choose the required revision, usually the last one that you didn't upload, and merge the changes with your revisions.

Each time when you work, before you start changing things, if you do not have the last revision – pull and then merge with the last revision.

When you have made your changes, commit and push. It's recommended to do this from time to time.

When you push or pull, you can probably check both of the following options: force push, and abort when timeout occurs