.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Git::Raw::Commit 3pm"
.TH Git::Raw::Commit 3pm 2024-01-10 "perl v5.38.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
Git::Raw::Commit \- Git commit class
.SH VERSION
.IX Header "VERSION"
version 0.90
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 1
\&    use Git::Raw;
\&
\&    # open the Git repository at $path
\&    my $repo = Git::Raw::Repository \-> open($path);
\&
\&    # add a file to the repository default index
\&    my $index = $repo \-> index;
\&    $index \-> add(\*(Aqtest\*(Aq);
\&    $index \-> write;
\&
\&    # create a new tree out of the repository index
\&    my $tree_id = $index \-> write_tree;
\&    my $tree    = $repo \-> lookup($tree_id);
\&
\&    # retrieve user\*(Aqs name and email from the Git configuration
\&    my $config = $repo \-> config;
\&    my $name   = $config \-> str(\*(Aquser.name\*(Aq);
\&    my $email  = $config \-> str(\*(Aquser.email\*(Aq);
\&
\&    # create a new Git signature
\&    my $me = Git::Raw::Signature \-> now($name, $email);
\&
\&    # create a new commit out of the above tree, with the repository HEAD as
\&    # parent
\&    my $commit = $repo \-> commit(
\&      \*(Aqsome commit\*(Aq, $me, $me, [ $repo \-> head \-> target ], $tree
\&    );
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
A \f(CW\*(C`Git::Raw::Commit\*(C'\fR represents a Git commit.
.PP
\&\fBWARNING\fR: The API of this module is unstable and may change without warning
(any change will be appropriately documented in the changelog).
.SH METHODS
.IX Header "METHODS"
.ie n .SS "create( $repo, $msg, $author, $committer, [@parents], $tree [, $update_ref ] )"
.el .SS "create( \f(CW$repo\fP, \f(CW$msg\fP, \f(CW$author\fP, \f(CW$committer\fP, [@parents], \f(CW$tree\fP [, \f(CW$update_ref\fP ] )"
.IX Subsection "create( $repo, $msg, $author, $committer, [@parents], $tree [, $update_ref ] )"
Create a new commit given a message, two Git::Raw::Signature (one is the
commit author and the other the committer), a list of parent commits and a
Git::Raw::Tree. If \f(CW$update_ref\fR is provided and is defined, the reference
with the corresponding name is automatically updated or created. If
\&\f(CW$update_ref\fR is \f(CW\*(C`undef\*(C'\fR, no reference is updated.  If \f(CW$update_ref\fR is not
provided, "HEAD" is updated.
.SS "annotated( )"
.IX Subsection "annotated( )"
Create a Git::Raw::AnnotatedCommit from the commit.
.ie n .SS "amend( $baseline, [@parents], $tree [, $update_ref ] )"
.el .SS "amend( \f(CW$baseline\fP, [@parents], \f(CW$tree\fP [, \f(CW$update_ref\fP ] )"
.IX Subsection "amend( $baseline, [@parents], $tree [, $update_ref ] )"
Create a new commit using \f(CW$baseline\fR as a template for the message, author
and committer. This method is useful for rewriting a commit, by replacing its
parents and trees. See \f(CW\*(C`Git::Raw::Commit\->create()\*(C'\fR
.ie n .SS "lookup( $repo, $id )"
.el .SS "lookup( \f(CW$repo\fP, \f(CW$id\fP )"
.IX Subsection "lookup( $repo, $id )"
Retrieve the commit corresponding to \f(CW$id\fR. This function is pretty much the
same as \f(CW\*(C`$repo\->lookup($id)\*(C'\fR except that it only returns commits. If the
commit doesn't exist, this function will return \f(CW\*(C`undef\*(C'\fR.
.SS "owner( )"
.IX Subsection "owner( )"
Retrieve the Git::Raw::Repository owning the commit.
.SS "id( )"
.IX Subsection "id( )"
Retrieve the id of the commit, as a string.
.SS "message( )"
.IX Subsection "message( )"
Retrieve the message of the commit.
.SS "message_trailers( )"
.IX Subsection "message_trailers( )"
Retrieve the message trailers of the commit. Returns a hash.
.SS "summary( )"
.IX Subsection "summary( )"
Retrieve the summary of the commit message.
.SS "body( )"
.IX Subsection "body( )"
Retrieve the body of the commit message.
.SS "author( )"
.IX Subsection "author( )"
Retrieve the Git::Raw::Signature representing the author of the commit.
.SS "committer( )"
.IX Subsection "committer( )"
Retrieve the Git::Raw::Signature representing the committer.
.SS "time( )"
.IX Subsection "time( )"
Retrieve the committer time of the commit.
.SS "offset( )"
.IX Subsection "offset( )"
Retrieve the committer time offset (in minutes) of the commit.
.SS "tree( )"
.IX Subsection "tree( )"
Retrieve the Git::Raw::Tree the commit points to.
.SS "parents( )"
.IX Subsection "parents( )"
Retrieve the list of parents of the commit.
.ie n .SS "merge( $commit, [ \e%merge_opts ])"
.el .SS "merge( \f(CW$commit\fP, [ \e%merge_opts ])"
.IX Subsection "merge( $commit, [ %merge_opts ])"
Merge \f(CW$commit\fR into this commit. See \f(CW\*(C`Git::Raw::Repository\->merge()\*(C'\fR
for valid \f(CW%merge_opts\fR values. Returns a Git::Raw::Index object
containing the merge result.
.ie n .SS "ancestor( $gen )"
.el .SS "ancestor( \f(CW$gen\fP )"
.IX Subsection "ancestor( $gen )"
Retrieve the Git::Raw::Commit object that is the \f(CW$gen\fR'th generation
ancestor of this commit, following only the first parents.
.SS "diff( [$parent_no, \e%diff_opts] )"
.IX Subsection "diff( [$parent_no, %diff_opts] )"
Retrieve the diff associated with the commit. If the commit has no parents,
\&\f(CW$parent_no\fR should not specified. Similarly, for merge commits, \f(CW$parent_no\fR
should be specified. See \f(CW\*(C`Git::Raw::Repository\->diff()\*(C'\fR for valid
\&\f(CW%diff_opts\fR values. In this context, specifying a Git::Raw::Tree in
\&\f(CW%diff_opts\fR will have no effect as it will be determined from the commit's
parent.
.SS "as_email( [\e%format_opts, \e%diff_opts] )"
.IX Subsection "as_email( [%format_opts, %diff_opts] )"
Retrieve the patch e\-mail associated with the commit. See
\&\f(CW\*(C`Git::Raw::Repository\->diff()\*(C'\fR for valid \f(CW%diff_opts\fR values. In this
context, specifying a Git::Raw::Tree in \f(CW%diff_opts\fR will have no effect
as it will be determined from the commit's parent.  Valid fields for the
\&\f(CW%format_opts\fR hash are:
.IP \(bu 4
"patch_no"
.Sp
The patch number for this commit.
.IP \(bu 4
"total_patches"
.Sp
Total number of patches.
.IP \(bu 4
"flags"
.Sp
E\-mail generation flags. Valid fields for this hash include:
.RS 4
.IP \(bu 8
"exclude_subject_patch_marker"
.Sp
Don't insert \f(CW"[PATCH]"\fR in the subject header.
.RE
.RS 4
.RE
.SH AUTHOR
.IX Header "AUTHOR"
Alessandro Ghedini <alexbio@cpan.org>
.PP
Jacques Germishuys <jacquesg@cpan.org>
.SH "LICENSE AND COPYRIGHT"
.IX Header "LICENSE AND COPYRIGHT"
Copyright 2012 Alessandro Ghedini.
.PP
This program is free software; you can redistribute it and/or modify it
under the terms of either: the GNU General Public License as published
by the Free Software Foundation; or the Artistic License.
.PP
See http://dev.perl.org/licenses/ for more information.