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 "fatal"
97 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 merged,
125 keys in later hashes taking precedence over keys in earlier hashes.
126 The Git::Repository::Command object returned by new() has a number of
128 attributes defined (see below).
129 close
131 $cmd->close();
132 Close all pipes to the child process, and collects exit status, etc.
134 and defines a number of attributes (see below).
135 final_output
137 $cmd->final_output( @callbacks );
138 Collect all the output, and terminate the command.
140 Returns the output as a string in scalar context, or as a list of lines
142 in list context. Also accepts a hashref of options.
143 Lines are automatically "chomp"ed.
145 If @callbacks is provided, the code references will be applied
147 successively to each line of output. The line being processed is in $_,
148 but the coderef must still return the result string.
149 If the Git command printed anything on stderr, it will be printed as
151 warnings. If the git sub-process exited with a status code listed in
152 the "fatal" option, it will die(). The defaults fatal exit codes are
153 128 (fatal error), and 129 (usage message).
154 Accessors
156 The attributes of a Git::Repository::Command object are also accessible
157 through a number of accessors.
158 The object returned by new() will have the following attributes
160 defined:
161 cmdline
163 Return the command-line actually executed, as a list of strings.
164 pid The PID of the underlying git command.
166 stdin
168 A filehandle opened in write mode to the child process' standard
169 input.
170 stdout
172 A filehandle opened in read mode to the child process' standard
173 output.
174 stderr
176 A filehandle opened in read mode to the child process' standard
177 error output.
178 Regarding the handles to the child git process, note that in the
180 following code:
181 my $fh = Git::Repository::Command->new( @cmd )->stdout;
183 $fh is opened and points to the output of the git subcommand, while the
185 anonymous Git::Repository::Command object has been destroyed.
186 After the call to close(), the following attributes will be defined:
188 exit
190 The exit status of the underlying git command.
191 core
193 A boolean value indicating if the command dumped core.
194 signal
196 The signal, if any, that killed the command.
197
199 Philippe Bruhat (BooK) <book@cpan.org>
200
202 The core of Git::Repository::Command has been moved into its own
203 distribution: System::Command. Proper Win32 support is now delegated to
204 that module.
205 Before that, the Win32 implementation owed a lot to two people. First,
207 Olivier Raginel (BABAR), who provided me with a test platform with Git
208 and Strawberry Perl installed, which I could use at any time. Many
209 thanks go also to Chris Williams (BINGOS) for pointing me towards
210 perlmonks posts by ikegami that contained crucial elements to a working
211 MSWin32 implementation.
212 In the end, it was Christian Walder (MITHALDU) who helped me finalize
214 Win32 support for System::Command through a quick round of edit (on my
215 Linux box) and testing (on his Windows box) during the Perl QA
216 Hackathon 2013 in Lancaster.
217
219 Copyright 2010-2016 Philippe Bruhat (BooK), all rights reserved.
220
222 This program is free software; you can redistribute it and/or modify it
223 under the same terms as Perl itself.
224perl v5.36.0 2023-01-20 Git::Repository::Command(3)