chiark - git - mdw - stgit/blob - stgit/lib/git.py

   1 """A Python class hierarchy wrapping a git repository and its
   2 contents."""
   3
   4 import os, os.path, re
   5 from datetime import datetime, timedelta, tzinfo
   6
   7 from stgit import exception, run, utils
   8 from stgit.config import config
   9
  10 class Immutable(object):
  11     """I{Immutable} objects cannot be modified once created. Any
  12     modification methods will return a new object, leaving the
  13     original object as it was.
  14
  15     The reason for this is that we want to be able to represent git
  16     objects, which are immutable, and want to be able to create new
  17     git objects that are just slight modifications of other git
  18     objects. (Such as, for example, modifying the commit message of a
  19     commit object while leaving the rest of it intact. This involves
  20     creating a whole new commit object that's exactly like the old one
  21     except for the commit message.)
  22
  23     The L{Immutable} class doesn't actually enforce immutability --
  24     that is up to the individual immutable subclasses. It just serves
  25     as documentation."""
  26
  27 class RepositoryException(exception.StgException):
  28     """Base class for all exceptions due to failed L{Repository}
  29     operations."""
  30
  31 class BranchException(exception.StgException):
  32     """Exception raised by failed L{Branch} operations."""
  33
  34 class DateException(exception.StgException):
  35     """Exception raised when a date+time string could not be parsed."""
  36     def __init__(self, string, type):
  37         exception.StgException.__init__(
  38             self, '"%s" is not a valid %s' % (string, type))
  39
  40 class DetachedHeadException(RepositoryException):
  41     """Exception raised when HEAD is detached (that is, there is no
  42     current branch)."""
  43     def __init__(self):
  44         RepositoryException.__init__(self, 'Not on any branch')
  45
  46 class Repr(object):
  47     """Utility class that defines C{__reps__} in terms of C{__str__}."""
  48     def __repr__(self):
  49         return str(self)
  50
  51 class NoValue(object):
  52     """A handy default value that is guaranteed to be distinct from any
  53     real argument value."""
  54     pass
  55
  56 def make_defaults(defaults):
  57     def d(val, attr, default_fun = lambda: None):
  58         if val != NoValue:
  59             return val
  60         elif defaults != NoValue:
  61             return getattr(defaults, attr)
  62         else:
  63             return default_fun()
  64     return d
  65
  66 class TimeZone(tzinfo, Repr):
  67     """A simple time zone class for static offsets from UTC. (We have to
  68     define our own since Python's standard library doesn't define any
  69     time zone classes.)"""
  70     def __init__(self, tzstring):
  71         m = re.match(r'^([+-])(\d{2}):?(\d{2})$', tzstring)
  72         if not m:
  73             raise DateException(tzstring, 'time zone')
  74         sign = int(m.group(1) + '1')
  75         try:
  76             self.__offset = timedelta(hours = sign*int(m.group(2)),
  77                                       minutes = sign*int(m.group(3)))
  78         except OverflowError:
  79             raise DateException(tzstring, 'time zone')
  80         self.__name = tzstring
  81     def utcoffset(self, dt):
  82         return self.__offset
  83     def tzname(self, dt):
  84         return self.__name
  85     def dst(self, dt):
  86         return timedelta(0)
  87     def __str__(self):
  88         return self.__name
  89
  90 class Date(Immutable, Repr):
  91     """Represents a timestamp used in git commits."""
  92     def __init__(self, datestring):
  93         # Try git-formatted date.
  94         m = re.match(r'^(\d+)\s+([+-]\d\d:?\d\d)$', datestring)
  95         if m:
  96             try:
  97                 self.__time = datetime.fromtimestamp(int(m.group(1)),
  98                                                      TimeZone(m.group(2)))
  99             except ValueError:
 100                 raise DateException(datestring, 'date')
 101             return
 102
 103         # Try iso-formatted date.
 104         m = re.match(r'^(\d{4})-(\d{2})-(\d{2})\s+(\d{2}):(\d{2}):(\d{2})\s+'
 105                      + r'([+-]\d\d:?\d\d)$', datestring)
 106         if m:
 107             try:
 108                 self.__time = datetime(
 109                     *[int(m.group(i + 1)) for i in xrange(6)],
 110                     **{'tzinfo': TimeZone(m.group(7))})
 111             except ValueError:
 112                 raise DateException(datestring, 'date')
 113             return
 114
 115         raise DateException(datestring, 'date')
 116     def __str__(self):
 117         return self.isoformat()
 118     def isoformat(self):
 119         """Human-friendly ISO 8601 format."""
 120         return '%s %s' % (self.__time.replace(tzinfo = None).isoformat(' '),
 121                           self.__time.tzinfo)
 122     @classmethod
 123     def maybe(cls, datestring):
 124         """Return a new object initialized with the argument if it contains a
 125         value (otherwise, just return the argument)."""
 126         if datestring in [None, NoValue]:
 127             return datestring
 128         return cls(datestring)
 129
 130 class Person(Immutable, Repr):
 131     """Represents an author or committer in a git commit object. Contains
 132     name, email and timestamp."""
 133     def __init__(self, name = NoValue, email = NoValue,
 134                  date = NoValue, defaults = NoValue):
 135         d = make_defaults(defaults)
 136         self.__name = d(name, 'name')
 137         self.__email = d(email, 'email')
 138         self.__date = d(date, 'date')
 139         assert isinstance(self.__date, Date) or self.__date in [None, NoValue]
 140     name = property(lambda self: self.__name)
 141     email = property(lambda self: self.__email)
 142     name_email = property(lambda self: '%s <%s>' % (self.name, self.email))
 143     date = property(lambda self: self.__date)
 144     def set_name(self, name):
 145         return type(self)(name = name, defaults = self)
 146     def set_email(self, email):
 147         return type(self)(email = email, defaults = self)
 148     def set_date(self, date):
 149         return type(self)(date = date, defaults = self)
 150     def __str__(self):
 151         return '%s %s' % (self.name_email, self.date)
 152     @classmethod
 153     def parse(cls, s):
 154         m = re.match(r'^([^<]*)<([^>]*)>\s+(\d+\s+[+-]\d{4})$', s)
 155         assert m
 156         name = m.group(1).strip()
 157         email = m.group(2)
 158         date = Date(m.group(3))
 159         return cls(name, email, date)
 160     @classmethod
 161     def user(cls):
 162         if not hasattr(cls, '__user'):
 163             cls.__user = cls(name = config.get('user.name'),
 164                              email = config.get('user.email'))
 165         return cls.__user
 166     @classmethod
 167     def author(cls):
 168         if not hasattr(cls, '__author'):
 169             cls.__author = cls(
 170                 name = os.environ.get('GIT_AUTHOR_NAME', NoValue),
 171                 email = os.environ.get('GIT_AUTHOR_EMAIL', NoValue),
 172                 date = Date.maybe(os.environ.get('GIT_AUTHOR_DATE', NoValue)),
 173                 defaults = cls.user())
 174         return cls.__author
 175     @classmethod
 176     def committer(cls):
 177         if not hasattr(cls, '__committer'):
 178             cls.__committer = cls(
 179                 name = os.environ.get('GIT_COMMITTER_NAME', NoValue),
 180                 email = os.environ.get('GIT_COMMITTER_EMAIL', NoValue),
 181                 date = Date.maybe(
 182                     os.environ.get('GIT_COMMITTER_DATE', NoValue)),
 183                 defaults = cls.user())
 184         return cls.__committer
 185
 186 class GitObject(Immutable, Repr):
 187     """Base class for all git objects. One git object is represented by at
 188     most one C{GitObject}, which makes it possible to compare them
 189     using normal Python object comparison; it also ensures we don't
 190     waste more memory than necessary."""
 191
 192 class BlobData(Immutable, Repr):
 193     """Represents the data contents of a git blob object."""
 194     def __init__(self, string):
 195         self.__string = str(string)
 196     str = property(lambda self: self.__string)
 197     def commit(self, repository):
 198         """Commit the blob.
 199         @return: The committed blob
 200         @rtype: L{Blob}"""
 201         sha1 = repository.run(['git', 'hash-object', '-w', '--stdin']
 202                               ).raw_input(self.str).output_one_line()
 203         return repository.get_blob(sha1)
 204
 205 class Blob(GitObject):
 206     """Represents a git blob object. All the actual data contents of the
 207     blob object is stored in the L{data} member, which is a
 208     L{BlobData} object."""
 209     typename = 'blob'
 210     default_perm = '100644'
 211     def __init__(self, repository, sha1):
 212         self.__repository = repository
 213         self.__sha1 = sha1
 214     sha1 = property(lambda self: self.__sha1)
 215     def __str__(self):
 216         return 'Blob<%s>' % self.sha1
 217     @property
 218     def data(self):
 219         return BlobData(self.__repository.cat_object(self.sha1))
 220
 221 class ImmutableDict(dict):
 222     """A dictionary that cannot be modified once it's been created."""
 223     def error(*args, **kwargs):
 224         raise TypeError('Cannot modify immutable dict')
 225     __delitem__ = error
 226     __setitem__ = error
 227     clear = error
 228     pop = error
 229     popitem = error
 230     setdefault = error
 231     update = error
 232
 233 class TreeData(Immutable, Repr):
 234     """Represents the data contents of a git tree object."""
 235     @staticmethod
 236     def __x(po):
 237         if isinstance(po, GitObject):
 238             perm, object = po.default_perm, po
 239         else:
 240             perm, object = po
 241         return perm, object
 242     def __init__(self, entries):
 243         """Create a new L{TreeData} object from the given mapping from names
 244         (strings) to either (I{permission}, I{object}) tuples or just
 245         objects."""
 246         self.__entries = ImmutableDict((name, self.__x(po))
 247                                        for (name, po) in entries.iteritems())
 248     entries = property(lambda self: self.__entries)
 249     """Map from name to (I{permission}, I{object}) tuple."""
 250     def set_entry(self, name, po):
 251         """Create a new L{TreeData} object identical to this one, except that
 252         it maps C{name} to C{po}.
 253
 254         @param name: Name of the changed mapping
 255         @type name: C{str}
 256         @param po: Value of the changed mapping
 257         @type po: L{Blob} or L{Tree} or (C{str}, L{Blob} or L{Tree})
 258         @return: The new L{TreeData} object
 259         @rtype: L{TreeData}"""
 260         e = dict(self.entries)
 261         e[name] = self.__x(po)
 262         return type(self)(e)
 263     def del_entry(self, name):
 264         """Create a new L{TreeData} object identical to this one, except that
 265         it doesn't map C{name} to anything.
 266
 267         @param name: Name of the deleted mapping
 268         @type name: C{str}
 269         @return: The new L{TreeData} object
 270         @rtype: L{TreeData}"""
 271         e = dict(self.entries)
 272         del e[name]
 273         return type(self)(e)
 274     def commit(self, repository):
 275         """Commit the tree.
 276         @return: The committed tree
 277         @rtype: L{Tree}"""
 278         listing = ''.join(
 279             '%s %s %s\t%s\0' % (mode, obj.typename, obj.sha1, name)
 280             for (name, (mode, obj)) in self.entries.iteritems())
 281         sha1 = repository.run(['git', 'mktree', '-z']
 282                               ).raw_input(listing).output_one_line()
 283         return repository.get_tree(sha1)
 284     @classmethod
 285     def parse(cls, repository, s):
 286         """Parse a raw git tree description.
 287
 288         @return: A new L{TreeData} object
 289         @rtype: L{TreeData}"""
 290         entries = {}
 291         for line in s.split('\0')[:-1]:
 292             m = re.match(r'^([0-7]{6}) ([a-z]+) ([0-9a-f]{40})\t(.*)$', line)
 293             assert m
 294             perm, type, sha1, name = m.groups()
 295             entries[name] = (perm, repository.get_object(type, sha1))
 296         return cls(entries)
 297
 298 class Tree(GitObject):
 299     """Represents a git tree object. All the actual data contents of the
 300     tree object is stored in the L{data} member, which is a
 301     L{TreeData} object."""
 302     typename = 'tree'
 303     default_perm = '040000'
 304     def __init__(self, repository, sha1):
 305         self.__sha1 = sha1
 306         self.__repository = repository
 307         self.__data = None
 308     sha1 = property(lambda self: self.__sha1)
 309     @property
 310     def data(self):
 311         if self.__data == None:
 312             self.__data = TreeData.parse(
 313                 self.__repository,
 314                 self.__repository.run(['git', 'ls-tree', '-z', self.sha1]
 315                                       ).raw_output())
 316         return self.__data
 317     def __str__(self):
 318         return 'Tree<sha1: %s>' % self.sha1
 319
 320 class CommitData(Immutable, Repr):
 321     """Represents the data contents of a git commit object."""
 322     def __init__(self, tree = NoValue, parents = NoValue, author = NoValue,
 323                  committer = NoValue, message = NoValue, defaults = NoValue):
 324         d = make_defaults(defaults)
 325         self.__tree = d(tree, 'tree')
 326         self.__parents = d(parents, 'parents')
 327         self.__author = d(author, 'author', Person.author)
 328         self.__committer = d(committer, 'committer', Person.committer)
 329         self.__message = d(message, 'message')
 330     tree = property(lambda self: self.__tree)
 331     parents = property(lambda self: self.__parents)
 332     @property
 333     def parent(self):
 334         assert len(self.__parents) == 1
 335         return self.__parents[0]
 336     author = property(lambda self: self.__author)
 337     committer = property(lambda self: self.__committer)
 338     message = property(lambda self: self.__message)
 339     def set_tree(self, tree):
 340         return type(self)(tree = tree, defaults = self)
 341     def set_parents(self, parents):
 342         return type(self)(parents = parents, defaults = self)
 343     def add_parent(self, parent):
 344         return type(self)(parents = list(self.parents or []) + [parent],
 345                           defaults = self)
 346     def set_parent(self, parent):
 347         return self.set_parents([parent])
 348     def set_author(self, author):
 349         return type(self)(author = author, defaults = self)
 350     def set_committer(self, committer):
 351         return type(self)(committer = committer, defaults = self)
 352     def set_message(self, message):
 353         return type(self)(message = message, defaults = self)
 354     def is_nochange(self):
 355         return len(self.parents) == 1 and self.tree == self.parent.data.tree
 356     def __str__(self):
 357         if self.tree == None:
 358             tree = None
 359         else:
 360             tree = self.tree.sha1
 361         if self.parents == None:
 362             parents = None
 363         else:
 364             parents = [p.sha1 for p in self.parents]
 365         return ('CommitData<tree: %s, parents: %s, author: %s,'
 366                 ' committer: %s, message: "%s">'
 367                 ) % (tree, parents, self.author, self.committer, self.message)
 368     def commit(self, repository):
 369         """Commit the commit.
 370         @return: The committed commit
 371         @rtype: L{Commit}"""
 372         c = ['git', 'commit-tree', self.tree.sha1]
 373         for p in self.parents:
 374             c.append('-p')
 375             c.append(p.sha1)
 376         env = {}
 377         for p, v1 in ((self.author, 'AUTHOR'),
 378                        (self.committer, 'COMMITTER')):
 379             if p != None:
 380                 for attr, v2 in (('name', 'NAME'), ('email', 'EMAIL'),
 381                                  ('date', 'DATE')):
 382                     if getattr(p, attr) != None:
 383                         env['GIT_%s_%s' % (v1, v2)] = str(getattr(p, attr))
 384         sha1 = repository.run(c, env = env).raw_input(self.message
 385                                                       ).output_one_line()
 386         return repository.get_commit(sha1)
 387     @classmethod
 388     def parse(cls, repository, s):
 389         """Parse a raw git commit description.
 390         @return: A new L{CommitData} object
 391         @rtype: L{CommitData}"""
 392         cd = cls(parents = [])
 393         lines = list(s.splitlines(True))
 394         for i in xrange(len(lines)):
 395             line = lines[i].strip()
 396             if not line:
 397                 return cd.set_message(''.join(lines[i+1:]))
 398             key, value = line.split(None, 1)
 399             if key == 'tree':
 400                 cd = cd.set_tree(repository.get_tree(value))
 401             elif key == 'parent':
 402                 cd = cd.add_parent(repository.get_commit(value))
 403             elif key == 'author':
 404                 cd = cd.set_author(Person.parse(value))
 405             elif key == 'committer':
 406                 cd = cd.set_committer(Person.parse(value))
 407             else:
 408                 assert False
 409         assert False
 410
 411 class Commit(GitObject):
 412     """Represents a git commit object. All the actual data contents of the
 413     commit object is stored in the L{data} member, which is a
 414     L{CommitData} object."""
 415     typename = 'commit'
 416     def __init__(self, repository, sha1):
 417         self.__sha1 = sha1
 418         self.__repository = repository
 419         self.__data = None
 420     sha1 = property(lambda self: self.__sha1)
 421     @property
 422     def data(self):
 423         if self.__data == None:
 424             self.__data = CommitData.parse(
 425                 self.__repository,
 426                 self.__repository.cat_object(self.sha1))
 427         return self.__data
 428     def __str__(self):
 429         return 'Commit<sha1: %s, data: %s>' % (self.sha1, self.__data)
 430
 431 class Refs(object):
 432     """Accessor for the refs stored in a git repository. Will
 433     transparently cache the values of all refs."""
 434     def __init__(self, repository):
 435         self.__repository = repository
 436         self.__refs = None
 437     def __cache_refs(self):
 438         """(Re-)Build the cache of all refs in the repository."""
 439         self.__refs = {}
 440         for line in self.__repository.run(['git', 'show-ref']).output_lines():
 441             m = re.match(r'^([0-9a-f]{40})\s+(\S+)$', line)
 442             sha1, ref = m.groups()
 443             self.__refs[ref] = sha1
 444     def get(self, ref):
 445         """Get the Commit the given ref points to. Throws KeyError if ref
 446         doesn't exist."""
 447         if self.__refs == None:
 448             self.__cache_refs()
 449         return self.__repository.get_commit(self.__refs[ref])
 450     def exists(self, ref):
 451         """Check if the given ref exists."""
 452         try:
 453             self.get(ref)
 454         except KeyError:
 455             return False
 456         else:
 457             return True
 458     def set(self, ref, commit, msg):
 459         """Write the sha1 of the given Commit to the ref. The ref may or may
 460         not already exist."""
 461         if self.__refs == None:
 462             self.__cache_refs()
 463         old_sha1 = self.__refs.get(ref, '0'*40)
 464         new_sha1 = commit.sha1
 465         if old_sha1 != new_sha1:
 466             self.__repository.run(['git', 'update-ref', '-m', msg,
 467                                    ref, new_sha1, old_sha1]).no_output()
 468             self.__refs[ref] = new_sha1
 469     def delete(self, ref):
 470         """Delete the given ref. Throws KeyError if ref doesn't exist."""
 471         if self.__refs == None:
 472             self.__cache_refs()
 473         self.__repository.run(['git', 'update-ref',
 474                                '-d', ref, self.__refs[ref]]).no_output()
 475         del self.__refs[ref]
 476
 477 class ObjectCache(object):
 478     """Cache for Python objects, for making sure that we create only one
 479     Python object per git object. This reduces memory consumption and
 480     makes object comparison very cheap."""
 481     def __init__(self, create):
 482         self.__objects = {}
 483         self.__create = create
 484     def __getitem__(self, name):
 485         if not name in self.__objects:
 486             self.__objects[name] = self.__create(name)
 487         return self.__objects[name]
 488     def __contains__(self, name):
 489         return name in self.__objects
 490     def __setitem__(self, name, val):
 491         assert not name in self.__objects
 492         self.__objects[name] = val
 493
 494 class RunWithEnv(object):
 495     def run(self, args, env = {}):
 496         """Run the given command with an environment given by self.env.
 497
 498         @type args: list of strings
 499         @param args: Command and argument vector
 500         @type env: dict
 501         @param env: Extra environment"""
 502         return run.Run(*args).env(utils.add_dict(self.env, env))
 503
 504 class RunWithEnvCwd(RunWithEnv):
 505     def run(self, args, env = {}):
 506         """Run the given command with an environment given by self.env, and
 507         current working directory given by self.cwd.
 508
 509         @type args: list of strings
 510         @param args: Command and argument vector
 511         @type env: dict
 512         @param env: Extra environment"""
 513         return RunWithEnv.run(self, args, env).cwd(self.cwd)
 514     def run_in_cwd(self, args):
 515         """Run the given command with an environment given by self.env and
 516         self.env_in_cwd, without changing the current working
 517         directory.
 518
 519         @type args: list of strings
 520         @param args: Command and argument vector"""
 521         return RunWithEnv.run(self, args, self.env_in_cwd)
 522
 523 class Repository(RunWithEnv):
 524     """Represents a git repository."""
 525     def __init__(self, directory):
 526         self.__git_dir = directory
 527         self.__refs = Refs(self)
 528         self.__blobs = ObjectCache(lambda sha1: Blob(self, sha1))
 529         self.__trees = ObjectCache(lambda sha1: Tree(self, sha1))
 530         self.__commits = ObjectCache(lambda sha1: Commit(self, sha1))
 531         self.__default_index = None
 532         self.__default_worktree = None
 533         self.__default_iw = None
 534     env = property(lambda self: { 'GIT_DIR': self.__git_dir })
 535     @classmethod
 536     def default(cls):
 537         """Return the default repository."""
 538         try:
 539             return cls(run.Run('git', 'rev-parse', '--git-dir'
 540                                ).output_one_line())
 541         except run.RunException:
 542             raise RepositoryException('Cannot find git repository')
 543     @property
 544     def current_branch_name(self):
 545         """Return the name of the current branch."""
 546         return utils.strip_prefix('refs/heads/', self.head_ref)
 547     @property
 548     def default_index(self):
 549         """An L{Index} object representing the default index file for the
 550         repository."""
 551         if self.__default_index == None:
 552             self.__default_index = Index(
 553                 self, (os.environ.get('GIT_INDEX_FILE', None)
 554                        or os.path.join(self.__git_dir, 'index')))
 555         return self.__default_index
 556     def temp_index(self):
 557         """Return an L{Index} object representing a new temporary index file
 558         for the repository."""
 559         return Index(self, self.__git_dir)
 560     @property
 561     def default_worktree(self):
 562         """A L{Worktree} object representing the default work tree."""
 563         if self.__default_worktree == None:
 564             path = os.environ.get('GIT_WORK_TREE', None)
 565             if not path:
 566                 o = run.Run('git', 'rev-parse', '--show-cdup').output_lines()
 567                 o = o or ['.']
 568                 assert len(o) == 1
 569                 path = o[0]
 570             self.__default_worktree = Worktree(path)
 571         return self.__default_worktree
 572     @property
 573     def default_iw(self):
 574         """An L{IndexAndWorktree} object representing the default index and
 575         work tree for this repository."""
 576         if self.__default_iw == None:
 577             self.__default_iw = IndexAndWorktree(self.default_index,
 578                                                  self.default_worktree)
 579         return self.__default_iw
 580     directory = property(lambda self: self.__git_dir)
 581     refs = property(lambda self: self.__refs)
 582     def cat_object(self, sha1):
 583         return self.run(['git', 'cat-file', '-p', sha1]).raw_output()
 584     def rev_parse(self, rev, discard_stderr = False):
 585         try:
 586             return self.get_commit(self.run(
 587                     ['git', 'rev-parse', '%s^{commit}' % rev]
 588                     ).discard_stderr(discard_stderr).output_one_line())
 589         except run.RunException:
 590             raise RepositoryException('%s: No such revision' % rev)
 591     def get_blob(self, sha1):
 592         return self.__blobs[sha1]
 593     def get_tree(self, sha1):
 594         return self.__trees[sha1]
 595     def get_commit(self, sha1):
 596         return self.__commits[sha1]
 597     def get_object(self, type, sha1):
 598         return { Blob.typename: self.get_blob,
 599                  Tree.typename: self.get_tree,
 600                  Commit.typename: self.get_commit }[type](sha1)
 601     def commit(self, objectdata):
 602         return objectdata.commit(self)
 603     @property
 604     def head_ref(self):
 605         try:
 606             return self.run(['git', 'symbolic-ref', '-q', 'HEAD']
 607                             ).output_one_line()
 608         except run.RunException:
 609             raise DetachedHeadException()
 610     def set_head_ref(self, ref, msg):
 611         self.run(['git', 'symbolic-ref', '-m', msg, 'HEAD', ref]).no_output()
 612     def simple_merge(self, base, ours, theirs):
 613         index = self.temp_index()
 614         try:
 615             result, index_tree = index.merge(base, ours, theirs)
 616         finally:
 617             index.delete()
 618         return result
 619     def apply(self, tree, patch_text, quiet):
 620         """Given a L{Tree} and a patch, will either return the new L{Tree}
 621         that results when the patch is applied, or None if the patch
 622         couldn't be applied."""
 623         assert isinstance(tree, Tree)
 624         if not patch_text:
 625             return tree
 626         index = self.temp_index()
 627         try:
 628             index.read_tree(tree)
 629             try:
 630                 index.apply(patch_text, quiet)
 631                 return index.write_tree()
 632             except MergeException:
 633                 return None
 634         finally:
 635             index.delete()
 636     def diff_tree(self, t1, t2, diff_opts):
 637         """Given two L{Tree}s C{t1} and C{t2}, return the patch that takes
 638         C{t1} to C{t2}.
 639
 640         @type diff_opts: list of strings
 641         @param diff_opts: Extra diff options
 642         @rtype: String
 643         @return: Patch text"""
 644         assert isinstance(t1, Tree)
 645         assert isinstance(t2, Tree)
 646         return self.run(['git', 'diff-tree', '-p'] + list(diff_opts)
 647                         + [t1.sha1, t2.sha1]).raw_output()
 648     def diff_tree_files(self, t1, t2):
 649         """Given two L{Tree}s C{t1} and C{t2}, iterate over all files for
 650         which they differ. For each file, yield a tuple with the old
 651         file mode, the new file mode, the old blob, the new blob, the
 652         status, the old filename, and the new filename. Except in case
 653         of a copy or a rename, the old and new filenames are
 654         identical."""
 655         assert isinstance(t1, Tree)
 656         assert isinstance(t2, Tree)
 657         i = iter(self.run(['git', 'diff-tree', '-r', '-z'] + [t1.sha1, t2.sha1]
 658                           ).raw_output().split('\0'))
 659         try:
 660             while True:
 661                 x = i.next()
 662                 if not x:
 663                     continue
 664                 omode, nmode, osha1, nsha1, status = x[1:].split(' ')
 665                 fn1 = i.next()
 666                 if status[0] in ['C', 'R']:
 667                     fn2 = i.next()
 668                 else:
 669                     fn2 = fn1
 670                 yield (omode, nmode, self.get_blob(osha1),
 671                        self.get_blob(nsha1), status, fn1, fn2)
 672         except StopIteration:
 673             pass
 674
 675 class MergeException(exception.StgException):
 676     """Exception raised when a merge fails for some reason."""
 677
 678 class MergeConflictException(MergeException):
 679     """Exception raised when a merge fails due to conflicts."""
 680
 681 class Index(RunWithEnv):
 682     """Represents a git index file."""
 683     def __init__(self, repository, filename):
 684         self.__repository = repository
 685         if os.path.isdir(filename):
 686             # Create a temp index in the given directory.
 687             self.__filename = os.path.join(
 688                 filename, 'index.temp-%d-%x' % (os.getpid(), id(self)))
 689             self.delete()
 690         else:
 691             self.__filename = filename
 692     env = property(lambda self: utils.add_dict(
 693             self.__repository.env, { 'GIT_INDEX_FILE': self.__filename }))
 694     def read_tree(self, tree):
 695         self.run(['git', 'read-tree', tree.sha1]).no_output()
 696     def write_tree(self):
 697         """Write the index contents to the repository.
 698         @return: The resulting L{Tree}
 699         @rtype: L{Tree}"""
 700         try:
 701             return self.__repository.get_tree(
 702                 self.run(['git', 'write-tree']).discard_stderr(
 703                     ).output_one_line())
 704         except run.RunException:
 705             raise MergeException('Conflicting merge')
 706     def is_clean(self):
 707         try:
 708             self.run(['git', 'update-index', '--refresh']).discard_output()
 709         except run.RunException:
 710             return False
 711         else:
 712             return True
 713     def apply(self, patch_text, quiet):
 714         """In-index patch application, no worktree involved."""
 715         try:
 716             r = self.run(['git', 'apply', '--cached']).raw_input(patch_text)
 717             if quiet:
 718                 r = r.discard_stderr()
 719             r.no_output()
 720         except run.RunException:
 721             raise MergeException('Patch does not apply cleanly')
 722     def apply_treediff(self, tree1, tree2, quiet):
 723         """Apply the diff from C{tree1} to C{tree2} to the index."""
 724         # Passing --full-index here is necessary to support binary
 725         # files. It is also sufficient, since the repository already
 726         # contains all involved objects; in other words, we don't have
 727         # to use --binary.
 728         self.apply(self.__repository.diff_tree(tree1, tree2, ['--full-index']),
 729                    quiet)
 730     def merge(self, base, ours, theirs, current = None):
 731         """Use the index (and only the index) to do a 3-way merge of the
 732         L{Tree}s C{base}, C{ours} and C{theirs}. The merge will either
 733         succeed (in which case the first half of the return value is
 734         the resulting tree) or fail cleanly (in which case the first
 735         half of the return value is C{None}).
 736
 737         If C{current} is given (and not C{None}), it is assumed to be
 738         the L{Tree} currently stored in the index; this information is
 739         used to avoid having to read the right tree (either of C{ours}
 740         and C{theirs}) into the index if it's already there. The
 741         second half of the return value is the tree now stored in the
 742         index, or C{None} if unknown. If the merge succeeded, this is
 743         often the merge result."""
 744         assert isinstance(base, Tree)
 745         assert isinstance(ours, Tree)
 746         assert isinstance(theirs, Tree)
 747         assert current == None or isinstance(current, Tree)
 748
 749         # Take care of the really trivial cases.
 750         if base == ours:
 751             return (theirs, current)
 752         if base == theirs:
 753             return (ours, current)
 754         if ours == theirs:
 755             return (ours, current)
 756
 757         if current == theirs:
 758             # Swap the trees. It doesn't matter since merging is
 759             # symmetric, and will allow us to avoid the read_tree()
 760             # call below.
 761             ours, theirs = theirs, ours
 762         if current != ours:
 763             self.read_tree(ours)
 764         try:
 765             self.apply_treediff(base, theirs, quiet = True)
 766             result = self.write_tree()
 767             return (result, result)
 768         except MergeException:
 769             return (None, ours)
 770     def delete(self):
 771         if os.path.isfile(self.__filename):
 772             os.remove(self.__filename)
 773     def conflicts(self):
 774         """The set of conflicting paths."""
 775         paths = set()
 776         for line in self.run(['git', 'ls-files', '-z', '--unmerged']
 777                              ).raw_output().split('\0')[:-1]:
 778             stat, path = line.split('\t', 1)
 779             paths.add(path)
 780         return paths
 781
 782 class Worktree(object):
 783     """Represents a git worktree (that is, a checked-out file tree)."""
 784     def __init__(self, directory):
 785         self.__directory = directory
 786     env = property(lambda self: { 'GIT_WORK_TREE': '.' })
 787     env_in_cwd = property(lambda self: { 'GIT_WORK_TREE': self.directory })
 788     directory = property(lambda self: self.__directory)
 789
 790 class CheckoutException(exception.StgException):
 791     """Exception raised when a checkout fails."""
 792
 793 class IndexAndWorktree(RunWithEnvCwd):
 794     """Represents a git index and a worktree. Anything that an index or
 795     worktree can do on their own are handled by the L{Index} and
 796     L{Worktree} classes; this class concerns itself with the
 797     operations that require both."""
 798     def __init__(self, index, worktree):
 799         self.__index = index
 800         self.__worktree = worktree
 801     index = property(lambda self: self.__index)
 802     env = property(lambda self: utils.add_dict(self.__index.env,
 803                                                self.__worktree.env))
 804     env_in_cwd = property(lambda self: self.__worktree.env_in_cwd)
 805     cwd = property(lambda self: self.__worktree.directory)
 806     def checkout_hard(self, tree):
 807         assert isinstance(tree, Tree)
 808         self.run(['git', 'read-tree', '--reset', '-u', tree.sha1]
 809                  ).discard_output()
 810     def checkout(self, old_tree, new_tree):
 811         # TODO: Optionally do a 3-way instead of doing nothing when we
 812         # have a problem. Or maybe we should stash changes in a patch?
 813         assert isinstance(old_tree, Tree)
 814         assert isinstance(new_tree, Tree)
 815         try:
 816             self.run(['git', 'read-tree', '-u', '-m',
 817                       '--exclude-per-directory=.gitignore',
 818                       old_tree.sha1, new_tree.sha1]
 819                      ).discard_output()
 820         except run.RunException:
 821             raise CheckoutException('Index/workdir dirty')
 822     def merge(self, base, ours, theirs):
 823         assert isinstance(base, Tree)
 824         assert isinstance(ours, Tree)
 825         assert isinstance(theirs, Tree)
 826         try:
 827             r = self.run(['git', 'merge-recursive', base.sha1, '--', ours.sha1,
 828                           theirs.sha1],
 829                          env = { 'GITHEAD_%s' % base.sha1: 'ancestor',
 830                                  'GITHEAD_%s' % ours.sha1: 'current',
 831                                  'GITHEAD_%s' % theirs.sha1: 'patched'})
 832             r.discard_output()
 833         except run.RunException, e:
 834             if r.exitcode == 1:
 835                 raise MergeConflictException()
 836             else:
 837                 raise MergeException('Index/worktree dirty')
 838     def changed_files(self, tree, pathlimits = []):
 839         """Return the set of files in the worktree that have changed with
 840         respect to C{tree}. The listing is optionally restricted to
 841         those files that match any of the path limiters given.
 842
 843         The path limiters are relative to the current working
 844         directory; the returned file names are relative to the
 845         repository root."""
 846         assert isinstance(tree, Tree)
 847         return set(self.run_in_cwd(
 848                 ['git', 'diff-index', tree.sha1, '--name-only', '-z', '--']
 849                 + list(pathlimits)).raw_output().split('\0')[:-1])
 850     def update_index(self, paths):
 851         """Update the index with files from the worktree. C{paths} is an
 852         iterable of paths relative to the root of the repository."""
 853         cmd = ['git', 'update-index', '--remove']
 854         self.run(cmd + ['-z', '--stdin']
 855                  ).input_nulterm(paths).discard_output()
 856
 857 class Branch(object):
 858     """Represents a Git branch."""
 859     def __init__(self, repository, name):
 860         self.__repository = repository
 861         self.__name = name
 862         try:
 863             self.head
 864         except KeyError:
 865             raise BranchException('%s: no such branch' % name)
 866
 867     name = property(lambda self: self.__name)
 868     repository = property(lambda self: self.__repository)
 869
 870     def __ref(self):
 871         return 'refs/heads/%s' % self.__name
 872     @property
 873     def head(self):
 874         return self.__repository.refs.get(self.__ref())
 875     def set_head(self, commit, msg):
 876         self.__repository.refs.set(self.__ref(), commit, msg)
 877
 878     def set_parent_remote(self, name):
 879         value = config.set('branch.%s.remote' % self.__name, name)
 880     def set_parent_branch(self, name):
 881         if config.get('branch.%s.remote' % self.__name):
 882             # Never set merge if remote is not set to avoid
 883             # possibly-erroneous lookups into 'origin'
 884             config.set('branch.%s.merge' % self.__name, name)
 885
 886     @classmethod
 887     def create(cls, repository, name, create_at = None):
 888         """Create a new Git branch and return the corresponding
 889         L{Branch} object."""
 890         try:
 891             branch = cls(repository, name)
 892         except BranchException:
 893             branch = None
 894         if branch:
 895             raise BranchException('%s: branch already exists' % name)
 896
 897         cmd = ['git', 'branch']
 898         if create_at:
 899             cmd.append(create_at.sha1)
 900         repository.run(['git', 'branch', create_at.sha1]).discard_output()
 901
 902         return cls(repository, name)