Make sure to create a ~/.hgrc file like this
username = William Stein <firstname.lastname@example.org>
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 http://sage.math.washington.edu/sage/hg/sage-main
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.
QUICK MERCURIAL FOR SAGE (Tutorial)
I assume you've upgraded SAGE to version 22.214.171.124.
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
1. LAYOUT CHANGE:
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;
2. HOW TO CLONE:
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
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.
3. SWITCHING BRANCHES:
To switch to a different repository and build it, type, e.g.,
sage -b newver
if the repository is stored in
4. HG COMMAND:
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.
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
patches, so it's not so bad.
(6) Pull your changes back into your main repository:
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 http://sage.math.washington.edu/sage/hg/sage-main
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
above to send only from your own sage-main repository.
Note also that if you have a repository, e.g.,
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
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).