sage-geom / mercurial-howto.txt

Make sure to create a ~/.hgrc file like this

username = William Stein <>


It's probably easiest to just type


at the sage: prompt and go from there.  If you want to use the hg
commands directly, see the rest of this document.


QUICKSTART: How to get the latest version of the repository.

change to the direcotry <SAGE_ROOT>/devel/sage/ then type

   sage -hg pull
   sage -hg update
   sage -hg merge    # if necessary
   sage -hg commit   # if it says you need to...

to update your mercurial repository.  If you're wary of messing
things up, do
    sage -clone test  # e.g., where test can be anything.
    sage -b test

then do the above.  To switch back to your old repository, you can do
    sage -b main
You have to work with mercurial differently than with darcs.  It's
crucial to create branches -- don't do everything in one place. With
darcs that was possible, since darcs is so powerful, but with
mercurial it's not.  (Indeed, I think that's just not how mercurial is
designed to be used.)
To make working with multiple branches very easy, I added a clone
command to sage and improved how "sage -b" and "sage -br" work.
I assume you've upgraded SAGE to version
Mercurial is then available by default.   It's confusingly
called hg (the chemical symbol for mercury) at the command line.
Do "sage -hg" to run it, or make a link to SAGE_ROOT/local/bin/hg
      Now <SAGE_ROOT>/local/lib/python/site-packages/sage
      is just a symlink to
      Thus by changing what <SAGE_ROOT>/devel/sage points to,
      you can easily switch between running different versions of the
      SAGE library.  The "sage -b" command does this automatically;
      see below.
      If you type "sage -clone newver", say, then SAGE will use
      hg to clone the current repository and call the result newver.
      The new repository is stored in
      and when you clone the symlink
                   sage --> sage-newvar
      is made.  Creating clones of a repository should be fairly fast,
      e.g., about 30 seconds.  Most of the time is spent building
      some pyrexembed code (and the need for this will vanish in
      the future).
      You can also do, e.g.,
                 sage -clone -r 1250 oldvar
      to get a clone of SAGE but as it was at revision 1250.   Thus you
      can almost trivially go back in time.  Of course,
      dependency issues could make old versions not work (e.g., old
      SAGE won't compile with the latest singular library...).
      Type "sage -hg log" while in the devel/sage-* directory, to see
      the revision history.   NOTE - all the pyrex code is rebuilt
      if you clone and old version, since there's no way for me to
      easily know which files do and don't need rebuilding.
      To switch to a different repository and build it, type, e.g.,
                   sage -b newver
      if the repository is stored in
      You might want to make a symlink from
      to something in your PATH.  Then you can type "hg <stuff>"
      instead of "sage -hg <stuff>".
   5. HOW TO USE:
      Let's say you want to do a bunch of development, then make
      it available.  Here's how:
         (1) Make a new branch.
         (2) Implement your functionality there.
         (3) Type
                  sage -hg diff [optional filenames] |more
             to see exactly what you've done.
                  sage -hg status
             to see which files have changed.
         (4) Type "sage -hg add [optional filenames]" to add new
             files to your repository.
         (5) Type "sage -hg commit [optional filenames]" to commit
             the changes in files to the
             repository -- if not filenames are given all
             files are commited.
             NOTE -- here there is a huge difference from darcs!!!
             You can't just commit bits and pieces of given files to a patch
             like you can in darcs.   But you shouldn't have to since you're
             only making changes relevant to this branch you cloaned, right.
             Also, you *can* record different subsets of the files
             to different
             patches, so it's not so bad.
         (6) Pull your changes back into your main repository:
              cd <SAGE_ROOT>/devel/sage-main
              sage -hg pull ../sage-my_other_branch
              sage -hg update
         (7) Send me *all* changes in the repository you're working in
             as a bundle:
sage -hg bundle mybundle.hg
             Note that you don't get to "cherry" pick what you
             send me.   Everything
             you recorded is sent.  Hence you might want to use the
             cloning, etc.
             above to send only from your own sage-main repository.
             Note also that if you have a repository, e.g.,
             sage-mynewstuff, you
             and it's all ready to use, you can do
               sage -hg pull <SAGE_ROOT>/devel/sage-mynewstuff
             from your <SAGE_ROOT>/devel/sage-main repository, and you'll
             get all the sage-mynewstuff merged in.   NOTE: read the output!
             You must type "sage -hg update".
         (8) You can also make a server with your repository:
              sage -hg serve -p 9010   # or some other port.
             Note that this doesn't print anything out till you hit it.
             It provides a nice GUI way to browse your repository.
             Anybody can pull from it...
To emphasize -- if you try to use Mercurial as a "clone of darcs", you'll
get frustrated and confused -- Mercurial works a bit more like svn
or bizaare-ng or git than like darcs.  It is *very* different than darcs.
But, it is a fairly simple (mostly) python program, and it is often
*SHOCKINGLY* fast given what it is doing.  Also, so far it seems to me
to be extremely robust and works well even with huge data sets.  It's a
solid piece of quality software.
Finally -- if you have some darcs patches you haven't given me yet, don't
worry.  I have a SAGE's darcs --> mercurial patch conversion system setup
on my laptop, so I can convert them.  Alternatively (better), merge the
changes manually into your new mercurial repository and send me
the bundle.
Also, there's no analogue of the darcs_* Python functions yet.
By the way, you can browse the official repositories for SAGE with your
web browser here:
Another big change is that *all* the mercurial repositories related to
SAGE are included with SAGE now by default.   Thus the complete change
history and setup for doing development is there by default.  It's
not something that has to be confusingly installed later.  This is reasaonble,
partly because Mercurial is space efficient.  E.g., it adds only 5.6MB to
the entire sage library right now (darcs added 20MB).
   -- William