I got asked (being a Java developer) about what was involved in creating an Eclipse Plugin for Mercurial. Well in true Google style, why invent when somebody probably already has. A quick check finds Mercurial Eclipse by VecTrace.
Now until last week, I’d never heard of Mercurial, so this is really an introduction to somebody that has no idea.
What is Mercurial?
Mercurial is a fast, lightweight Source Control Management system designed for efficient handling of very large distributed projects.
Ok, so big deal, I use CVS. I also use Subversion (SVN) for my Apache contributions, and also for MySQL GUI products. Why do we need another Version Control Product? Mercurial is a Distributed Software Configuration Management Tool. The following is from the Mercurial Wiki
A distributed SCM tool is designed to support a model in which each Repository is loosely coupled to many others. Each Repository contains a complete set of metadata describing one or more projects. These repositories may be located almost anywhere. Individual developers only need access to their own repositories, not to a central one, in order to Commit changes.
Distributed SCMs provide mechanisms for propagating changes between repositories.
Distributed SCMs are in contrast to CentralisedSCMs.
So, clearly a distributed model would well in a large distributed organisation where external factors limit continous access to a single central repository. Low Bandwidth, Poor Internet Connectivity, being on a plane, and travelling are all things that would make a distributed model a more ideal solution. I know I’ve taken my laptop away, and being an “Agile Methodology” developer, I commit often. When you have several days of uncommitted work it goes against the normal operation.
You can get more information at the official website at http://www.selenic.com/mercurial. A few quick links are: Quick Start Guide, Tutorial, Glossary.
su - cd /src wget http://www.selenic.com/mercurial/release/mercurial-0.9.tar.gz tar xvfz mercurial-0.9.tar.gz cd mercurial-0.9 # NOTE: Requires python 2.3 or better. python -V python setup.py install --force
A quick check of the syntax.
$ hg Mercurial Distributed SCM basic commands (use "hg help" for the full list or option "-v" for details): add add the specified files on the next commit annotate show changeset information per file line clone make a copy of an existing repository commit commit the specified files or all outstanding changes diff diff repository (or selected files) export dump the header and diffs for one or more changesets init create a new repository in the given directory log show revision history of entire repository or files parents show the parents of the working dir or revision pull pull changes from the specified source push push changes to the specified destination remove remove the specified files on the next commit revert revert files or dirs to their states as of some revision serve export the repository via HTTP status show changed files in the working directory update update or merge working directory
A more detailed list:
$ hg help Mercurial Distributed SCM list of commands (use "hg help -v" to show aliases and global options): add add the specified files on the next commit annotate show changeset information per file line archive create unversioned archive of a repository revision backout reverse effect of earlier changeset bundle create a changegroup file cat output the latest or given revisions of files clone make a copy of an existing repository commit commit the specified files or all outstanding changes copy mark files as copied for the next commit diff diff repository (or selected files) export dump the header and diffs for one or more changesets grep search for a pattern in specified files and revisions heads show current repository heads help show help for a given command or all commands identify print information about the working copy import import an ordered set of patches incoming show new changesets found in source init create a new repository in the given directory locate locate files matching specific patterns log show revision history of entire repository or files manifest output the latest or given revision of the project manifest merge Merge working directory with another revision outgoing show changesets not found in destination parents show the parents of the working dir or revision paths show definition of symbolic path names pull pull changes from the specified source push push changes to the specified destination recover roll back an interrupted transaction remove remove the specified files on the next commit rename rename files; equivalent of copy + remove revert revert files or dirs to their states as of some revision rollback roll back the last transaction in this repository root print the root (top) of the current working dir serve export the repository via HTTP status show changed files in the working directory tag add a tag for the current tip or a given revision tags list repository tags tip show the tip revision unbundle apply a changegroup file update update or merge working directory verify verify the integrity of the repository version output version and copyright information
Mercurial Eclipse Plugin
The plugin is still in it’s early days, but the “FREEDOM” of open source enables me to easily review. After a quick install and review of docs, I shot off an email to the developer, stating why I was looking, and while I have other projects on the go, I asked what I could do to help. It’s only be 2 days and we have already communicated via email several times on various topics. That’s one reason why I really love the Open Source Community. Generally people are very receptive to feedback, comments and especially help.
- Help ->Software Updates-> Find and install…
- Select “Search for new features to install”, click Next
- Click “New Remote site…”
- Enter following details and click Ok
- Name: MercurialEclipse Beta site
- URL: http://zingo.homeip.net:8000/eclipse-betaupdate/
- Follow the prompts to accept the license and download.
So now with Eclipse, on a project you can simply go Right Click -> Team -> Share Project -> Select Mercurial
A Quick Mercurial Tutorial
Of course the quickest way to learn about using Mercurial is to look at an existing product. So taking this plugin project for a spin.
$ cd /tmp $ hg clone http://zingo.homeip.net:8000/hg/mercurialeclipse com.vectrace.MercurialEclipse $ hg clone com.vectrace.MercurialEclipse example $ cd example # Create some new dummy files $ touch test.txt $ touch html/test.html # View files against respository status $ hg status ? html/test.html ? test.txt # Add the new files $ hg add adding html/test.html adding test.txt # Commit changes $ hg commit -m "Testing Mercurial"
So other then the second clone command (which enabled me to not mess up the original repository and to test distributed handling next), this is just the same as CVS (checkout, diff, add, commit)
# The Distributed nature involves first Pulling from the "upstream" respository $ hg pull ../com.vectrace.MercurialEclipse pulling from ../com.vectrace.MercurialEclipse searching for changes no changes found # Confirm our new file is not in "upstream" respository $ ls ../com.vectrace.MercurialEclipse/test.txt ls: ../com.vectrace.MercurialEclipse/test.txt: No such file or directory # Push local respository changes to "upstream" respository $ hg push ../com.vectrace.MercurialEclipse pushing to ../com.vectrace.MercurialEclipse searching for changes adding changesets adding manifests adding file changes added 1 changesets with 2 changes to 2 files $ ls ../com.vectrace.MercurialEclipse/test.txt ls: ../com.vectrace.MercurialEclipse/test.txt: No such file or directory
Hmmm, missed something here. The Quick Start Guide docs seems to want to work back into the original respository, pulling in changes from the “downstream” repository, then executing a merge and commit command. I don’t want to do this just in case I start messing up the original repository. Time for me to create a new standalone repository so I don’t screw anything up. Stay tuned for an updated tutorial.
Of course this is very basic, I need to look into commands used in CVS like login, tagging (versioning), branching, diffing revisions and merging but this is a start.
I do have a concern with the number of distributed respositories, when and how do you know you are in sync with the “master”, indeed what is the “master”. It does merit some investigation to see what management is in place, like identifying all respositories, and comparing for example.
Ok, so now I’ve got a grasp on Mercurial, time to review the Java Code and see what works and what doesn’t in the Eclipse environment. Of course I don’t use Mercurial so what I may consider as functionality required, may be lower priority to those users out there. Any feedback I’m sure will be most appreciated by the original developer.
There is now a better public release of Mercurial Eclipse see
for more instruction
Please use the Eclipse Update site below instead
Name: Vectrace (Mercurial Eclipse plugin)
As the other site depends om my home computer.
/Zingo Mercurial Eclipse Plugin Author