[stgit] / stgit / lib / log.py

r"""This module contains functions and classes for manipulating
I{patch stack logs} (or just I{stack logs}).

A stack log is a git branch. Each commit contains the complete state
of the stack at the moment it was written; the most recent commit has
the most recent state.

For a branch C{I{foo}}, the stack log is stored in C{I{foo}.stgit}.
Each log entry makes sure to have proper references to everything it
needs, which means that it is safe against garbage collection -- you
can even pull it from one repository to another.

Stack log format (version 0)
============================

Version 0 was an experimental version of the stack log format; it is
no longer supported.

Stack log format (version 1)
============================

Commit message
--------------

The commit message is mostly for human consumption; in most cases it
is just a subject line: the stg subcommand name and possibly some
important command-line flag.

An exception to this is log commits for undo and redo. Their subject
line is "C{undo I{n}}" and "C{redo I{n}}"; the positive integer I{n}
says how many steps were undone or redone.

Tree
----

  - One blob, C{meta}, that contains the log data:

      - C{Version:} I{n}

        where I{n} must be 1. (Future versions of StGit might change
        the log format; when this is done, this version number will be
        incremented.)

      - C{Previous:} I{sha1 or C{None}}

        The commit of the previous log entry, or C{None} if this is
        the first entry.

      - C{Head:} I{sha1}

        The current branch head.

      - C{Applied:}

        Marks the start of the list of applied patches. They are
        listed in order, each on its own line: first one or more
        spaces, then the patch name, then a colon, space, then the
        patch's sha1.

      - C{Unapplied:}

        Same as C{Applied:}, but for the unapplied patches.

      - C{Hidden:}

        Same as C{Applied:}, but for the hidden patches.

  - One subtree, C{patches}, that contains one blob per patch::

      Bottom: <sha1 of patch's bottom tree>
      Top:    <sha1 of patch's top tree>
      Author: <author name and e-mail>
      Date:   <patch timestamp>

      <commit message>

      ---

      <patch diff>

Following the message is a newline, three dashes, and another newline.
Then come, each on its own line,

Parents
-------

  - The first parent is the I{simplified log}, described below.

  - The rest of the parents are just there to make sure that all the
    commits referred to in the log entry -- patches, branch head,
    previous log entry -- are ancestors of the log commit. (This is
    necessary to make the log safe with regard to garbage collection
    and pulling.)

Simplified log
--------------

The simplified log is exactly like the full log, except that its only
parent is the (simplified) previous log entry, if any. It's purpose is
mainly ease of visualization."""

from stgit.lib import git, stack as libstack
from stgit import exception, utils
from stgit.out import out
import StringIO

class LogException(exception.StgException):
    pass

class LogParseException(LogException):
    pass

def patch_file(repo, cd):
    return repo.commit(git.BlobData(''.join(s + '\n' for s in [
                    'Bottom: %s' % cd.parent.data.tree.sha1,
                    'Top:    %s' % cd.tree.sha1,
                    'Author: %s' % cd.author.name_email,
                    'Date:   %s' % cd.author.date,
                    '',
                    cd.message,
                    '',
                    '---',
                    '',
                    repo.diff_tree(cd.parent.data.tree, cd.tree, ['-M']
                                   ).strip()])))

def log_ref(branch):
    return 'refs/heads/%s.stgit' % branch

