view mercurial/tagmerge.py @ 31765:264baeef3588

show: new extension for displaying various repository data

Currently, Mercurial has a number of commands to show information. And,
there are features coming down the pipe that will introduce more
commands for showing information.

Currently, when introducing a new class of data or a view that we
wish to expose to the user, the strategy is to introduce a new command
or overload an existing command, sometimes both. For example, there is
a desire to formalize the wip/smartlog/underway/mine functionality that
many have devised. There is also a desire to introduce a "topics"
concept. Others would like views of "the current stack." In the
current model, we'd need a new command for wip/smartlog/etc (that
behaves a lot like a pre-defined alias of `hg log`). For topics,
we'd likely overload `hg topic[s]` to both display and manipulate
topics.

Adding new commands for every pre-defined query doesn't scale well
and pollutes `hg help`. Overloading commands to perform read-only and
write operations is arguably an UX anti-pattern: while having all
functionality for a given concept in one command is nice, having a
single command doing multiple discrete operations is not. Furthermore,
a user may be surprised that a command they thought was read-only
actually changes something.

We discussed this at the Mercurial 4.0 Sprint in Paris and decided that
having a single command where we could hang pre-defined views of
various data would be a good idea. Having such a command would:

* Help prevent an explosion of new query-related commands
* Create a clear separation between read and write operations
  (mitigates footguns)
* Avoids overloading the meaning of commands that manipulate data
  (bookmark, tag, branch, etc) (while we can't take away the
  existing behavior for BC reasons, we now won't introduce this
  behavior on new commands)
* Allows users to discover informational views more easily by
  aggregating them in a single location
* Lowers the barrier to creating the new views (since the barrier
  to creating a top-level command is relatively high)

So, this commit introduces the `hg show` command via the "show"
extension. This command accepts a positional argument of the
"view" to show. New views can be registered with a decorator. To
prove it works, we implement the "bookmarks" view, which shows a
table of bookmarks and their associated nodes.

We introduce a new style to hold everything used by `hg show`.

For our initial bookmarks view, the output varies from `hg bookmarks`:

* Padding is performed in the template itself as opposed to Python
* Revision integers are not shown
* shortest() is used to display a 5 character node by default (as
  opposed to static 12 characters)

I chose to implement the "bookmarks" view first because it is simple
and shouldn't invite too much bikeshedding that detracts from the
evaluation of `hg show` itself. But there is an important point
to consider: we now have 2 ways to show a list of bookmarks. I'm not
a fan of introducing multiple ways to do very similar things. So it
might be worth discussing how we wish to tackle this issue for
bookmarks, tags, branches, MQ series, etc.

I also made the choice of explicitly declaring the default show
template not part of the standard BC guarantees. History has shown
that we make mistakes and poor choices with output formatting but
can't fix these mistakes later because random tools are parsing
output and we don't want to break these tools. Optimizing for human
consumption is one of my goals for `hg show`. So, by not covering
the formatting as part of BC, the barrier to future change is much
lower and humans benefit.

There are some improvements that can be made to formatting. For
example, we don't yet use label() in the templates. We obviously
want this for color. But I'm not sure if we should reuse the existing
log.* labels or invent new ones. I figure we can punt that to a
follow-up.

At the aforementioned Sprint, we discussed and discarded various
alternatives to `hg show`.

