Commits

Jason Harris  committed 46554d9

- Add read me and copyright.

  • Participants
  • Parent commits 8cd1653

Comments (0)

Files changed (2)

+HGBAN
+=====
+
+hgban is a Mercurial extension which can be used to abort any push, pull or
+bundle operation that matches a given criteria.
+
+Basically it solves the problem if someone accidentally pushes some commit to a
+central repository and then the administrator removes the offending changeset
+then sometimes people might accidentally push the removed changeset again. To
+stop this repushing of bad changesets you can ban these changesets using this
+extension.
+
+hgban was created by Jason Harris and Angel Ezquerra.
+hgban is licensed under the classic "New BSD License" (included below)
+
+
+HGBAN Overview
+==============
+
+The extension sets up a pretxnchangegroup hook, which is executed on every push,
+pull and bundle operation. The hook tries to match every new changeset in the
+changegroup that is being pushed, pulled or bundled into a repository against a
+list of "banned" revision sets.
+
+If any of the changesets in the changegroup matches any of the "banned" revision
+sets the entire changegroup is be rejected, and the push, pull or bundle
+operation is aborted.
+
+
+Setting up the list of banned revision sets
+===========================================
+
+There are two complementary ways to specify the list of banned revision sets:
+
+1. Create a file called ".hgban" at the root of the repository. Each line in
+   that file corresponds to a banned revision set. A banned revision set can be
+   specified as simple revision id or a a complex revision set query.
+
+   You can add comments to your .hgban file by beginning a line with a "#"
+   character. You can put spaces in front of or after a revision set or
+   comment and they will be ignored.
+
+   The .hgban file does not need to be committed, although in practice it usually
+   makes sense to do so.
+
+2. Set a hgban.revsets key in one of your mecurial configuration files (i.e.
+   add a "hgban" section, and in it set a "revsets" key). In order to ban more
+   than one revset using this method you must create a multi-line configuration
+   key as explained in (http://www.selenic.com/mercurial/hgrc.5.html#syntax).
+   Note that you can add comments to this key, but you cannot add empty lines
+   between revsets (see below for an example)
+
+   This is useful when you want to ban a certain revset but you do not want to
+   track the fact that you ban that revset in your repository history.
+
+(Note either or both methods can be used to ban changesets.)
+
+
+Enabling the extension
+======================
+
+You can enable the hgban extension just like any other Mercurial extension by
+adding the following to your hgrc:
+
+[extensions]
+hgban = /path/to/hgban.py
+
+
+Configuration Examples
+======================
+
+Using this extension you could for example ban the revision id with the
+following hash:
+
+ce3b00de97cf04655227554a13be8b077d5a3d2f
+
+by creating a file called ".hgban" at the root of your repo with the following
+contents:
+
+ce3b00de97cf04655227554a13be8b077d5a3d2f
+
+You could _also_ ban any revisions commited by "John Doe" by adding an
+additional line to the .hgban file:
+
+ce3b00de97cf04655227554a13be8b077d5a3d2f
+author("John Doe")
+
+Note that you could also add comments as follows:
+
+# Ban changeset that adds nuclear launch keys
+ce3b00de97cf04655227554a13be8b077d5a3d2f
+
+# Do not allow John Doe to push any of his changes
+author("John Doe")
+
+Alternativelly, instead of using the .hgban file you could set the hgban.revsets
+configuration key as follows:
+
+[hgban]
+revsets = # Ban changeset that adds nuclear launch keys
+          ce3b00de97cf04655227554a13be8b077d5a3d2f
+          # Do not allow John Doe to push any of its changes
+          author("John Doe")
+
+Note that each line on the revsets key (except the first one) _must_ be
+indented, and that while you can add comments you cannot add empty lines.
+
+You could have combined the use of the .hgban file and of the hgban.revsets key
+to achieved the same result:
+
+[hgban]
+revsets = # Ban changeset that adds nuclear launch keys
+          ce3b00de97cf04655227554a13be8b077d5a3d2f
+
+".hgban" file:
+
+# Do not allow John Doe to push any of its changes
+author("John Doe")
+
+
+Full License
+============
+
+hgban extension for Mercurial
+Copyright (c) 2012, Jason Harris and Angel Ezquerra
+All rights reserved.
+   
+Redistribution and use in source and binary forms, with or without modification,
+are permitted provided that the following conditions are met:
+* Redistributions of source code must retain the above copyright notice, this
+  list of conditions and the following disclaimer.
+* Redistributions in binary form must reproduce the above copyright notice, this
+  list of conditions and the following disclaimer in the documentation and/or
+  other materials provided with the distribution.
+* Neither the name of Jason Harris nor the names of its contributors may be used
+  to endorse or promote products derived from this software without specific
+  prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 'AS IS' AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
+ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
+ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 #!/usr/bin/env python
+# hgban by Jason Harris and Angel Ezquerra
+# Copyright (c) 2012, Jason Harris and Angel Ezquerra
+# hgban is licensed under the standard 3 caluse BSD license.
 
 '''hgban is a Mercurial extension which can be used to abort any push, pull or
 bundle operation that matches a given criteria.