class LogEntry(object):
    __separator = '\n---\n'
    __max_parents = 16
    def __init__(self, repo, prev, head, applied, unapplied, hidden,
                 patches, message):
        self.__repo = repo
        self.__prev = prev
        self.__simplified = None
        self.head = head
        self.applied = applied
        self.unapplied = unapplied
        self.hidden = hidden
        self.patches = patches
        self.message = message
    @property
    def simplified(self):
        if not self.__simplified:
            self.__simplified = self.commit.data.parents[0]
        return self.__simplified
    @property
    def prev(self):
        if self.__prev != None and not isinstance(self.__prev, LogEntry):
            self.__prev = self.from_commit(self.__repo, self.__prev)
        return self.__prev
    @property
    def base(self):
        if self.applied:
            return self.patches[self.applied[0]].data.parent
        else:
            return self.head
    @classmethod
    def from_stack(cls, prev, stack, message):
        return cls(
            repo = stack.repository,
            prev = prev,
            head = stack.head,
            applied = list(stack.patchorder.applied),
            unapplied = list(stack.patchorder.unapplied),
            hidden = list(stack.patchorder.hidden),
            patches = dict((pn, stack.patches.get(pn).commit)
                           for pn in stack.patchorder.all),
            message = message)
    @staticmethod
    def __parse_metadata(repo, metadata):
        """Parse a stack log metadata string."""
        if not metadata.startswith('Version:'):
            raise LogParseException('Malformed log metadata')
        metadata = metadata.splitlines()
        version_str = utils.strip_prefix('Version:', metadata.pop(0)).strip()
        try:
            version = int(version_str)
        except ValueError:
            raise LogParseException(
                'Malformed version number: %r' % version_str)
        if version < 1:
            raise LogException('Log is version %d, which is too old' % version)
        if version > 1:
            raise LogException('Log is version %d, which is too new' % version)
        parsed = {}
        for line in metadata:
            if line.startswith(' '):
                parsed[key].append(line.strip())
            else:
                key, val = [x.strip() for x in line.split(':', 1)]
                if val:
                    parsed[key] = val
                else:
                    parsed[key] = []
        prev = parsed['Previous']
        if prev == 'None':
            prev = None
        else:
            prev = repo.get_commit(prev)
        head = repo.get_commit(parsed['Head'])
        lists = { 'Applied': [], 'Unapplied': [], 'Hidden': [] }
        patches = {}
        for lst in lists.keys():
            for entry in parsed[lst]:
                pn, sha1 = [x.strip() for x in entry.split(':')]
                lists[lst].append(pn)
                patches[pn] = repo.get_commit(sha1)
        return (prev, head, lists['Applied'], lists['Unapplied'],
                lists['Hidden'], patches)
    @classmethod
    def from_commit(cls, repo, commit):
        """Parse a (full or simplified) stack log commit."""
        message = commit.data.message
        try:
            perm, meta = commit.data.tree.data.entries['meta']
        except KeyError:
            raise LogParseException('Not a stack log')
        (prev, head, applied, unapplied, hidden, patches
         ) = cls.__parse_metadata(repo, meta.data.str)
        lg = cls(repo, prev, head, applied, unapplied, hidden, patches, message)
        lg.commit = commit
        return lg
    def __metadata_string(self):
        e = StringIO.StringIO()
        e.write('Version: 1\n')
        if self.prev == None:
            e.write('Previous: None\n')
        else:
            e.write('Previous: %s\n' % self.prev.commit.sha1)
        e.write('Head: %s\n' % self.head.sha1)
        for lst, title in [(self.applied, 'Applied'),
                           (self.unapplied, 'Unapplied'),
                           (self.hidden, 'Hidden')]:
            e.write('%s:\n' % title)
            for pn in lst:
                e.write('  %s: %s\n' % (pn, self.patches[pn].sha1))
        return e.getvalue()
    def __parents(self):
        """Return the set of parents this log entry needs in order to be a
        descendant of all the commits it refers to."""
        xp = set([self.head]) | set(self.patches[pn]
                                    for pn in self.unapplied + self.hidden)
        if self.applied:
            xp.add(self.patches[self.applied[-1]])
        if self.prev != None:
            xp.add(self.prev.commit)
            xp -= set(self.prev.patches.values())
        return xp
    def __tree(self, metadata):
        if self.prev == None:
            def pf(c):
                return patch_file(self.__repo, c.data)
        else:
            prev_top_tree = self.prev.commit.data.tree
            perm, prev_patch_tree = prev_top_tree.data.entries['patches']
            # Map from Commit object to patch_file() results taken
            # from the previous log entry.
            c2b = dict((self.prev.patches[pn], pf) for pn, pf
                       in prev_patch_tree.data.entries.iteritems())
            def pf(c):
                r = c2b.get(c, None)
                if not r:
                    r = patch_file(self.__repo, c.data)
                return r
        patches = dict((pn, pf(c)) for pn, c in self.patches.iteritems())
        return self.__repo.commit(git.TreeData({
                    'meta': self.__repo.commit(git.BlobData(metadata)),
                    'patches': self.__repo.commit(git.TreeData(patches)) }))
    def write_commit(self):
        metadata = self.__metadata_string()
        tree = self.__tree(metadata)
        self.__simplified = self.__repo.commit(git.CommitData(
                tree = tree, message = self.message,
                parents = [prev.simplified for prev in [self.prev]
                           if prev != None]))
        parents = list(self.__parents())
        while len(parents) >= self.__max_parents:
            g = self.__repo.commit(git.CommitData(
                    tree = tree, parents = parents[-self.__max_parents:],
                    message = 'Stack log parent grouping'))
            parents[-self.__max_parents:] = [g]
        self.commit = self.__repo.commit(git.CommitData(
                tree = tree, message = self.message,
                parents = [self.simplified] + parents))