We considered making `hg log <view>` perform this behavior. The main
reason we can't do this is because a positional argument to `hg log`
can be a file path and if there is a conflict between a path name and
a view name, behavior is ambiguous. We could have introduced
`hg log --view` or similar, but we felt that required too much typing
(we don't want to require a command flag to show a view) and wasn't
very discoverable. Furthermore, `hg log` is optimized for showing
changelog data and there are things that `hg display` could display
that aren't changelog centric.

There were concerns about using "show" as the command name.

Some users already have a "show" alias that is similar to `hg export`.

There were also concerns that Git users adapted to `git show` would
be confused by `hg show`'s different behavior. The main difference
here is `git show` prints an `hg export` like view of the current
commit by default and `hg show` requires an argument. `git show`
can also display any Git object. `git show` does not support
displaying more complex views: just single objects. If we
implemented `hg show <hash>` or `hg show <identifier>`, `hg show`
would be a superset of `git show`. Although, I'm hesitant to do that
at this time because I view `hg show` as a higher-level querying
command and there are namespace collisions between valid identifiers
and registered views.

There is also a prefix collision with `hg showconfig`, which is an
alias of `hg config`.

We also considered `hg view`, but that is already used by the "hgk"
extension.

`hg display` was also proposed at one point. It has a prefix collision
with `hg diff`. General consensus was "show" or "view" are the best
verbs. And since "view" was taken, "show" was chosen.

There are a number of inline TODOs in this patch. Some of these
represent decisions yet to be made. Others represent features
requiring non-trivial complexity. Rather than bloat the patch or
invite additional bikeshedding, I figured I'd document future
enhancements via TODO so we can get a minimal implmentation landed.
Something is better than nothing.

# tagmerge.py - merge .hgtags files
#
# Copyright 2014 Angel Ezquerra <[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.

# This module implements an automatic merge algorithm for mercurial's tag files
#
# The tagmerge algorithm implemented in this module is able to resolve most
# merge conflicts that currently would trigger a .hgtags merge conflict. The
# only case that it does not (and cannot) handle is that in which two tags point
# to different revisions on each merge parent _and_ their corresponding tag
# histories have the same rank (i.e. the same length). In all other cases the
# merge algorithm will choose the revision belonging to the parent with the
# highest ranked tag history. The merged tag history is the combination of both
# tag histories (special care is taken to try to combine common tag histories
# where possible).
#
# In addition to actually merging the tags from two parents, taking into
# account the base, the algorithm also tries to minimize the difference
# between the merged tag file and the first parent's tag file (i.e. it tries to
# make the merged tag order as as similar as possible to the first parent's tag
# file order).
#
# The algorithm works as follows:
# 1. read the tags from p1, p2 and the base
#     - when reading the p1 tags, also get the line numbers associated to each
#       tag node (these will be used to sort the merged tags in a way that
#       minimizes the diff to p1). Ignore the file numbers when reading p2 and
#       the base
# 2. recover the "lost tags" (i.e. those that are found in the base but not on
#    p1 or p2) and add them back to p1 and/or p2
#     - at this point the only tags that are on p1 but not on p2 are those new
#       tags that were introduced in p1. Same thing for the tags that are on p2
#       but not on p2
# 3. take all tags that are only on p1 or only on p2 (but not on the base)
#     - Note that these are the tags that were introduced between base and p1
#       and between base and p2, possibly on separate clones
# 4. for each tag found both on p1 and p2 perform the following merge algorithm:
#     - the tags conflict if their tag "histories" have the same "rank" (i.e.
#       length) AND the last (current) tag is NOT the same
#     - for non conflicting tags:
#         - choose which are the high and the low ranking nodes
#             - the high ranking list of nodes is the one that is longer.
#               In case of draw favor p1
#             - the merged node list is made of 3 parts:
#                 - first the nodes that are common to the beginning of both
#                   the low and the high ranking nodes
#                 - second the non common low ranking nodes
#                 - finally the non common high ranking nodes (with the last
#                   one being the merged tag node)
#             - note that this is equivalent to putting the whole low ranking
#               node list first, followed by the non common high ranking nodes
#     - note that during the merge we keep the "node line numbers", which will
#       be used when writing the merged tags to the tag file
# 5. write the merged tags taking into account to their positions in the first
#    parent (i.e. try to keep the relative ordering of the nodes that come
#    from p1). This minimizes the diff between the merged and the p1 tag files
#    This is done by using the following algorithm
#     - group the nodes for a given tag that must be written next to each other
#         - A: nodes that come from consecutive lines on p1
#         - B: nodes that come from p2 (i.e. whose associated line number is
#              None) and are next to one of the a nodes in A
#         - each group is associated with a line number coming from p1
#     - generate a "tag block" for each of the groups
#         - a tag block is a set of consecutive "node tag" lines belonging to
#           the same tag and which will be written next to each other on the
#           merged tags file
#     - sort the "tag blocks" according to their associated number line
#         - put blocks whose nodes come all from p2 first
#     - write the tag blocks in the sorted order

from __future__ import absolute_import

import operator

from .i18n import _
from .node import (
    hex,
    nullid,
)
from .import (
    tags as tagsmod,
    util,
)

hexnullid = hex(nullid)

def readtagsformerge(ui, repo, lines, fn='', keeplinenums=False):
    '''read the .hgtags file into a structure that is suitable for merging

    Depending on the keeplinenums flag, clear the line numbers associated
    with each tag. This is done because only the line numbers of the first
    parent are useful for merging.
    '''
    filetags = tagsmod._readtaghist(ui, repo, lines, fn=fn, recode=None,
                                    calcnodelines=True)[1]
    for tagname, taginfo in filetags.items():
        if not keeplinenums:
            for el in taginfo:
                el[1] = None
    return filetags

def grouptagnodesbyline(tagnodes):
    '''
    Group nearby nodes (i.e. those that must be written next to each other)

    The input is a list of [node, position] pairs, corresponding to a given tag
    The position is the line number where the node was found on the first parent
    .hgtags file, or None for those nodes that came from the base or the second
    parent .hgtags files.

    This function groups those [node, position] pairs, returning a list of
    groups of nodes that must be written next to each other because their
    positions are consecutive or have no position preference (because their
    position is None).

    The result is a list of [position, [consecutive node list]]
    '''
    firstlinenum = None
    for hexnode, linenum in tagnodes:
        firstlinenum = linenum
        if firstlinenum is not None:
            break
    if firstlinenum is None:
        return [[None, [el[0] for el in tagnodes]]]
    tagnodes[0][1] = firstlinenum
    groupednodes = [[firstlinenum, []]]
    prevlinenum = firstlinenum
    for hexnode, linenum in tagnodes:
        if linenum is not None and linenum - prevlinenum > 1:
            groupednodes.append([linenum, []])
        groupednodes[-1][1].append(hexnode)
        if linenum is not None:
            prevlinenum = linenum
    return groupednodes

def writemergedtags(repo, mergedtags):
    '''
    write the merged tags while trying to minimize the diff to the first parent

    This function uses the ordering info stored on the merged tags dict to
    generate an .hgtags file which is correct (in the sense that its contents
    correspond to the result of the tag merge) while also being as close as
    possible to the first parent's .hgtags file.
    '''
    # group the node-tag pairs that must be written next to each other
    for tname, taglist in mergedtags.items():
        mergedtags[tname] = grouptagnodesbyline(taglist)

    # convert the grouped merged tags dict into a format that resembles the
    # final .hgtags file (i.e. a list of blocks of 'node tag' pairs)
    def taglist2string(tlist, tname):
        return '\n'.join(['%s %s' % (hexnode, tname) for hexnode in tlist])

    finaltags = []
    for tname, tags in mergedtags.items():
        for block in tags:
            block[1] = taglist2string(block[1], tname)
        finaltags += tags

    # the tag groups are linked to a "position" that can be used to sort them
    # before writing them
    # the position is calculated to ensure that the diff of the merged .hgtags
    # file to the first parent's .hgtags file is as small as possible
    finaltags.sort(key=operator.itemgetter(0))

    # finally we can join the sorted groups to get the final contents of the
    # merged .hgtags file, and then write it to disk
    mergedtagstring = '\n'.join([tags for rank, tags in finaltags if tags])
    fp = repo.wvfs('.hgtags', 'wb')
    fp.write(mergedtagstring + '\n')
    fp.close()

def singletagmerge(p1nodes, p2nodes):
    '''
    merge the nodes corresponding to a single tag

    Note that the inputs are lists of node-linenum pairs (i.e. not just lists
    of nodes)
    '''
    if not p2nodes:
        return p1nodes
    if not p1nodes:
        return p2nodes

    # there is no conflict unless both tags point to different revisions
    # and have a non identical tag history
    p1currentnode = p1nodes[-1][0]
    p2currentnode = p2nodes[-1][0]
    if p1currentnode != p2currentnode and len(p1nodes) == len(p2nodes):
        # cannot merge two tags with same rank pointing to different nodes
        return None

    # which are the highest ranking (hr) / lowest ranking (lr) nodes?
    if len(p1nodes) >= len(p2nodes):
        hrnodes, lrnodes = p1nodes, p2nodes
    else:
        hrnodes, lrnodes = p2nodes, p1nodes

    # the lowest ranking nodes will be written first, followed by the highest
    # ranking nodes
    # to avoid unwanted tag rank explosion we try to see if there are some
    # common nodes that can be written only once
    commonidx = len(lrnodes)
    for n in range(len(lrnodes)):
        if hrnodes[n][0] != lrnodes[n][0]:
            commonidx = n
            break
        lrnodes[n][1] = p1nodes[n][1]

    # the merged node list has 3 parts:
    # - common nodes
    # - non common lowest ranking nodes
    # - non common highest ranking nodes
    # note that the common nodes plus the non common lowest ranking nodes is the
    # whole list of lr nodes
    return lrnodes + hrnodes[commonidx:]

def merge(repo, fcd, fco, fca):
    '''
    Merge the tags of two revisions, taking into account the base tags
    Try to minimize the diff between the merged tags and the first parent tags
    '''
    ui = repo.ui
    # read the p1, p2 and base tags
    # only keep the line numbers for the p1 tags
    p1tags = readtagsformerge(
        ui, repo, fcd.data().splitlines(), fn="p1 tags",
        keeplinenums=True)
    p2tags = readtagsformerge(
        ui, repo, fco.data().splitlines(), fn="p2 tags",
        keeplinenums=False)
    basetags = readtagsformerge(
        ui, repo, fca.data().splitlines(), fn="base tags",
        keeplinenums=False)

    # recover the list of "lost tags" (i.e. those that were found on the base
    # revision but not on one of the revisions being merged)
    basetagset = set(basetags)
    for n, pntags in enumerate((p1tags, p2tags)):
        pntagset = set(pntags)
        pnlosttagset = basetagset - pntagset
        for t in pnlosttagset:
            pntags[t] = basetags[t]
            if pntags[t][-1][0] != hexnullid:
                pntags[t].append([hexnullid, None])

    conflictedtags = []  # for reporting purposes
    mergedtags = util.sortdict(p1tags)
    # sortdict does not implement iteritems()
    for tname, p2nodes in p2tags.items():
        if tname not in mergedtags:
            mergedtags[tname] = p2nodes
            continue
        p1nodes = mergedtags[tname]
        mergednodes = singletagmerge(p1nodes, p2nodes)
        if mergednodes is None:
            conflictedtags.append(tname)
            continue
        mergedtags[tname] = mergednodes

    if conflictedtags:
        numconflicts = len(conflictedtags)
        ui.warn(_('automatic .hgtags merge failed\n'
            'the following %d tags are in conflict: %s\n')
            % (numconflicts, ', '.join(sorted(conflictedtags))))
        return True, 1

    writemergedtags(repo, mergedtags)
    ui.note(_('.hgtags merged successfully\n'))
    return False, 0