XEmacs -- Emacs: The Next Generation
     Searching XEmacs
Quick Links About XEmacs Getting XEmacs Customizing XEmacs Troubleshooting XEmacs Developing XEmacs

XEmacs Mercurial Repository

Debian has upgraded Mercurial, and security tightened somewhat. How to tell Mercurial to trust a developer.

As of 5 December 2007, the development mainline (aka version 21.5) has been moved to a Mercurial repository on hg.debian.org from which you may browse the latest checked-in code. This page describes access to those resources.

Other XEmacs repositories, including the 21.4 branch, the packages, and the sources for this website, continue to be provided by the CVS repository on cvs.alioth.debian.org, hosted by our friends at Alioth.debian.org. Please see the introduction to the XEmacs CVS Repository for instructions on its use.

Please note: This page was hacked up quickly by copying and editing the corresponding page for CVS. If you spot any CVS-isms or other statements that are not correct for the new repository, please report it as a bug to the XEmacs Developers.

This site has a collection of Mercurial trees for XEmacs, a feature-packed text-editing environment based on Lisp. For general information about XEmacs, check out the XEmacs main WWW server.

Quick Start Guide

To get the official (21.5) development sources, do:

      hg clone http://hg.debian.org/hg/xemacs/xemacs-beta

To get the bleeding edge patches that are still under review (and in some cases may already have been vetoed or be known to cause crashes and other showstoppers) do:

      hg clone http://hg.debian.org/hg/xemacs/xemacs

instead. The XEmacs lisp packages are now unbundled, and are available from the CVS repository. Older versions of XEmacs, including the currently stable version (21.4) may also be checked out from CVS repository.

Each of these components are available separately as non-CVS tarballs via HTTP and FTP. Here are the current HTTP URLs:

If you prefer FTP for some reason, simply change the URL scheme from "http" to "ftp".

What is Mercurial?

Mercurial is a modern version control system (VCS) that not only keeps track of older versions also handles branching and distributed development well. Unlike CVS or Subversion (the defacto industry-standard source code control system for open source software projects), every Mercurial checkout is a full repository, containing all of the project's history. Because the archives are compressed, a full repository (back to 21.5.0) requires much less than twice the space of the source tree alone. Unlike many other VCSes (including CVS and git) Mercurial is perfectly happy to serve remote clients over an ordinary HTTP connection, using an unmodified httpd and a tiny CGI. This means that you can easily share your version-controlled patches with others, even if they are not accepted for the mainline.

Regular contributors to XEmacs are strongly encouraged to get Mercurial write access to the source repository. This distributes most of the patch-tracking work to those most qualified to do it, namely the patch authors. XEmacs source code maintenance is basically organized on the bazaar model - we'd like to have as many people as possible, including you, making high quality contributions to the source code, in parallel. But even if you are just a lurker with no desire to make any modifications to the tree, Mercurial gives you a painless way to upgrade between versions.

By current standards, these trees are moderate in size. XEmacs 21.5 sources will take up 80 MB of hard drive space, before compilation, the Mercurial metadata and archive about as much. A typical build will add about 60 MB of build products, for a total of about 220 MB required for core development. Add in the lisp packages tree (another 120 MB of source, with compiled Lisp taking about 70MB) in your calculations if you're interested in messing with them too.

Using the XEmacs Mercurial server

If you're interested in using the XEmacs Mercurial trees directly, you'll need to install Mercurial. Mercurial is highly portable because it is entirely written in Python. Binary packages are available for most platforms, either through native package distributions or from Selenic.

Unlike many centralized servers, XEmacs's Mercurial repository does not require login for cloning the repository. (Note: for modern distributed VCSes, whole repository is duplicated and can stand alone, so we use the word "clone" rather than "checkout". "Checkout" is used to describe the operation of copying files from the repository archive to the working copy, whether to revert undesirable changes in a single file, or to switch the entire working copy over to another branch.) The clone operation is simple.

First cd to the place you want to put the tree, and actually clone the repository.

chibi$ hg clone http://hg.debian.org/hg/xemacs/xemacs-beta xemacs-21.5
(churn, churn, churn)

And voila! One xemacs-21.5 directory complete with the latest versions of the base code. Packages are separate, of course.

The last argument xemacs-21.5 gives the name of the directory to use as a workspace. The repository metadata and archives go in the .hg subdirectory, and there will usually be a .hgignore file containing regexps matching names of files to ignore for version control purposes. If the tree root name (here xemacs-21.5) is omitted, it will be defaulted to the basename of the URL being cloned.

