# histedit.py - interactive history editing for mercurial

#

# Copyright 2009 Augie Fackler <raf@durin42.com>

#

# This software may be used and distributed according to the terms of the

# GNU General Public License version 2 or any later version.

"""interactive history editing

With this extension installed, Mercurial gains one new command: histedit. Usage

is as follows, assuming the following history::

 @  3[tip]   7c2fd3b9020c   2009-04-27 18:04 -0500   durin42

 |    Add delta

 |

 o  2   030b686bedc4   2009-04-27 18:04 -0500   durin42

 |    Add gamma

 |

 o  1   c561b4e977df   2009-04-27 18:04 -0500   durin42

 |    Add beta

 |

 o  0   d8d2fcd0e319   2009-04-27 18:04 -0500   durin42

      Add alpha

If you were to run ``hg histedit c561b4e977df``, you would see the following

file open in your editor::

 pick c561b4e977df Add beta

 pick 030b686bedc4 Add gamma

 pick 7c2fd3b9020c Add delta

 # Edit history between c561b4e977df and 7c2fd3b9020c

 #

 # Commits are listed from least to most recent

 #

 # Commands:

 #  p, pick = use commit

 #  e, edit = use commit, but allow edits before making new commit

 #  f, fold = use commit, but combine it with the one above

 #  r, roll = like fold, but discard this commit's description and date

 #  d, drop = remove commit from history

 #  m, mess = edit commit message without changing commit content

 #  b, base = checkout changeset and apply further changesets from there

 #

In this file, lines beginning with ``#`` are ignored. You must specify a rule

for each revision in your history. For example, if you had meant to add gamma

before beta, and then wanted to add delta in the same revision as beta, you

would reorganize the file to look like this::

 pick 030b686bedc4 Add gamma

 pick c561b4e977df Add beta

 fold 7c2fd3b9020c Add delta

 # Edit history between c561b4e977df and 7c2fd3b9020c

 #

 # Commits are listed from least to most recent

 #

 # Commands:

 #  p, pick = use commit

 #  e, edit = use commit, but allow edits before making new commit

 #  f, fold = use commit, but combine it with the one above

 #  r, roll = like fold, but discard this commit's description and date

 #  d, drop = remove commit from history

 #  m, mess = edit commit message without changing commit content

 #  b, base = checkout changeset and apply further changesets from there

 #

At which point you close the editor and ``histedit`` starts working. When you

specify a ``fold`` operation, ``histedit`` will open an editor when it folds

those revisions together, offering you a chance to clean up the commit message::

 Add beta

 ***

 Add delta

Edit the commit message to your liking, then close the editor. The date used

for the commit will be the later of the two commits' dates. For this example,

let's assume that the commit message was changed to ``Add beta and delta.``

After histedit has run and had a chance to remove any old or temporary

revisions it needed, the history looks like this::

 @  2[tip]   989b4d060121   2009-04-27 18:04 -0500   durin42

 |    Add beta and delta.

 |

 o  1   081603921c3f   2009-04-27 18:04 -0500   durin42

 |    Add gamma

 |

 o  0   d8d2fcd0e319   2009-04-27 18:04 -0500   durin42

      Add alpha

Note that ``histedit`` does *not* remove any revisions (even its own temporary

ones) until after it has completed all the editing operations, so it will

probably perform several strip operations when it's done. For the above example,

it had to run strip twice. Strip can be slow depending on a variety of factors,

so you might need to be a little patient. You can choose to keep the original

revisions by passing the ``--keep`` flag.

The ``edit`` operation will drop you back to a command prompt,

allowing you to edit files freely, or even use ``hg record`` to commit

some changes as a separate commit. When you're done, any remaining

uncommitted changes will be committed as well. When done, run ``hg

histedit --continue`` to finish this step. If there are uncommitted

changes, you'll be prompted for a new commit message, but the default

commit message will be the original message for the ``edit`` ed

revision, and the date of the original commit will be preserved.

The ``message`` operation will give you a chance to revise a commit

message without changing the contents. It's a shortcut for doing

``edit`` immediately followed by `hg histedit --continue``.

If ``histedit`` encounters a conflict when moving a revision (while

handling ``pick`` or ``fold``), it'll stop in a similar manner to

``edit`` with the difference that it won't prompt you for a commit

message when done. If you decide at this point that you don't like how

much work it will be to rearrange history, or that you made a mistake,

you can use ``hg histedit --abort`` to abandon the new changes you

have made and return to the state before you attempted to edit your

history.

If we clone the histedit-ed example repository above and add four more

changes, such that we have the following history::

   @  6[tip]   038383181893   2009-04-27 18:04 -0500   stefan

   |    Add theta

   |

   o  5   140988835471   2009-04-27 18:04 -0500   stefan

   |    Add eta

   |

   o  4   122930637314   2009-04-27 18:04 -0500   stefan

   |    Add zeta

   |

   o  3   836302820282   2009-04-27 18:04 -0500   stefan

   |    Add epsilon

   |

   o  2   989b4d060121   2009-04-27 18:04 -0500   durin42

   |    Add beta and delta.

   |

   o  1   081603921c3f   2009-04-27 18:04 -0500   durin42

   |    Add gamma

   |

   o  0   d8d2fcd0e319   2009-04-27 18:04 -0500   durin42

        Add alpha

If you run ``hg histedit --outgoing`` on the clone then it is the same

as running ``hg histedit 836302820282``. If you need plan to push to a

repository that Mercurial does not detect to be related to the source

repo, you can add a ``--force`` option.

Config

------

Histedit rule lines are truncated to 80 characters by default. You

can customize this behavior by setting a different length in your

configuration file::

  [histedit]

  linelen = 120      # truncate rule lines at 120 characters

The summary of a change can be customized as well::

  [histedit]

  summary-template = '{rev} {bookmarks} {desc|firstline}'

The customized summary should be kept short enough that rule lines

will fit in the configured line length. See above if that requires

customization.

``hg histedit`` attempts to automatically choose an appropriate base

revision to use. To change which base revision is used, define a

revset in your configuration file::

  [histedit]

  defaultrev = only(.) & draft()

By default each edited revision needs to be present in histedit commands.

To remove revision you need to use ``drop`` operation. You can configure

the drop to be implicit for missing commits by adding::

  [histedit]

  dropmissing = True

By default, histedit will close the transaction after each action. For

performance purposes, you can configure histedit to use a single transaction

across the entire histedit. WARNING: This setting introduces a significant risk

of losing the work you've done in a histedit if the histedit aborts

unexpectedly::

  [histedit]

  singletransaction = True

"""

