.\" Automatically generated by Pod::Man 4.14 (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
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    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::Repository::Command 3pm"
.TH Git::Repository::Command 3pm "2023-03-22" "perl v5.36.0" "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::Repository::Command \- Command objects for running git
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&    use Git::Repository::Command;
\&
\&    # invoke an external git command, and return an object
\&    $cmd = Git::Repository::Command\->new(@cmd);
\&
\&    # a Git::Repository object can provide more context
\&    $cmd = Git::Repository::Command\->new( $r, @cmd );
\&
\&    # options can be passed as a hashref
\&    $cmd = Git::Repository::Command\->new( $r, @cmd, \e%option );
\&
\&    # $cmd is basically a hash, with keys / accessors
\&    $cmd\->stdin();     # filehandle to the process\*(Aq stdin (write)
\&    $cmd\->stdout();    # filehandle to the process\*(Aq stdout (read)
\&    $cmd\->stderr();    # filehandle to the process\*(Aq stdout (read)
\&    $cmd\->pid();       # pid of the child process
\&
\&    # done!
\&    $cmd\->close();
\&
\&    # exit information
\&    $cmd\->exit();      # exit status
\&    $cmd\->signal();    # signal
\&    $cmd\->core();      # core dumped? (boolean)
\&
\&    # cut to the chase
\&    my ( $pid, $in, $out, $err ) = Git::Repository::Command\->spawn(@cmd);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Git::Repository::Command is a class that actually launches a \fBgit\fR
commands, allowing to interact with it through its \f(CW\*(C`STDIN\*(C'\fR, \f(CW\*(C`STDOUT\*(C'\fR
and \f(CW\*(C`STDERR\*(C'\fR.
.PP
This class is a subclass of System::Command, meant to be invoked
through Git::Repository.
.SH "METHODS"
.IX Header "METHODS"
As a subclass of System::Command,
Git::Repository::Command supports the following methods:
.SS "new"
.IX Subsection "new"
.Vb 1
\&    Git::Repository::Command\->new( @cmd );
.Ve
.PP
Runs a \fBgit\fR command with the parameters in \f(CW@cmd\fR.
.PP
If \f(CW@cmd\fR contains a Git::Repository object, it is used to provide
context to the \fBgit\fR command.
.PP
If \f(CW@cmd\fR contains one or more hash reference, they are taken as
\&\fIoption\fR hashes. The recognized keys are:
.ie n .IP """git""" 4
.el .IP "\f(CWgit\fR" 4
.IX Item "git"
The actual git binary to run. By default, it is just \f(CW\*(C`git\*(C'\fR.
.Sp
In case the \f(CW\*(C`git\*(C'\fR to be run is actually a command with parameters
(e.g. when using \fBsudo\fR or another command executer), the option value
should be an array reference with the command and parameters, like this:
.Sp
.Vb 1
\&    { git => [qw( sudo \-u nobody git )] }
.Ve
.ie n .IP """cwd""" 4
.el .IP "\f(CWcwd\fR" 4
.IX Item "cwd"
The \fIcurrent working directory\fR in which the git command will be run.
(\f(CW\*(C`chdir()\*(C'\fR will be called just before launching the command.)
.Sp
If not provided, it will default to the root of the Git repository work
tree (if the repository is bare, then no \f(CW\*(C`chdir()\*(C'\fR will be performed).
.ie n .IP """env""" 4
.el .IP "\f(CWenv\fR" 4
.IX Item "env"
A hashref containing key / values to add to the git command environment.
.ie n .IP """fatal""" 4
.el .IP "\f(CWfatal\fR" 4
.IX Item "fatal"
An arrayref containing a list of exit codes that will be considered
fatal by \f(CW\*(C`final_output()\*(C'\fR.
.Sp
Prepending the value with \f(CW\*(C`\-\*(C'\fR will make it non-fatal, which can be
useful to override a default. The string \f(CW"!0"\fR can be used as a
shortcut for \f(CW\*(C`[ 1 .. 255 ]\*(C'\fR.
.Sp
If several option hashes have the \f(CW\*(C`fatal\*(C'\fR key, the lists of exit codes
will be combined, with the values provided last taking precedence (when
using a combination of positive / negative values).
.Sp
The generated list always contains \f(CW128\fR and \f(CW129\fR; to make them
non-fatal, just add \f(CW\*(C`\-128\*(C'\fR and \f(CW\*(C`\-129\*(C'\fR to the list provided to the
\&\f(CW\*(C`fatal\*(C'\fR option.
.ie n .IP """input""" 4
.el .IP "\f(CWinput\fR" 4
.IX Item "input"
A string that is send to the git command standard input, which is then closed.
.Sp
Using the empty string as \f(CW\*(C`input\*(C'\fR will close the git command standard input
without writing to it.
.Sp
Using \f(CW\*(C`undef\*(C'\fR as \f(CW\*(C`input\*(C'\fR will not do anything. This behaviour provides
a way to modify options inherited from \f(CW\*(C`new()\*(C'\fR or a hash populated by
some other part of the program.
.Sp
On some systems, some git commands may close standard input on startup,
which will cause a \f(CW\*(C`SIGPIPE\*(C'\fR when trying to write to it. This will raise
an exception.
.ie n .IP """quiet""" 4
.el .IP "\f(CWquiet\fR" 4
.IX Item "quiet"
Boolean option to control the output of warnings.
.Sp
If true, methods such as \f(CW\*(C`final_output()\*(C'\fR will not warn when Git outputs
messages on \f(CW\*(C`STDERR\*(C'\fR.
.PP
If the Git::Repository object has its own option hash, it will be used
to provide default values that can be overridden by the actual option hash
passed to \f(CW\*(C`new()\*(C'\fR.
.PP
If several option hashes are passed to \f(CW\*(C`new()\*(C'\fR, they will all be merged,
keys in later hashes taking precedence over keys in earlier hashes.
.PP
The Git::Repository::Command object returned by \f(CW\*(C`new()\*(C'\fR has a
number of attributes defined (see below).
.SS "close"
.IX Subsection "close"
.Vb 1
\&    $cmd\->close();
.Ve
.PP
Close all pipes to the child process, and collects exit status, etc.
and defines a number of attributes (see below).
.SS "final_output"
.IX Subsection "final_output"
.Vb 1
\&    $cmd\->final_output( @callbacks );
.Ve
.PP
Collect all the output, and terminate the command.
.PP
Returns the output as a string in scalar context,
or as a list of lines in list context. Also accepts a hashref of options.
.PP
Lines are automatically \f(CW\*(C`chomp\*(C'\fRed.
.PP
If \f(CW@callbacks\fR is provided, the code references will be applied
successively to each line of output. The line being processed is in \f(CW$_\fR,
but the coderef must still return the result string.
.PP
If the Git command printed anything on stderr, it will be printed as
warnings. If the git sub-process exited with a status code listed in
the \f(CW\*(C`fatal\*(C'\fR option, it will \f(CW\*(C`die()\*(C'\fR. The defaults fatal exit codes
are \f(CW128\fR (fatal error), and \f(CW129\fR (usage message).
.SS "Accessors"
.IX Subsection "Accessors"
The attributes of a Git::Repository::Command object are also accessible
through a number of accessors.
.PP
The object returned by \f(CW\*(C`new()\*(C'\fR will have the following attributes defined:
.IP "cmdline" 4
.IX Item "cmdline"
Return the command-line actually executed, as a list of strings.
.IP "pid" 4
.IX Item "pid"
The \s-1PID\s0 of the underlying \fBgit\fR command.
.IP "stdin" 4
.IX Item "stdin"
A filehandle opened in write mode to the child process' standard input.
.IP "stdout" 4
.IX Item "stdout"
A filehandle opened in read mode to the child process' standard output.
.IP "stderr" 4
.IX Item "stderr"
A filehandle opened in read mode to the child process' standard error output.
.PP
Regarding the handles to the child git process, note that in the
following code:
.PP
.Vb 1
\&    my $fh = Git::Repository::Command\->new( @cmd )\->stdout;
.Ve
.PP
\&\f(CW$fh\fR is opened and points to the output of the git subcommand, while
the anonymous Git::Repository::Command object has been destroyed.
.PP
After the call to \f(CW\*(C`close()\*(C'\fR, the following attributes will be defined:
.IP "exit" 4
.IX Item "exit"
The exit status of the underlying \fBgit\fR command.
.IP "core" 4
.IX Item "core"
A boolean value indicating if the command dumped core.
.IP "signal" 4
.IX Item "signal"
The signal, if any, that killed the command.
.SH "AUTHOR"
.IX Header "AUTHOR"
Philippe Bruhat (BooK) <book@cpan.org>
.SH "ACKNOWLEDGEMENTS"
.IX Header "ACKNOWLEDGEMENTS"
The core of Git::Repository::Command has been moved into its own
distribution: System::Command. Proper Win32 support is now delegated
to that module.
.PP
Before that, the Win32 implementation owed a lot to two people.
First, Olivier Raginel (\s-1BABAR\s0), who provided me with a test platform
with Git and Strawberry Perl installed, which I could use at any time.
Many thanks go also to Chris Williams (\s-1BINGOS\s0) for pointing me towards
perlmonks posts by ikegami that contained crucial elements to a working
MSWin32 implementation.
.PP
In the end, it was Christian Walder (\s-1MITHALDU\s0) who helped me finalize
Win32 support for System::Command through a quick round of edit
(on my Linux box) and testing (on his Windows box) during the Perl \s-1QA\s0
Hackathon 2013 in Lancaster.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2010\-2016 Philippe Bruhat (BooK), all rights reserved.
.SH "LICENSE"
.IX Header "LICENSE"
This program is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.