This will take a quite long time (>160MB to fetch) . Time enough to think about the ideas behind Mercurial (or, more generally, distributed source code managers (DSCM)). If you know all about DSCM, you can skip this safely and proceed to IIb, „checking out the sources”.
Unlike CVS or SVN, a DSCM does not rely on a single central repository. Instead, everyone who wants to use the source code, hold their own copy of the master repository. Such a copy is called a clone in DSCM-Speak. To create a clone, you perform the operation clone - as you might have guessed. Such a clone is in fact just a directory on your hard drive. Note: In Linux and Mac, the directory might seem empty. It is not. It contains at least a subdirectory called .hg which is hidden in unix-like operating systems by default. You can make a backup by simply copying it or with any other backup mechanism you might to prefer. From this clone, you create a working directory with the sources you want to work on. Remember: The clone is really a clone of the master repository and as such it contains every single commit, tag and branch that occurred to the master repository – so you can check out any repository position you like to your working directory and you can easily switch to any other repository branch without the need for an internet connection.
With this local clone, you can work as with any other SCM. If you know Subversion/Subclipse, you’ll find this quite familiar: You commit your changes to the repository; you can update, branch, tag, and so on. The only difference is: You do not need to bother about other members of the development team, because all changes go only to your very own repository clone and nobody will cry if you totally mess it up (not even you because you can always create a new clone from the master). If you do not want to make a new clone but only want to keep up with changes on the Master, you can pull your repository from the master, merge incoming changes with your changes and then update the source directory to adapt the changes.
If you feel, however, that your changes should go to the master repository, you should first pull any changes that might have happened on the master in the meantime, merge if necessary, resolve all conflicts (if any) and then push your Repository to the master. If you do not have push rights, you can ask a master maintainer, to pull your changes, or you can send them a push request by e-mail, containing a diff of your repository to the master.
Now the clone operation from IIa is probably finished. You are presented a dialog „Select working directory revision”. Most probably you’ll want the bleeding edge, and thus, you might want to select the Revision that has the tag „tip”. Then click Next, and you’ll see all Elexis Projects that are part of this repository. Select those you want to import into your Eclipse workspace and click finish
After this, you’ll probably see lots of errors. First try a full rebuild (Project->clean->clean all). If some funny errors persist, you probably forgot to switch your workspace to UTF-8.
Still remaining errors are mostly due to unresolved dependencies. Probably you just want to close or remove the involved projects. Or, you clone repositories with the missing projects into the same workspace, which is perfectly possible. You can even mix projects from subversion and mercurial repositories.
From time to time you should integrate changes from the master repository into your clone to prevent it to differ to much from its parent. To do this, right-click on one of the projects from this repository and select team->pull. This will pull changes of ALL projects from the same repository.
Note: In plain Mercurial, this will not update your workspace. See next paragraph. The Eclipse plugin gives you the option to update after pull automatically by checking the respective checkbox in the dialog.
The pull operation can lead to a two-headed repository since there might be changes from somewhere else that originate from the same common revision than your own changes. You can merge the two heads with right-click on the project and team->merge. Again, the Eclipse plugin offers an option in the pull dialog to merge automatically if no unresolved conflicts are found. If there are conflicts in the files that can’t be resolved automatically, you have to resolve them manually. HgEclipse will open some merge View depending of your operating system. Here kdiff3 as found on Windows and KDE based Linuxes (with Gnome you’ll probably prefer ‚meld’): On the leftmost side you have the file as merged up to now and the right two panels show the two parents of the merge. You can decide which lines from which parent to move into the result and then save.
Your workspace can be set to any of the branches defined in the repository. Therefore by default a repository pull will not be reflected automatically in your workspace. To Update a project in your workspace, right-click on the project and select team->update.
It is recommended to commit your changes frequently. That way you have always the possibility to return to an earlier state if something went wrong. To commit, simply right-click on the project and select team->commit. Enter a commit-message and you’re done. Note: This will only change your own repository. To propagate your work to the parent repository, you must push. The rule of thumb is: Commit whenever you finished a distinct piece of work, push whenever you want to make the sum of your commits available to others. This involves some amount of testing bevore pushing.
This is a bit tricky first, so please read carefully:
If you are not used to DSCM’s: Mind the word „clone” above: All changes go only to your local clone. You’ll need to push them to the master (or send the master maintainer a pull request).
WARNING: If you right-click on the plugin and select „delete”, you’ll remove the project from the repository. And with the following commit and push your delete will be propagated through the hierarchy. Of course, this will not really delete anything, you can still recreate it using an older revision, but such actions can lead to some bad vibrations within the team...
So you better do the following: You can, instead of removing the project, just close it by right-clicking an choosing „close”. Or, if you really want to remove it: Select Team->disconnect. After doing this you can safely delete it.If you are a group working on the same subset of elexis, or if you are working with different computers, having a separate repository clone on every computer will probably not suffice to fit your needs. You’ll need some „regional” master repository to collect commits from distributed local repositories. This regional master synchronizes itself with the global master.
Fortunately, this is quite easy with Mercurial. You need only a pc with active internet connection or a repository on a public server (such as bitbucket.org) . If you use a private server, just install Mercurial there (eclipse is not required) and create a local clone with
hg clone http://elexis.hg.sourceforge.net/hgroot/elexis/elexis-base
then, serve this clone with
hg serve -d
And everybody from your team with access to that server (e.g. via internet or via VPN) can clone it with
hg clone http://your-url:8000
(Maybe you’ll have to change some firewall rules, though). By default, users have only read access (i.e. clone and pull).
If you want to allow push, you can either set up SSH on the server, or, if you connect through a secure path anyway, eg. inside a closed LAN or VPN, you can add the following lines to
[web]
allow_push = *
push_ssl=false
Do not use this hack for public servers since it imposes a maior security risk!
This way, everyone having access to the server can pull and push their data. So your private subproject can be developed independently from the master repository. Whenever you feel that the time has come to share your work, you do one of the following, depending on your preferences and access rights:
Having set up your repository for sharing gives you an additional feature for free: Web access to your repository. Simply point your favorite web browser to http://your-url:8000.
And even more: You can subscribe to an RSS feeder that tells you whenever something changed in the repository.
You might want to try this with the elexis main repositories
The hg serve command only serves the repository it was called from and by doing so, it occupies a port (normally 8000), making it inaccessible for other instances. If you want to share more repositories, you can either call it from each repository, providing a distinct port number, e.g. hg serve -d -p 8001.
Or, a bit more difficult to install but more flexible when running: Serve via cgi from a webserver. I use lighttpd which is much easier to configure than the ubiquitous Apache (that seems here oversized)
It is possible to use an existing SVN repository as master for a mercurial repository (and its descendants). This can be useful for collaboration with different groups.
If you plan to host your Mercurial repository on a debian-based computer (debian, ubuntu etc), this is quite easy. Just install the package hgsvn. This gives you the following commands:
hgimportsvn <url> - Checkout an existing SVN repository (If it is your first access to this svn repository, you should checkout with svn checkout first to set ssh keys or username correctly) . hgpullsvn - pull any changes from the svn repository into the mercurial repository. Note: You must do this after hgimportsvn to initialize the Mercurial repository correctlyAfter doing this, you have a chimaere repository with a shared workspace. Use hg update to integrate hg changes into the workspace. Use hg commit to propagate workspace changes into hg. Use hgpullsvn to fetch svn changes into the workspace. Use svn commit to send workspace changes to the svn repository. Please note: while the svn commands work on the central repository, the hg commands work only with the local hg repository. To propagate them, you must use hg push <url> (or hg pull from elsewhere)
A Tag is a label that marks a specific step of development with a human understandable name. In fact, every single commit has automatically a unique name such as c3445543dfsdfcdea, but this is not very useful for humans. A tag is just a meaningful alias such as „elexis 2.1 beta 4 rev2”. You can always create a working directory that contains such a development position by updating to that given tag.
In contrast, a branch denotes a point where the repository is split in two. Consider a public release such as „elexis 2.0”. There will still be a trunk with continuous development leading to release 2.1, but also „elexis 2.0” will not be static like a tag, but will receive bugfixes and continue eventually to 2.0.1 and so on. While it is possible in mercurial to create branches, it is more common to use clones for this purpose. So the elexis master repository has clones for elexis 1.4 and 2.0 branches.Mercurial: The definitive guide
The Mercurial web site
Short tutorial