You probably want to create a ~/.hgrc file to configure your local defaults. At least it's worth setting your Mercurial username:

username = J. Random Hacker <jrhacker@example.com>

so that any local commits to your own repository look nice. (Feel free to commit what you like, it's your repository. If you expect to contribute upstream, however, you may want to keep a separate "pristine" workspace or learn about named branches.)

When there is an upstream update, you can get the whole skinny quick, fast and relatively painlessly with the following command (executed from the directory created by hg clone).

chibi$ hg pull -u

The -u switch automatically updates your workspace to correspond to the tip.

If you have local changes that you'd like to keep under version control, you can either use a separate repository or named branches. Here's one suggestion:

Message-ID: <87abmmc1lo.fsf@uwakimon.sk.tsukuba.ac.jp>
From: "Stephen J. Turnbull" <stephen@xemacs.org>
Cc: XEmacs Beta List <xemacs-beta@xemacs.org>
Subject: Converting from using CVS to hg
Date: Thu, 31 Jan 2008 08:53:07 +0900

robert writes:

 > I have 21.5.b28 from CVS which I have kept uptodate.  I also have a few 
 > changes to files in src and lisp for my own use.
 > I just got a clone of the current tree using
 >   mv xemacs xemacs-cvs
 >   hg clone http://hg.debian.org/hg/xemacs/xemacs

 > When I want to update the xemacs tree, do I
 >   cd xemacs
 >   hg pull http://hg.debian.org/hg/xemacs/xemacs

No, you should do "hg pull -u", which updates the directory from the
default "other repository".  This starts out as the repo you cloned,
and won't change unless you edit .hg/hgrc.  The update, like CVS,

 > If I am only compiling and using XEmacs--not contributing code, is
 > hg still the way I should go?

Yes.  Because hg is so much better at branching, what you probably
want to do is to keep a pristine checkout of XEmacs, and a separate
checkout of your changes.  so the initial clone would look like

cd $parent
hg clone http://hg.debian.org/hg/xemacs/xemacs
mv xemacs xemacs-upstream
hg clone xemacs-upstream
for f in $files_I_want_to_keep_from_my_version; do
 cp f xemacs/$the_right_place
cd xemacs
hg commit -m "Bring in my existing local changes."

and your update process would look like:

cd xemacs-upstream
hg pull -u                # there should never be any merge conflicts
cd ../xemacs
hg pull -u
# fix any merge conflicts here
# if there were merge conflicts, commit

Alternatively, you could use named branches.  Initial clone:

cd $parent
hg clone http://hg.debian.org/hg/xemacs/xemacs
hg branch myxemacs
for f in $files_I_want_to_keep_from_my_version; do
 cp f $the_right_place
hg commit -m "Bring in my existing local changes."

and update

cd xemacs
hg checkout default
hg pull                # no -u because you're just going to overwrite
                       # again immediately
hg checkout myxemacs
hg merge default
# fix any merge conflicts here
hg commit -m "Merge $date."

(WARNING: The above use of named branches is as yet untested by me!)

Do you have the paranoia blues?

Recent versions of Mercurial have had their security consciousness strengthened. Specifically, when another user has committed an hgrc to the repository you're pulling from, you may get a message that looks like

remote: not trusting file hg/xemacs/xemacs/.hg/hgrc from untrusted user sperber-guest, group xemacs

In theory, Mike could cause execution of arbitrary code on your box. But hey, what's to worry: you're already running Dired and EFS, aren't you? Mike could have pwnzered you long ago, right? So if you find that comforting, and you'd like to trust Mike, run his workspace hgrc file in your xemacs workspace(s), and incidentally suppress the warning, you can add

users = sperber-guest

to your ~/.hgrc on alioth.debian.org. For more information, see the Mercurial documentation.

Just how much do you want to bleed?

XEmacs developers push their commits on an asynchronous basis. The idea is to keep those actively coding on the same page by making everyone's most recent code available in a central place. There is no strong guarantee that the tip of the default Mercurial branch even compiles for anyone. This means that if you blindly do a hg pull -u, there is a good chance that what you get is not functional.

There are several ways to deal with the churn.

  • Since you have the whole repository available, you can simply revert to an earlier revision.
    chibi$ hg checkout -r 1234
    If this mechanism satisfies you, you may even want to clone and update to the completely unfiltered repository that the active developers are committing to:
    chibi$ hg clone http://hg.debian.org/hg/xemacs/xemacs xemacs-21.5
  • You can also take advantage of the review process, and use the xemacs-beta repository as described above.
  • Finally, the most conservative approach is to checkout only the official releases. These are identical to the tarballs distributed by xemacs.org, and are identified in the xemacs-beta repository by tags of the form rX-Y-Z, corresponding to the version number X.Y.Z (or X.Y-bZ). X is the major version, Y the minor version, and Z the micro version or patchlevel.

In general, tags are admissible anywhere a revision number or hash is allowed. To checkout a particular revision use the checkout command with the -r <TAG> option to. Therefore, to update to 21.5 beta 16 (but no further), you'd type:

chibi$ hg checkout -r r21-5-16

The most recent patchlevel or beta release is identified by the tag rX-Y-latest-beta.

For more info, check the Mercurial documentation:

New Package system

For those of you wishing to work with XEmacs 21, you should probably know about our new packaging system. All the details are available here, and there is also an introduction to the packages CVS repository.

Web Access

You can browse the repositories simply by accessing the repositories with any web browser.

Commit (R/W) access to the Mercurial tree

Anybody who has become reasonably well-known to the XEmacs Reviewers can get access to commit to the repository. (You can also get commit access to the Packages repository.) This has the following advantages:

  • The revision history will contain the true author of a change, which makes tracking changes easier, and gives credit where credit is due.
  • Committers are more likely to take responsibility for their changes when they are directly modifying the repository themselves.

To qualify to be a committer, you should have a history of submitting successful patches to xemacs-patches

Currently we are adding new committers using the following method (which may change):

  1. Make sure ssh (version 1 or 2) is installed on your computer.
  2. Get yourself a ssh public key. Here is some unsolicited advice on maintaining your ssh key:

    In general, you should only have ONE identity that you expose to the outside world. Create only ONE key pair: ~/.ssh/identity and ~/.ssh/identity.pub for version 1. Or for version 2, one of either ~/.ssh/id_rsa and ~/.ssh/id_rsa.pub or ~/.ssh/id_dsa and ~/.ssh/id_dsa.pub with ssh-keygen, and change the comment to something more meaningful like your email address. Your ssh public key is a lot like a business card.

    For example, I modified the comment in my version 1 public key using

    ssh-keygen -c -C 'Steve Youngs <youngs@xemacs.org>'

    SSH version 2 is slightly different. If you try the above command on a version 2 key you'll get an error saying that comments are only supported for version 1 keys. Don't believe everything you read, you can have a comment in a version 2 key. You just have to add the comment when you create the key:

    ssh-keygen -t dsa -C 'Steve Youngs <youngs@xemacs.org>'

    After you have created your keys, copy the ~/.ssh/identity or ~/.ssh/id_dsa or ~/.ssh/id_rsa file to all the machines you run ssh from.

    Also, append your public key file ~/.ssh/identity.pub to the ~/.ssh/authorized_keys file for SSH 1 or ~/.ssh/id_(dsa|rsa).pub to ~/.ssh/authorized_keys2 on all the machines you run ssh to.

    When people ask you for your public ssh key, just send them the contents of ~/.ssh/identity.pub or ~/.ssh/id_dsa.pub or ~/.ssh/id_rsa.pub.

  3. If you are not already a Debian developer, you'll need to go to Alioth (http://alioth.debian.org/) and get an account for guest developers. If you're not a Debian person, it will have "-guest" appended to it, so be prepared. (Sorry, "unwelcome-guest" is already taken, but I can think of a few others that are moderately creative. Think!)
  4. Send the Mercurial Administrator your Alioth user name and your public ssh key (i.e. the contents of ~/.ssh/identity.pub for SSH 1, or ~/.ssh/id_dsa.pub or ~/.ssh/id_rsa.pub for SSH 2). The administrator will take care of the administrivia to give you access.
  5. Add this stanza to your ~/.ssh/config file (create it if necessary):

    Host hg.debian.org
    	User		alioth-user-guest
    	ForwardX11	no
    	ForwardAgent	no

News and changes

2008-05-19 Changes by Stephen:

Change incorrect reference to CVS to Mercurial. Add link to cvsaccess.html#committers.

2008-02-01 Changes by Stephen:

Steal the contents of cvsaccess.html and modify them for Mercurial.


Conform with <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
Automatically validated by PSGML