# chistedit dependencies that are not available everywhere

try:

    import fcntl

    import termios

except ImportError:

    fcntl = None

    termios = None

import binascii

import functools

import os

import pickle

import struct

from mercurial.i18n import _

from mercurial.pycompat import (

    getattr,

    open,

)

from mercurial.node import (

    bin,

    hex,

    short,

)

from mercurial import (

    bundle2,

    cmdutil,

    context,

    copies,

    destutil,

    discovery,

    encoding,

    error,

    exchange,

    extensions,

    hg,

    logcmdutil,

    merge as mergemod,

    mergestate as mergestatemod,

    mergeutil,

    obsolete,

    pycompat,

    registrar,

    repair,

    rewriteutil,

    scmutil,

    state as statemod,

    util,

)

from mercurial.utils import (

    dateutil,

    stringutil,

    urlutil,

)

cmdtable = {}

command = registrar.command(cmdtable)

configtable = {}

configitem = registrar.configitem(configtable)

configitem(

    b'experimental',

    b'histedit.autoverb',

    default=False,

)

configitem(

    b'histedit',

    b'defaultrev',

    default=None,

)

configitem(

    b'histedit',

    b'dropmissing',

    default=False,

)

configitem(

    b'histedit',

    b'linelen',

    default=80,

)

