Mercurial

Mercurial is a source code management system. The main difference from SVN is that it is distributed vs. centralized.

Mercurial is available at: http://mercurial.selenic.com/

A nice tutorial is available at: http://hginit.com/


TODO: Add a very simple tutorial directly related to using Mercurial with a few Euphoria projects.

Using Mercurial for Euphoria development.

Refer often to the above links as well as to Mercurial: The Definitive Guide. These resources are invaluable and give much more information than we can provide here.

Also make sure you are using your "hg help command" often at the command line.

Here are some commands with which you should become very familiar:

hg clone 
hg pull 
hg incoming 
hg update 
hg merge 
hg commit 
hg outgoing 
hg push 
hg log 
hg tip 
hg branch 
hg branches 
hg add 

The following examples assume a *nix command line. The overall process should still be the same for other operating systems and whether you are using a graphical client or the command line.

Your basic workflow should be something like this:

Create your "gold copy" and your working directory.

  • Clone the main repository. This is now your "gold copy" of the main repository, not a working directory. You should not modify it directly until you are ready to push your changes back out. You should only have to clone the main repository once, after that use "pull" and "update" to keep it current.
    • Note: Don't clone a branch of the main repository (see below). Always clone the whole project on which you are working.
  • Clone your gold copy of the main repository into a working directory. You can and should use a different working directory for every bug/ticket/feature on which you are working.
    • Use the "-b" branch command line switch if you want to work only on a specific branch, such as "4.0". However, every time that you pull changes into your working directory be aware that you must continue to use the "-b" branch switch, or else you will pull in changes from outside your branch and your working directory will now be mixed. That's generally bad.
  • Make your changes to the files in your working directory and test them.
  • Commit your changes. This updates the changeset in your working directory.
    • Use the "-m" switch and a string to describe the reason for your commit. If you do not include "-m", Mercurial will open up an editing screen for you anyway.
    • If you include a reference to a specific ticket, then when you push your changes to the main repository that will be picked up by the server and the ticket entry will be updated automatically. Don't wrap the ticket reference in Creole tags, though, that seems to hide the reference from the server.

Incorporate others' changesets.

Now you have a valid, tested changeset which you want to share with others. You are about halfway there.

  • Make sure that your gold copy of your repository is up to date using "incoming".
    • If no changes are incoming then you are already up to date.
    • Otherwise use "pull" and "update" to make your gold copy current.
  • Make sure that any relevant changes get merged into your working copy.
    • Use "incoming" in your working directory to see if there are any changes.
    • If there are changes listed in your incoming, use "pull" to bring them into your working directory.
      • Don't forget to use the "-b" branch switch if you are working on a branch!
    • Next you will need to use "merge" or "update" in order to apply the upstream changes to your working directory.
      • If you merge, you will have to commit those changes as well.
      • If you merge, you should re-test to make sure nothing has broken.

Push the changes to the main repository

Now everything in your working directory should be up to date unless someone snuck a change into the main repository while you were doing all of that.

  • Use "push" from your working directory into your gold copy of the repository. This should be straightfoward and "hg status" should show no pending changes, and "hg tip" should show the same revision as your working directory (unless it's a branch).
  • Use "outgoing" from your gold copy of the repository to make sure that only the changes of you are aware are going upstream. If not then you will have to update your gold copy again.
  • Use "push" from your gold copy of the repository to the main repository.

If everything has gone well then the main repository should reflect your change.

This is just a simplification. Note that working with a prior revision is similar to working with a branch, and when you push it upstream it may create its own branch. Or else it will give you a lot of errors. Someone else can edit this and clarify it.

An example command line session

~/$ hg clone https://scm.openeuphoria.org/hg/euphoria ~/my-euphoria-repo 
# hg output 
 
~/$ cd my-euphoria-repo 
~/my-euphoria-repo/$ hg pull 
# hg output 
 
~/my-euphoria-repo/$ hg update 
# hg output 
 
~/my-euphoria-repo/$ cd 
~/$ hg clone -b 4.0 my-euphoria-repo my-euphoria-working 
# hg output 
 
~/$ cd my-euphoria-working 
# Do some stuff -- editing, adding, testing, etc. 
 
~/my-euphoria-working/$ hg commit -m "Fixes ticket:xyz and some other meaningful information." 
# hg output 
 
~/my-euphoria-working/$ cd ~/my-euphoria-repo 
~/my-euphoria-repo/$ hg incoming 
# hg output - say no changes for this example. 
 
~/my-euphoria-repo/$ cd ~/my-euphoria-working 
~/my-euphoria-working/$ hg incoming -b 4.0 
# hg output - say no changes for this example. 
 
~/my-euphoria-working/$ hg push 
~/my-euphoria-working/$ cd ~/my-euphoria-repo 
~/my-euphoria-repo/$ hg outgoing 
# hg output showing your changes 
 
~/my-euphoria-repo/$ hg push 

Final Summary

  • Clone the main repository and keep your copy up-to-date. Your "gold copy".
  • Clone your gold copy into various working directories.
  • Commit your changes in your working directories with relevant information and ticket references if applicable.
  • Verify your gold copy of the repo is up-to-date and update it as necessary.
  • Push your working directory to your gold copy. Watch for any errors or anything unexpected.
  • Push your repository copy to the main repository.

eol

euphoria hg now uses the eol, end of line plugin. enable in tortoiseHG repo settings. there are numerous ways to access to settings. better to set eol in local repo rather than as global. just click eol, nothing need be installed.

for the commandline hg you can edit Mercurial.ini adding to section

[extensions] 
eol = 

you can also edit anyrepo/.hg/hgrc for any client,

also:Eol and win32text cannot both be enabled. you may have to edit ~/.hgrc to accomplish this, see tortoisehg-crashed-eol-extension

self certificate

versions of mercurial earlier than 1.8.2 are more strict about servers with self signed (cheaper) certificates as openeuphoria.org uses when accessing via https. a good write up on how to work around the problem is here

~TortoiseHG from version 2 on has several options to simplify this process.

Note: this is mostly a problem for developers that will be pushing back updates to the repo or using https to clone.

Search



Quick Links

User menu

Not signed in.

Misc Menu