Mercurial

Mercurial is a distributed version control system. Instead of simply copying files from a designated repository, Mercurial creates fully-functional clones of the original repo. These new repositories can do everything the original could (accept checkins, manage changesets, communicate with other repositories, etc). This means that users can create a local clone of the original repository and commit changes to the local clone; in contrast, a centralized version control system like SVN only allows checkins to the original repo.

In addition, Mercurial repositories can also communicate with any other Mercurial repositories. Thus, if someone had some experimental changes for you to try, you can simply pull those changes from their repository rather than directly copying the files over and merging your own changes by hand.

So instead of having to commit changes to one centralized repository (as with SVN) - you can only commit changes to your local repository. And instead of "checking out" code from a repository - you instead clone the entire repository locally using a command like

AstroBEAR uses a hierarchical repository model based on the Red Hat/Subverison model, but which runs on Mercurial. We have a stable repository and a development repository on our servers (NOTE: Currently the stable repo is seriously out of date. Use the development repository until further notice.). Users clone these repositories for their own use, and can pass code around among themselves. Once this code has been thoroughly tested, we check it into one of the two repositories for wider public use.

How to Use Mercurial

AstroBEAR comes in two flavors: stable, which is thoroughly tested and is as reliable as we can make it; and development, which has undergone some baseline testing but is not guaranteed to be as bulletproof as the stable build.

NOTE: At the moment, the development build is the fully-functional build, and should be the build you use for preference. Once the beta-testing period is over, the stable build will be updated.

To obtain the stable build of AstroBEAR, run the following command on a Linux/Mac OS system with Mercurial installed:

hg clone ssh://clover.pas.rochester.edu//var/repositories/scrambler_devel NewScramblerDirectory

Use the development version at your own risk. Not all features may be tested with this version.

Mercurial commands can also be broken into two categories. Ones that change source files - and ones that only change changesets.

Mercurial commands that change the changesets are:

• hg pull/push
• hg rollback
• hg ci
• hg resolve

Mercurial commands that change the source files are:

• hg update
• hg merge
• hg revert

Additionally there are mecurial commands that can be used to add/remove/move files that are under revision control

• hg add
• hg remove
• hg mv

Finally there are mercurial commands that display information about the repository

• hg log
• hg heads
• hg parents
• hg export
• hg status
• hg diff

Now if the repository you cloned or last pulled from gets updated with a new feature or bug fix etc… you can pull the new changes from the repository by going to your local repository directory and running

hg pull ssh://clover.pas.rochester.edu//var/repositories/scrambler

or if joe made changes that you want to update your repository with but hasn't checked them into the main scrambler repository on clover you can pull directly from joe's repository

hg pull ssh://grass//grassdata/joe/ScramblerWithBugFix

Alternatively joe could have pushed his changes into your (Sally's) repository (if he had write priveleges) by running

hg push ssh://grass//grassdata/sally/NewScramblerDirectory

Of course pulling or pushing does not change any of the actual source files - it just collects all of the new changesets but doesn't apply any of them to your files. However, if you've made local changes it is always a good idea to commit them before pulling. To see what files you've modified you can run

hg status -q

or

hg diff

If there are files you've modified that you didn't intend to you can run

hg revert file.f90

Then run

hg ci -m "made these changes to these files"

Now you can safely do almost anything without fear of losing your changes (Just don't delete the entire directory including the mercurial files)

Now you can run

hg pull SomeRepositoryAddress

To see the new changeset you've pulled you can run

hg heads

If you realize you pulled a changeset you didn't want just run

hg rollback

This will restore your repository to it's pre-pull state

If it is a changeset that you want to apply then you will need to perform a merge Before you run hg merge I strongly recommend you create/edit your .hgrc file to include merge=internal:merge. In fact, you must have an .hgrc file before you can check in to your repository. This can be done by creating an .hgrc file in your $HOME directory with the following in the text file:

[ui]
username = Sally
merge=internal:merge

Otherwise you will be presented with vi sessions with three windows showing your version, the pulled version, and the merged version which you can edit - which can all be a little confusing at first

To merge the heads run

hg merge

This will list all of the files that are merged as well as files that have conflicts. You should keep this list visible so that you are sure to manually go through each file and resolve the conflicts. Conflicted files will have a .orig file in the same directory for reference - and the conflicting regions of the file will be marked up as

<<<<<<< local
my changes
=======
other changes
>>>>>>> other

These can apparently be nested within each other - so it can be a little tricky to sort out…

If you realize that you did not want to merge in the first place you can still recover your original pre-pull files by running

hg rollback
hg revert --all

The rollback will remove the last pulled changeset and the revert will modify all of the files to the remaining changeset (yours)

If the merge is what you want and you manually edit all of the conflicting files you can let mercurial know the conflicts have been resolved by running

hg resolve -m

And then merge the changesets by committing

hg ci -m "merged heads"

Now if you look at the log by running

hg log | less

you will see a new changeset with two parents (the two changesets you just merged)

If at this point you realize something went terribly wrong during this whole process and you want to revert to your original files you have to actually abandon the directory you are in. Mercurial only allows you to rollback the last changeset modification which in this case would be the commit. You can rollback the commit and revert to a previous changest - but the pulled changeset you didn't want will still be there and mercurial will still think you have outstanding uncommitted merges. The easiest thing to do is to clone the repository at the earlier changeset in a new directory.

hg clone scrambler_post_merge -r 251 scrambler_pre_merge

This will not pull any changesets post 251 and will allow you to revert to your previous data.

If you want to check in your merged revision to the central repository it is always a good idea to first pull from the central repository to ensure that any merging will be done in your local directory. After resolving the merge and committing the merged version you should be able to go to the central repository and pull your new changeset from there. Then run hg update to update the files in the central repository. Of course you should make sure your revision compiles and runs and passes a lot of tests before putting it in the main repository. There is currently a scrambler_devel repository on clover that can be used for this purpose.

Finally, if you forget to commit your local changes before pulling you can still run

hg rollback

to remove the pulled changeset. But don't run hg revert since that will destroy your local changes since your last commit or clone

If you've run hg merge, however, and want to recover your original files than I'm afraid you are out of luck. The state of your files will have been lost and cannot be recovered. The only way is to resolve the conflicts and check your local changes in along with the merged heads in your next commit.