7.1 Quick Mercurial Tutorial for Sage

There are several ways to run Mercurial: from the command line, run sage -hg (Hg is the chemical symbol for mercury), or from within Sage, run hg_sage. Most of the examples below use the second method.

Before you modify Sage library files, you might want to create a copy of the Sage library in which to work. Do this by typing sage -clone myver, for example; then Sage will use Mercurial to clone the current repository and call the result myver. The new repository is stored in <SAGE_ROOT>/devel/sage-myver, and when you clone, the symlink sage --> sage-myver is made.

(You can also do, e.g., sage -clone -r 1250 oldver, to get a clone of Sage but as it was at revision 1250. Of course, dependency issues could make old versions not work (e.g., maybe an old Sage library won't compile with the latest Singular library, which is what is installed elsewhere in SAGE_ROOT). From with Sage, type hg_sage.log() to see the revision history. Note: If you clone an old version, all of the Cython code is rebuilt, since there is no easy way to know which files do and don't need rebuilding.)

Once you've copied the library to a new branch myver and edited some files there, you should build the Sage library to incorporate those changes: type sage -b myver, or just sage -b if the branch myver is already the current branch: that is, if <SAGE_ROOT>/devel/sage links to <SAGE_ROOT>/devel/sage-myver. You can also type sage -br myver to build the library and then to immediately run Sage.

If you want to submit your changes to the Sage development team for refereeing (and inclusion into Sage if the referee's report is positive), you should produce patch files. To do this:

Type hg_sage.status() and hg_sage.diff() to see exactly what you've done (you can pass options to diff to see information about certain files).
If you've added new files, not just edited existing ones, type hg_sage.add([filenames]) to add those new files to your repository.
Commit your changes by typing hg_sage.commit([optional filenames]) to commit the changes in files to the repository -- if no filenames are given, all files are committed. First the output of hg diff is displayed: look at it or just enter q. Then you are dumped into an editor to type a brief comment on the changes. The default editor is vi, so type i, write some meaningful one line description, hit Escape and type :wq. (In bash, to make emacs the default editor, type export EDITOR=emacs.)
Now create a patch file using hg_sage.export(...). This command needs a revision number (or list of revision numbers) as an argument; use hg_sage.log() to see these numbers. An optional second argument to hg_sage.export(...) is a filename for the patch; the default is (changeset_revision_number).patch.
Then post your patch on the Sage trac server: see Chapter 9.

Note that you can also start a very nice web server that allows you to navigate your repository with a web browser, or pull patches from it remotely, by typing hg_sage.serve(). Then open your webbrowser and point it to http://localhost:8000 which is the default listening address for Mecurial.

Finally, if you want to apply a patch file (perhaps you've downloaded a patch from the trac server for review), use the command hg_sage.patch('filename').

See About this document... for information on suggesting changes.