--- a/hgext/convert/__init__.py	Mon Jun 01 17:12:39 2009 +0200
+++ b/hgext/convert/__init__.py	Mon Jun 01 17:12:41 2009 +0200
@@ -41,6 +41,18 @@
     basename of the source with '-hg' appended. If the destination
     repository doesn't exist, it will be created.
 
+    By default, all sources except Mercurial will use
+    --branchsort. Mercurial uses --sourcesort to preserve original
+    revision numbers order. Sort modes have the following effects:
+      --branchsort: convert from parent to child revision when
+        possible, which means branches are usually converted one after
+        the other. It generates more compact repositories.
+      --datesort: sort revisions by date. Converted repositories have
+        good-looking changelogs but are often an order of magnitude
+        larger than the same ones generated by --branchsort.
+      --sourcesort: try to preserve source revisions order, only
+        supported by Mercurial sources.
+
     If <REVMAP> isn't given, it will be put in a default location
     (<dest>/.hg/shamap by default). The <REVMAP> is a simple text file
     that maps each source commit ID to the destination ID for that
@@ -247,6 +259,7 @@
           ('s', 'source-type', '', _('source repository type')),
           ('', 'splicemap', '', _('splice synthesized history into place')),
           ('', 'branchmap', '', _('change branch names while converting')),
+          ('', 'branchsort', None, _('try to sort changesets by branches')),
           ('', 'datesort', None, _('try to sort changesets by date')),
           ('', 'sourcesort', None, _('preserve source changesets order'))],
          _('hg convert [OPTION]... SOURCE [DEST [REVMAP]]')),