def get_log_entry(repo, ref, commit):
    try:
        return LogEntry.from_commit(repo, commit)
    except LogException, e:
        raise LogException('While reading log from %s: %s' % (ref, e))

def same_state(log1, log2):
    """Check whether two log entries describe the same current state."""
    s = [[lg.head, lg.applied, lg.unapplied, lg.hidden, lg.patches]
         for lg in [log1, log2]]
    return s[0] == s[1]

def log_entry(stack, msg):
    """Write a new log entry for the stack."""
    ref = log_ref(stack.name)
    try:
        last_log_commit = stack.repository.refs.get(ref)
    except KeyError:
        last_log_commit = None
    try:
        if last_log_commit:
            last_log = get_log_entry(stack.repository, ref, last_log_commit)
        else:
            last_log = None
        new_log = LogEntry.from_stack(last_log, stack, msg)
    except LogException, e:
        out.warn(str(e), 'No log entry written.')
        return
    if last_log and same_state(last_log, new_log):
        return
    new_log.write_commit()
    stack.repository.refs.set(ref, new_log.commit, msg)

class Fakestack(object):
    """Imitates a real L{Stack<stgit.lib.stack.Stack>}, but with the
    topmost patch popped."""
    def __init__(self, stack):
        appl = list(stack.patchorder.applied)
        unappl = list(stack.patchorder.unapplied)
        hidd = list(stack.patchorder.hidden)
        class patchorder(object):
            applied = appl[:-1]
            unapplied = [appl[-1]] + unappl
            hidden = hidd
            all = appl + unappl + hidd
        self.patchorder = patchorder
        class patches(object):
            @staticmethod
            def get(pn):
                if pn == appl[-1]:
                    class patch(object):
                        commit = stack.patches.get(pn).old_commit
                    return patch
                else:
                    return stack.patches.get(pn)
        self.patches = patches
        self.head = stack.head.data.parent
        self.top = stack.top.data.parent
        self.base = stack.base
        self.name = stack.name
        self.repository = stack.repository
def compat_log_entry(msg):
    """Write a new log entry. (Convenience function intended for use by
    code not yet converted to the new infrastructure.)"""
    repo = default_repo()
    try:
        stack = repo.get_stack(repo.current_branch_name)
    except libstack.StackException, e:
        out.warn(str(e), 'Could not write to stack log')
    else:
        if repo.default_index.conflicts() and stack.patchorder.applied:
            log_entry(Fakestack(stack), msg)
            log_entry(stack, msg + ' (CONFLICT)')
        else:
            log_entry(stack, msg)

def delete_log(repo, branch):
    ref = log_ref(branch)
    if repo.refs.exists(ref):
        repo.refs.delete(ref)

def rename_log(repo, old_branch, new_branch, msg):
    old_ref = log_ref(old_branch)
    new_ref = log_ref(new_branch)
    if repo.refs.exists(old_ref):
        repo.refs.set(new_ref, repo.refs.get(old_ref), msg)
        repo.refs.delete(old_ref)

def copy_log(repo, src_branch, dst_branch, msg):
    src_ref = log_ref(src_branch)
    dst_ref = log_ref(dst_branch)
    if repo.refs.exists(src_ref):
        repo.refs.set(dst_ref, repo.refs.get(src_ref), msg)

def default_repo():
    return libstack.Repository.default()