1Git::Repository::CommanUds(e3r)Contributed Perl DocumentGaitti:o:nRepository::Command(3)
2
6 Git::Repository::Command - Command objects for running git
7
9 use Git::Repository::Command;
10 # invoke an external git command, and return an object
12 $cmd = Git::Repository::Command->new(@cmd);
13 # a Git::Repository object can provide more context
15 $cmd = Git::Repository::Command->new( $r, @cmd );
16 # options can be passed as a hashref
18 $cmd = Git::Repository::Command->new( $r, @cmd, \%option );
19 # $cmd is basically a hash, with keys / accessors
21 $cmd->stdin(); # filehandle to the process' stdin (write)
22 $cmd->stdout(); # filehandle to the process' stdout (read)
23 $cmd->stderr(); # filehandle to the process' stdout (read)
24 $cmd->pid(); # pid of the child process
25 # done!
27 $cmd->close();
28 # exit information
30 $cmd->exit(); # exit status
31 $cmd->signal(); # signal
32 $cmd->core(); # core dumped? (boolean)
33 # cut to the chase
35 my ( $pid, $in, $out, $err ) = Git::Repository::Command->spawn(@cmd);
36
38 Git::Repository::Command is a class that actually launches a git
39 commands, allowing to interact with it through its "STDIN", "STDOUT"
40 and "STDERR".
41 This class is a subclass of System::Command, meant to be invoked
43 through Git::Repository.
44
46 As a subclass of System::Command, Git::Repository::Command supports the
47 following methods:
48 new
50 Git::Repository::Command->new( @cmd );
51 Runs a git command with the parameters in @cmd.
53 If @cmd contains a Git::Repository object, it is used to provide
55 context to the git command.
56 If @cmd contains one or more hash reference, they are taken as option
58 hashes. The recognized keys are:
59 "git"
61 The actual git binary to run. By default, it is just "git".
62 In case the "git" to be run is actually a command with parameters
64 (e.g. when using sudo or another command executer), the option
65 value should be an array reference with the command and parameters,
66 like this:
67 { git => [qw( sudo -u nobody git )] }
69 "cwd"
71 The current working directory in which the git command will be run.
72 ("chdir()" will be called just before launching the command.)
73 If not provided, it will default to the root of the Git repository
75 work tree (if the repository is bare, then no "chdir()" will be
76 performed).
77 "env"
79 A hashref containing key / values to add to the git command
80 environment.
81 "fatal"
83 An arrayref containing a list of exit codes that will be considered
84 fatal by "final_output()".
85 Prepending the value with "-" will make it non-fatal, which can be
87 useful to override a default. The string "!0" can be used as a
88 shortcut for "[ 1 .. 255 ]".
89 If several option hashes have the "fatal" key, the lists of exit
91 codes will be combined, with the values provided last taking
92 precedence (when using a combination of positive / negative
93 values).
94 The generated list always contains 128 and 129; to make them non-
96 fatal, just add "-128" and "-129" to the list provided to the
97 "fatal" option.
98 "input"
100 A string that is send to the git command standard input, which is
101 then closed.
102 Using the empty string as "input" will close the git command
104 standard input without writing to it.
105 Using "undef" as "input" will not do anything. This behaviour
107 provides a way to modify options inherited from "new()" or a hash
108 populated by some other part of the program.
109 On some systems, some git commands may close standard input on
111 startup, which will cause a "SIGPIPE" when trying to write to it.
112 This will raise an exception.
113 "quiet"
115 Boolean option to control the output of warnings.
116 If true, methods such as "final_output()" will not warn when Git
118 outputs messages on "STDERR".
119 If the Git::Repository object has its own option hash, it will be used
121 to provide default values that can be overridden by the actual option
122 hash passed to "new()".
123 If several option hashes are passed to "new()", they will all be
125 merged, keys in later hashes taking precedence over keys in earlier
126 hashes.
127 The Git::Repository::Command object returned by "new()" has a number of
129 attributes defined (see below).
130 close
132 $cmd->close();
133 Close all pipes to the child process, and collects exit status, etc.
135 and defines a number of attributes (see below).
136 final_output
138 $cmd->final_output( @callbacks );
139 Collect all the output, and terminate the command.
141 Returns the output as a string in scalar context, or as a list of lines
143 in list context. Also accepts a hashref of options.
144 Lines are automatically "chomp"ed.
146 If @callbacks is provided, the code references will be applied
148 successively to each line of output. The line being processed is in $_,
149 but the coderef must still return the result string.
150 If the Git command printed anything on stderr, it will be printed as
152 warnings. If the git sub-process exited with a status code listed in
153 the "fatal" option, it will "die()". The defaults fatal exit codes are
154 128 (fatal error), and 129 (usage message).
155 Accessors
157 The attributes of a Git::Repository::Command object are also accessible
158 through a number of accessors.
159 The object returned by "new()" will have the following attributes
161 defined:
162 cmdline
164 Return the command-line actually executed, as a list of strings.
165 pid The PID of the underlying git command.
167 stdin
169 A filehandle opened in write mode to the child process' standard
170 input.
171 stdout
173 A filehandle opened in read mode to the child process' standard
174 output.
175 stderr
177 A filehandle opened in read mode to the child process' standard
178 error output.
179 Regarding the handles to the child git process, note that in the
181 following code:
182 my $fh = Git::Repository::Command->new( @cmd )->stdout;
184 $fh is opened and points to the output of the git subcommand, while the
186 anonymous Git::Repository::Command object has been destroyed.
187 After the call to "close()", the following attributes will be defined:
189 exit
191 The exit status of the underlying git command.
192 core
194 A boolean value indicating if the command dumped core.
195 signal
197 The signal, if any, that killed the command.
198
200 Philippe Bruhat (BooK) <book@cpan.org>
201
203 The core of Git::Repository::Command has been moved into its own
204 distribution: System::Command. Proper Win32 support is now delegated to
205 that module.
206 Before that, the Win32 implementation owed a lot to two people. First,
208 Olivier Raginel (BABAR), who provided me with a test platform with Git
209 and Strawberry Perl installed, which I could use at any time. Many
210 thanks go also to Chris Williams (BINGOS) for pointing me towards
211 perlmonks posts by ikegami that contained crucial elements to a working
212 MSWin32 implementation.
213 In the end, it was Christian Walder (MITHALDU) who helped me finalize
215 Win32 support for System::Command through a quick round of edit (on my
216 Linux box) and testing (on his Windows box) during the Perl QA
217 Hackathon 2013 in Lancaster.
218
220 Copyright 2010-2016 Philippe Bruhat (BooK), all rights reserved.
221
223 This program is free software; you can redistribute it and/or modify it
224 under the same terms as Perl itself.
225perl v5.32.1 2021-01-30 Git::Repository::Command(3)