perl/Git/Commit.pm

   1 =head1 NAME
   2
   3 Git::Commit - Object-oriented interface to Git commit objects.
   4
   5 =head1 DESCRIPTION
   6
   7 Git::Commit is a class representing a commit object in a Git
   8 repository.  It stringifies to the commit object's SHA1.
   9
  10 =cut
  11
  12 use strict;
  13 use warnings;
  14
  15
  16 package Git::Commit;
  17
  18 use base qw(Git::Object);
  19
  20
  21 # Keep documentation in one place to save space.
  22
  23 =head1 METHODS
  24
  25 =head2 General Methods
  26
  27 =over
  28
  29 =item $commit = Git::Commit->new($repo, $sha1)
  30
  31 Return a new Git::Commit instance for a commit object with $sha1 in
  32 repository $repo.
  33
  34 The commit object is loaded lazily.  Hence, calls to this method are
  35 free, and it does not check whether $sha1 exists and has the right
  36 type.  However, accessing any of the commit object's properties will
  37 fail if $sha1 is not a valid commit object.
  38
  39 Note that $sha1 must be the SHA1 of a commit object; tag objects are
  40 not dereferenced.
  41
  42 The author, committer and message methods return Unicode strings,
  43 decoded according to the "encoding" header, with UTF-8 and then
  44 Latin-1 as fallbacks.  (These Unicode strings can contain code points
  45 greater than 256 and are *not* UTF-8 strings; see man perlunitut on
  46 how Perl handles Unicode.)
  47
  48 You will usually want to call $repo->get_commit($sha1) instead of
  49 instantiating this class directly; see L<Git::Repo>.
  50
  51 =item $obj->repo
  52
  53 Return the Git::Repo instance this object was instantiated with.
  54
  55 =item $obj->sha1
  56
  57 Return the SHA1 of this commit object, as provided at instantiation time.
  58
  59 =back
  60
  61 =head2 Property Methods
  62
  63 Calling any of these methods will cause the commit object to be loaded
  64 from the repository, if it hasn't been loaded already.
  65
  66 =over
  67
  68 =item $commit->tree
  69
  70 Return an object that stringifies to the SHA1 of the tree that this
  71 commit object refers to.  (Currently this returns an actual string,
  72 but don't rely on it.)
  73
  74 =item $commit->parents
  75
  76 Return an array of zero or more parent commit objects.  Note that
  77 commit objects stringify to their respective SHA1s, so you can
  78 alternatively treat this as an array of SHA1 strings.
  79
  80 =item $commit->author
  81
  82 Return the author of this commit object as a Unicode string.
  83
  84 =item $commit->committer
  85
  86 Return the committer of this commit object as a Unicode string.
  87
  88 =item $commit->message
  89
  90 Return the commit message of this commit object as a Unicode string.
  91
  92 =item $commit->encoding
  93
  94 Return the encoding header of the commit object, or undef if no
  95 encoding header is present; note that Git::Commit does the necessary
  96 decoding for you, so you should not normally need this method.
  97
  98 =back
  99
 100 =cut
 101
 102
 103 sub tree {
 104         my $self = shift;
 105         $self->_load;
 106         return $self->{tree};
 107 }
 108
 109 sub parents {
 110         my $self = shift;
 111         $self->_load;
 112         return map { ref($self)->new($self->repo, $_) } @{$self->{parents}};
 113 }
 114
 115 sub author {
 116         my $self = shift;
 117         $self->_load;
 118         return $self->_decode($self->{author});
 119 }
 120
 121 sub committer {
 122         my $self = shift;
 123         $self->_load;
 124         return $self->_decode($self->{committer});
 125 }
 126
 127 sub message {
 128         my $self = shift;
 129         $self->_load;
 130         return $self->_decode($self->{message});
 131 }
 132
 133 sub encoding {
 134         my $self = shift;
 135         $self->_load;
 136         return $self->{encoding};
 137 }
 138
 139 # Auxiliary method to load (and parse) the commit object from the
 140 # repository if it hasn't already been loaded.  Optional parameter:
 141 # The raw contents of the commit object; the commit object will be
 142 # retrieved from the repository if that parameter is not given.
 143 sub _load {
 144         my ($self, $raw_text) = shift;
 145         return if exists $self->{message};  # already loaded
 146
 147         my $sha1 = $self->sha1;
 148         if (!defined $raw_text) {
 149                 # Retrieve from the repository.
 150                 (my $type, $raw_text) = $self->repo->get_object($sha1);
 151                 die "$sha1 is a $type object (expected a commit object)"
 152                     unless $type eq 'commit';
 153         }
 154
 155         (my $header, $self->{message}) = split "\n\n", $raw_text, 2;
 156         # Parse header.
 157         for my $line (split "\n", $header) {
 158                 local $/ = "\n"; # for chomp
 159                 chomp($line);
 160                 my ($key, $value) = split ' ', $line, 2;
 161                 if ($key eq 'tree') {
 162                         $self->{tree} = $value;
 163                 } elsif ($key eq 'parent') {
 164                         push @{$self->{parents}}, $value;
 165                 } elsif ($key eq 'author') {
 166                         $self->{author} = $value;
 167                 } elsif ($key eq 'committer') {
 168                         $self->{committer} = $value;
 169                 } elsif ($key eq 'encoding') {
 170                         $self->{encoding} = $value;
 171                 } else {
 172                         # Ignore unrecognized header lines.
 173                 }
 174         }
 175         undef;
 176 }
 177
 178
 179 1;