--- name: "Git::Repository::Command" section: "3pm" platform: "linux" package: "libgit-repository-perl" version: "1.325-3" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/Git::Repository::Command" --- # Git::Repository::Command(3pm) Command objects for running git ## 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 ``` 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 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. 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) \ ## 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. In the end, it was Christian Walder (MITHALDU) 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 QA Hackathon 2013 in Lancaster. ## COPYRIGHT Copyright 2010-2016 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.