# HG changeset patch
# User Oben Sonne <obensonne@googlemail.com>
# Date 1573216359 -3600
#      Fri Nov 08 13:32:39 2019 +0100
# Node ID 901a5b715f6297e14ea965f2628ea7ae61bac885
# Parent  4307700f5909988e943891b051e8e5105f3f4ba0
Migrate BitBucket Wiki to repo README

diff --git a/README.md b/README.md
new file mode 100644
--- /dev/null
+++ b/README.md
@@ -0,0 +1,104 @@
+Mercurial compass extension
+---------------------------
+
+**This extension is unmaintained and does not work with recent Mercurial
+versions!**
+
+The compass extensions helps to find your way in repositories with
+multiple heads, branches and bookmarks. It show where you are, where you
+could be and where you go on update or commit.
+
+*Requires Mercurial ≥ 1.8*
+
+#### Sample output
+
+    $ cd crazy/repository
+    $ hg compass
+    #=============================================================================#
+    #                              You are at a head                              #
+    #=============================================================================#
+    Rev      5 dev-1.1                                          @b-tip [ 1 minutes]
+    #-----------------------------------------------------------------------------#
+    #                                 Other heads                                 #
+    #-----------------------------------------------------------------------------#
+    Rev     16 dev-1.0                                      tip @b-tip [58 seconds]
+    Rev     13 dev-1.2                                  @closed @b-tip [ 1 minutes]
+    Rev     11 dev-2.0                                  @closed @b-tip [ 1 minutes]
+    Rev      7 dev-1.0                                           @anon [ 1 minutes]
+    #-----------------------------------------------------------------------------#
+    #                            Inactive branch heads                            #
+    #-----------------------------------------------------------------------------#
+    Rev      0 default                                          @b-tip [ 1 minutes]
+    Rev     15 feature-foo                              @closed @b-tip [59 seconds]
+    #-----------------------------------------------------------------------------#
+    #                              Inactive bookmarks                             #
+    #-----------------------------------------------------------------------------#
+    Rev      4 dev-1.1 (feature-1.1a)                                  [ 1 minutes]
+    #-----------------------------------------------------------------------------#
+    #                               Branch overview                               #
+    #-----------------------------------------------------------------------------#
+    default                            1 heads (0 active, 1 inactive, 0 bookmarked)
+    dev-2.0 (closed)                   1 heads (1 active, 0 inactive, 0 bookmarked)
+    feature-foo (closed)               1 heads (0 active, 1 inactive, 0 bookmarked)
+    dev-1.2 (closed)                   1 heads (1 active, 0 inactive, 0 bookmarked)
+    dev-1.0                            2 heads (2 active, 0 inactive, 0 bookmarked)
+    dev-1.1*                           1 heads (1 active, 0 inactive, 0 bookmarked)
+
+You probably won't need *hg-compass* in straightforward repositories:
+
+    $ cd boring/repository
+    $ hg compass
+    #=============================================================================#
+    #                              You are at a head                              #
+    #=============================================================================#
+    Rev     47 default                                      tip @b-tip [17 minutes]
+    #-----------------------------------------------------------------------------#
+    #                               Branch overview                               #
+    #-----------------------------------------------------------------------------#
+    default*                           1 heads (1 active, 0 inactive, 0 bookmarked)
+
+#### Output explained
+
+The example above shows the parent revision of your working directory
+and a list of *revisions of interest* grouped by type (heads, inactive
+heads and inactive bookmarks). For each listed revision, it shows the
+following information:
+
+  Revision   Branch    Bookmarks   Tags   Labels   Revision age
+  ---------- --------- ----------- ------ -------- ----------------
+  Rev 16     dev-1.0   (foomark)   tip    @b-tip   \[58 seconds\]
+
+Labels are generated dynamically, start with *@* and may be one of
+these:
+
+  Label      Description
+  ---------- ---------------------------------------------------------------------------------------------------
+  *above*    revision is a head revision above your current revision
+  *anon*     revision is anonymous, i.e. the only way to update to is specifying its revision number
+  *b-tip*    revision is tip of its branch, i.e. you'll get to this revision when updating to its branch name
+  *closed*   revision is part of a closed branch
+
+Finally *compass* prints out an overview about all existing branches and
+prints a warning if a commit will create a new head.
+
+#### Installation
+
+Download or clone *hg-compass* to some place, then enable the extension
+in your *hgrc* file:
+
+    ...
+    [extensions]
+    compass = path/to/compass.py
+    ...
+
+#### Usage
+
+There is not much to it, just run *hg compass* within a repository.
+
+Run *hg help compass* for a few options.
+
+#### Feedback
+
+I'm sure *hg-compass* has some bugs and there is space for improvements
+(e.g. make it work with Mercurial \< 1.3). Feel free to report issues or
+suggest enhancements.