NAME¶
Git::Repository::Command - Command objects for running git
SYNOPSIS¶
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, \%option );
# $cmd is basically a hash, with keys / accessors
$cmd->stdin(); # filehandle to the process' stdin (write)
$cmd->stdout(); # filehandle to the process' stdout (read)
$cmd->stderr(); # filehandle to the process' 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);
DESCRIPTION¶
"Git::Repository::Command" is a class that actually launches a
git commands, allowing to interact with it through its
"STDIN", "STDOUT" and "STDERR".
This class is a subclass of "System::Command", meant to be invoked
through "Git::Repository".
METHODS¶
As a subclass of "System::Command",
"Git::Repository::Command" supports the following methods:
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.
- "env"
- A hashref containing key / values to add to the git command
environment.
- "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.
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()¶
Close all pipes to the child process, and collects exit status, etc. and defines
a number of attributes (see below).
final_output()¶
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 the Git command printed anything on stderr, it will be printed as warnings.
If the git sub-process exited with status 128 (fatal error), or 129 (usage
message), it will "die()".
Accessors¶
The attributes of a "Git::Repository::Command" object are also
accessible through a number of 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. Once
$fh is destroyed, the subprocess will be reaped, thus avoiding zombies.
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.
AUTHOR¶
Philippe Bruhat (BooK), "<book at cpan.org>"
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.
Before that, the Win32 implementation owed a lot to two people. First, Olivier
Raginel (BABAR), 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 (BINGOS) for pointing me towards perlmonks posts by ikegami that
contained crucial elements to a working MSWin32 implementation.
COPYRIGHT¶
Copyright 2010-2011 Philippe Bruhat (BooK), all rights reserved.
LICENSE¶
This program is free software; you can redistribute it and/or modify it under
the same terms as Perl itself.