new

    Git::Repository::Command->new( @cmd );

Runs a git command with the parameters in @cmd.

If @cmd contains a Git::Repository object, it is used to provide context to the git command.

If @cmd contains one or more hash reference, they are taken as option hashes. The recognized keys are:

"git"

The actual git binary to run. By default, it is just "git".

In case the "git" to be run is actually a command with parameters (e.g. when using sudo or another command executer), the option value should be an array reference with the command and parameters, like this:

    { git => [qw( sudo -u nobody git )] }
    

"cwd"

The current working directory in which the git command will be run. ("chdir()" will be called just before launching the command.)

If not provided, it will default to the root of the Git repository work tree (if the repository is bare, then no "chdir()" will be performed).

"env"

A hashref containing key / values to add to the git command environment.

"fatal"

An arrayref containing a list of exit codes that will be considered fatal by "final_output()".

Prepending the value with "-" will make it non-fatal, which can be useful to override a default. The string "!0" can be used as a shortcut for "[ 1 .. 255 ]".

If several option hashes have the "fatal" key, the lists of exit codes will be combined, with the values provided last taking precedence (when using a combination of positive / negative values).

The generated list always contains 128 and 129; to make them non-fatal, just add "-128" and "-129" to the list provided to the "fatal" option.

"input"

A string that is send to the git command standard input, which is then closed.

Using the empty string as "input" will close the git command standard input without writing to it.

Using "undef" as "input" will not do anything. This behaviour provides a way to modify options inherited from "new()" or a hash populated by some other part of the program.

On some systems, some git commands may close standard input on startup, which will cause a "SIGPIPE" when trying to write to it. This will raise an exception.

"quiet"

Boolean option to control the output of warnings.

If true, methods such as "final_output()" will not warn when Git outputs messages on "STDERR".

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 "new()".

If several option hashes are passed to "new()", they will all be merged, keys in later hashes taking precedence over keys in earlier hashes.

The Git::Repository::Command object returned by "new()" has a number of attributes defined (see below).

close

    $cmd->close();

Close all pipes to the child process, and collects exit status, etc. and defines a number of attributes (see below).

final_output

    $cmd->final_output( @callbacks );

Collect all the output, and terminate the command.

Returns the output as a string in scalar context, or as a list of lines in list context. Also accepts a hashref of options.

Lines are automatically "chomp"ed.

If @callbacks is provided, the code references will be applied successively to each line of output. The line being processed is in $_, but the coderef must still return the result string.

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 "fatal" option, it will "die()". The defaults fatal exit codes are 128 (fatal error), and 129 (usage message).

Accessors

The object returned by "new()" will have the following attributes defined:

cmdline

Return the command-line actually executed, as a list of strings.

pid

The PID of the underlying git command.

stdin

A filehandle opened in write mode to the child process' standard input.

stdout

A filehandle opened in read mode to the child process' standard output.

stderr

A filehandle opened in read mode to the child process' standard error output.

Regarding the handles to the child git process, note that in the following code:

    my $fh = Git::Repository::Command->new( @cmd )->stdout;

$fh is opened and points to the output of the git subcommand, while the anonymous Git::Repository::Command object has been destroyed.

After the call to "close()", the following attributes will be defined:

exit

The exit status of the underlying git command.

core

A boolean value indicating if the command dumped core.

signal

The signal, if any, that killed the command.