mercurial/repo.py

backout: make help more explicit about what backout does

The help for backout explains:

   The backout command merges the reverse effect of the reverted
   changeset into the working directory.

Unfortunately, that does not make it obvious to a newcomer what the
backout command does.  Since it performs a 3-way merge, what is the
common ancestor?  Will the result be automatically committed?  What is
this reverted changeset --- is it the rev passed with -r on the
command line or its inverse?

So try to clarify the description, avoiding jargon and being
explicit about what happens from the user's perspective.

Thanks to Gilles Moris, Steve Borho, Kevin Bullock, and timeless for
help.

# repo.py - repository base classes for mercurial
#
# Copyright 2005, 2006 Matt Mackall <[e-mail]>
# Copyright 2006 Vadim Gelfer <[e-mail]>
#
# This software may be used and distributed according to the terms of the
# GNU General Public License version 2 or any later version.

from i18n import _
import error

class repository(object):
    def capable(self, name):
        '''tell whether repo supports named capability.
        return False if not supported.
        if boolean capability, return True.
        if string capability, return string.'''
        if name in self.capabilities:
            return True
        name_eq = name + '='
        for cap in self.capabilities:
            if cap.startswith(name_eq):
                return cap[len(name_eq):]
        return False

    def requirecap(self, name, purpose):
        '''raise an exception if the given capability is not present'''
        if not self.capable(name):
            raise error.CapabilityError(
                _('cannot %s; remote repository does not '
                  'support the %r capability') % (purpose, name))

    def local(self):
        return False

    def cancopy(self):
        return self.local()