@@ 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.