configitem(

    b'histedit',

    b'singletransaction',

    default=False,

)

configitem(

    b'ui',

    b'interface.histedit',

    default=None,

)

configitem(b'histedit', b'summary-template', default=b'{rev} {desc|firstline}')

# TODO: Teach the text-based histedit interface to respect this config option

# before we make it non-experimental.

configitem(

    b'histedit', b'later-commits-first', default=False, experimental=True

)

# Note for extension authors: ONLY specify testedwith = 'ships-with-hg-core' for

# extensions which SHIP WITH MERCURIAL. Non-mainline extensions should

# be specifying the version(s) of Mercurial they are tested with, or

# leave the attribute unspecified.

testedwith = b'ships-with-hg-core'

actiontable = {}

primaryactions = set()

secondaryactions = set()

tertiaryactions = set()

internalactions = set()

def geteditcomment(ui, first, last):

    """construct the editor comment

    The comment includes::

     - an intro

     - sorted primary commands

     - sorted short commands

     - sorted long commands

     - additional hints

    Commands are only included once.

    """

    intro = _(

        b"""Edit history between %s and %s

Commits are listed from least to most recent

You can reorder changesets by reordering the lines

Commands:

"""

    )

    actions = []

    def addverb(v):

        a = actiontable[v]

        lines = a.message.split(b"\n")

        if len(a.verbs):

            v = b', '.join(sorted(a.verbs, key=lambda v: len(v)))

        actions.append(b" %s = %s" % (v, lines[0]))

        actions.extend([b'  %s'] * (len(lines) - 1))

    for v in (

        sorted(primaryactions)

        + sorted(secondaryactions)

        + sorted(tertiaryactions)

    ):

        addverb(v)

    actions.append(b'')

    hints = []

    if ui.configbool(b'histedit', b'dropmissing'):

        hints.append(

            b"Deleting a changeset from the list "

            b"will DISCARD it from the edited history!"

        )

    lines = (intro % (first, last)).split(b'\n') + actions + hints

    return b''.join([b'# %s\n' % l if l else b'#\n' for l in lines])

class histeditstate:

    def __init__(self, repo):

        self.repo = repo

        self.actions = None

        self.keep = None

        self.topmost = None

        self.parentctxnode = None

        self.lock = None

        self.wlock = None

        self.backupfile = None

        self.stateobj = statemod.cmdstate(repo, b'histedit-state')

        self.replacements = []

    def read(self):

        """Load histedit state from disk and set fields appropriately."""

        if not self.stateobj.exists():

            cmdutil.wrongtooltocontinue(self.repo, _(b'histedit'))

        data = self._read()

        self.parentctxnode = data[b'parentctxnode']

        actions = parserules(data[b'rules'], self)

        self.actions = actions

        self.keep = data[b'keep']

        self.topmost = data[b'topmost']

        self.replacements = data[b'replacements']

        self.backupfile = data[b'backupfile']

    def _read(self):

        fp = self.repo.vfs.read(b'histedit-state')

        if fp.startswith(b'v1\n'):

            data = self._load()

            parentctxnode, rules, keep, topmost, replacements, backupfile = data

        else:

            data = pickle.loads(fp)

            parentctxnode, rules, keep, topmost, replacements = data

            backupfile = None

        rules = b"\n".join([b"%s %s" % (verb, rest) for [verb, rest] in rules])

        return {

            b'parentctxnode': parentctxnode,

            b"rules": rules,

            b"keep": keep,

            b"topmost": topmost,

            b"replacements": replacements,

            b"backupfile": backupfile,

        }

    def write(self, tr=None):

        if tr:

            tr.addfilegenerator(

                b'histedit-state',

                (b'histedit-state',),

                self._write,

                location=b'plain',

            )

        else:

            with self.repo.vfs(b"histedit-state", b"w") as f:

                self._write(f)

    def _write(self, fp):

        fp.write(b'v1\n')

        fp.write(b'%s\n' % hex(self.parentctxnode))

        fp.write(b'%s\n' % hex(self.topmost))