1Git(3) User Contributed Perl Documentation Git(3)
2
6 Git - Perl interface to the Git version control system
7
9 use Git;
10 my $version = Git::command_oneline('version');
12 git_cmd_try { Git::command_noisy('update-server-info') }
14 '%s failed w/ code %d';
15 my $repo = Git->repository (Directory => '/srv/git/cogito.git');
17 my @revs = $repo->command('rev-list', '--since=last monday', '--all');
20 my ($fh, $c) = $repo->command_output_pipe('rev-list', '--since=last monday', '--all');
22 my $lastrev = <$fh>; chomp $lastrev;
23 $repo->command_close_pipe($fh, $c);
24 my $lastrev = $repo->command_oneline( [ 'rev-list', '--all' ],
26 STDERR => 0 );
27 my $sha1 = $repo->hash_and_insert_object('file.txt');
29 my $tempfile = tempfile();
30 my $size = $repo->cat_blob($sha1, $tempfile);
31
33 This module provides Perl scripts easy way to interface the Git version
34 control system. The modules have an easy and well-tested way to call
35 arbitrary Git commands; in the future, the interface will also provide
36 specialized methods for doing easily operations which are not totally
37 trivial to do over the generic command interface.
38 While some commands can be executed outside of any context (e.g.
40 'version' or 'init'), most operations require a repository context,
41 which in practice means getting an instance of the Git object using the
42 repository() constructor. (In the future, we will also get a
43 new_repository() constructor.) All commands called as methods of the
44 object are then executed in the context of the repository.
45 Part of the "repository state" is also information about path to the
47 attached working copy (unless you work with a bare repository). You can
48 also navigate inside of the working copy using the "wc_chdir()" method.
49 (Note that the repository object is self-contained and will not change
50 working directory of your process.)
51 TODO: In the future, we might also do
53 my $remoterepo = $repo->remote_repository (Name => 'cogito', Branch => 'master');
55 $remoterepo ||= Git->remote_repository ('http://git.or.cz/cogito.git/');
56 my @refs = $remoterepo->refs();
57 Currently, the module merely wraps calls to external Git tools. In the
59 future, it will provide a much faster way to interact with Git by
60 linking directly to libgit. This should be completely opaque to the
61 user, though (performance increase notwithstanding).
62
64 repository ( OPTIONS )
65 repository ( DIRECTORY )
66 repository ()
67 Construct a new repository object. "OPTIONS" are passed in a hash
68 like fashion, using key and value pairs. Possible options are:
69 Repository - Path to the Git repository.
71 WorkingCopy - Path to the associated working copy; not strictly
73 required as many commands will happily crunch on a bare repository.
74 WorkingSubdir - Subdirectory in the working copy to work inside.
76 Just left undefined if you do not want to limit the scope of
77 operations.
78 Directory - Path to the Git working directory in its usual setup.
80 The ".git" directory is searched in the directory and all the
81 parent directories; if found, "WorkingCopy" is set to the directory
82 containing it and "Repository" to the ".git" directory itself. If
83 no ".git" directory was found, the "Directory" is assumed to be a
84 bare repository, "Repository" is set to point at it and
85 "WorkingCopy" is left undefined. If the $GIT_DIR environment
86 variable is set, things behave as expected as well.
87 You should not use both "Directory" and either of "Repository" and
89 "WorkingCopy" - the results of that are undefined.
90 Alternatively, a directory path may be passed as a single scalar
92 argument to the constructor; it is equivalent to setting only the
93 "Directory" option field.
94 Calling the constructor with no options whatsoever is equivalent to
96 calling it with "Directory => '.'". In general, if you are building
97 a standard porcelain command, simply doing "Git->repository()"
98 should do the right thing and setup the object to reflect exactly
99 where the user is right now.
100
102 command ( COMMAND [, ARGUMENTS... ] )
103 command ( [ COMMAND, ARGUMENTS... ], { Opt => Val ... } )
104 Execute the given Git "COMMAND" (specify it without the 'git-'
105 prefix), optionally with the specified extra "ARGUMENTS".
106 The second more elaborate form can be used if you want to further
108 adjust the command execution. Currently, only one option is
109 supported:
110 STDERR - How to deal with the command's error output. By default
112 ("undef") it is delivered to the caller's "STDERR". A false value
113 (0 or '') will cause it to be thrown away. If you want to process
114 it, you can get it in a filehandle you specify, but you must be
115 extremely careful; if the error output is not very short and you
116 want to read it in the same process as where you called
117 "command()", you are set up for a nice deadlock!
118 The method can be called without any instance or on a specified Git
120 repository (in that case the command will be run in the repository
121 context).
122 In scalar context, it returns all the command output in a single
124 string (verbatim).
125 In array context, it returns an array containing lines printed to
127 the command's stdout (without trailing newlines).
128 In both cases, the command's stdin and stderr are the same as the
130 caller's.
131 command_oneline ( COMMAND [, ARGUMENTS... ] )
133 command_oneline ( [ COMMAND, ARGUMENTS... ], { Opt => Val ... } )
134 Execute the given "COMMAND" in the same way as command() does but
135 always return a scalar string containing the first line of the
136 command's standard output.
137 command_output_pipe ( COMMAND [, ARGUMENTS... ] )
139 command_output_pipe ( [ COMMAND, ARGUMENTS... ], { Opt => Val ... } )
140 Execute the given "COMMAND" in the same way as command() does but
141 return a pipe filehandle from which the command output can be read.
142 The function can return "($pipe, $ctx)" in array context. See
144 "command_close_pipe()" for details.
145 command_input_pipe ( COMMAND [, ARGUMENTS... ] )
147 command_input_pipe ( [ COMMAND, ARGUMENTS... ], { Opt => Val ... } )
148 Execute the given "COMMAND" in the same way as
149 command_output_pipe() does but return an input pipe filehandle
150 instead; the command output is not captured.
151 The function can return "($pipe, $ctx)" in array context. See
153 "command_close_pipe()" for details.
154 command_close_pipe ( PIPE [, CTX ] )
156 Close the "PIPE" as returned from "command_*_pipe()", checking
157 whether the command finished successfully. The optional "CTX"
158 argument is required if you want to see the command name in the
159 error message, and it is the second value returned by
160 "command_*_pipe()" when called in array context. The call idiom is:
161 my ($fh, $ctx) = $r->command_output_pipe('status');
163 while (<$fh>) { ... }
164 $r->command_close_pipe($fh, $ctx);
165 Note that you should not rely on whatever actually is in "CTX";
167 currently it is simply the command name but in future the context
168 might have more complicated structure.
169 command_bidi_pipe ( COMMAND [, ARGUMENTS... ] )
171 Execute the given "COMMAND" in the same way as
172 command_output_pipe() does but return both an input pipe filehandle
173 and an output pipe filehandle.
174 The function will return return "($pid, $pipe_in, $pipe_out,
176 $ctx)". See "command_close_bidi_pipe()" for details.
177 command_close_bidi_pipe ( PID, PIPE_IN, PIPE_OUT [, CTX] )
179 Close the "PIPE_IN" and "PIPE_OUT" as returned from
180 "command_bidi_pipe()", checking whether the command finished
181 successfully. The optional "CTX" argument is required if you want
182 to see the command name in the error message, and it is the fourth
183 value returned by "command_bidi_pipe()". The call idiom is:
184 my ($pid, $in, $out, $ctx) = $r->command_bidi_pipe('cat-file --batch-check');
186 print "000000000\n" $out;
187 while (<$in>) { ... }
188 $r->command_close_bidi_pipe($pid, $in, $out, $ctx);
189 Note that you should not rely on whatever actually is in "CTX";
191 currently it is simply the command name but in future the context
192 might have more complicated structure.
193 command_noisy ( COMMAND [, ARGUMENTS... ] )
195 Execute the given "COMMAND" in the same way as command() does but
196 do not capture the command output - the standard output is not
197 redirected and goes to the standard output of the caller
198 application.
199 While the method is called command_noisy(), you might want to as
201 well use it for the most silent Git commands which you know will
202 never pollute your stdout but you want to avoid the overhead of the
203 pipe setup when calling them.
204 The function returns only after the command has finished running.
206 version ()
208 Return the Git version in use.
209 exec_path ()
211 Return path to the Git sub-command executables (the same as "git
212 --exec-path"). Useful mostly only internally.
213 html_path ()
215 Return path to the Git html documentation (the same as "git
216 --html-path"). Useful mostly only internally.
217 repo_path ()
219 Return path to the git repository. Must be called on a repository
220 instance.
221 wc_path ()
223 Return path to the working copy. Must be called on a repository
224 instance.
225 wc_subdir ()
227 Return path to the subdirectory inside of a working copy. Must be
228 called on a repository instance.
229 wc_chdir ( SUBDIR )
231 Change the working copy subdirectory to work within. The "SUBDIR"
232 is relative to the working copy root directory (not the current
233 subdirectory). Must be called on a repository instance attached to
234 a working copy and the directory must exist.
235 config ( VARIABLE )
237 Retrieve the configuration "VARIABLE" in the same manner as
238 "config" does. In scalar context requires the variable to be set
239 only one time (exception is thrown otherwise), in array context
240 returns allows the variable to be set multiple times and returns
241 all the values.
242 This currently wraps command('config') so it is not so fast.
244 config_bool ( VARIABLE )
246 Retrieve the bool configuration "VARIABLE". The return value is
247 usable as a boolean in perl (and "undef" if it's not defined, of
248 course).
249 This currently wraps command('config') so it is not so fast.
251 config_int ( VARIABLE )
253 Retrieve the integer configuration "VARIABLE". The return value is
254 simple decimal number. An optional value suffix of 'k', 'm', or
255 'g' in the config file will cause the value to be multiplied by
256 1024, 1048576 (1024^2), or 1073741824 (1024^3) prior to output. It
257 would return "undef" if configuration variable is not defined,
258 This currently wraps command('config') so it is not so fast.
260 get_colorbool ( NAME )
262 Finds if color should be used for NAMEd operation from the
263 configuration, and returns boolean (true for "use color", false for
264 "do not use color").
265 get_color ( SLOT, COLOR )
267 Finds color for SLOT from the configuration, while defaulting to
268 COLOR, and returns the ANSI color escape sequence:
269 print $repo->get_color("color.interactive.prompt", "underline blue white");
271 print "some text";
272 print $repo->get_color("", "normal");
273 remote_refs ( REPOSITORY [, GROUPS [, REFGLOBS ] ] )
275 This function returns a hashref of refs stored in a given remote
276 repository. The hash is in the format "refname =\" hash>. For
277 tags, the "refname" entry contains the tag object while a
278 "refname^{}" entry gives the tagged objects.
279 "REPOSITORY" has the same meaning as the appropriate
281 "git-ls-remote" argument; either an URL or a remote name (if called
282 on a repository instance). "GROUPS" is an optional arrayref that
283 can contain 'tags' to return all the tags and/or 'heads' to return
284 all the heads. "REFGLOB" is an optional array of strings containing
285 a shell-like glob to further limit the refs returned in the hash;
286 the meaning is again the same as the appropriate "git-ls-remote"
287 argument.
288 This function may or may not be called on a repository instance. In
290 the former case, remote names as defined in the repository are
291 recognized as repository specifiers.
292 ident ( TYPE | IDENTSTR )
294 ident_person ( TYPE | IDENTSTR | IDENTARRAY )
295 This suite of functions retrieves and parses ident information, as
296 stored in the commit and tag objects or produced by "var
297 GIT_type_IDENT" (thus "TYPE" can be either author or committer;
298 case is insignificant).
299 The "ident" method retrieves the ident information from "git var"
301 and either returns it as a scalar string or as an array with the
302 fields parsed. Alternatively, it can take a prepared ident string
303 (e.g. from the commit object) and just parse it.
304 "ident_person" returns the person part of the ident - name and
306 email; it can take the same arguments as "ident" or the array
307 returned by "ident".
308 The synopsis is like:
310 my ($name, $email, $time_tz) = ident('author');
312 "$name <$email>" eq ident_person('author');
313 "$name <$email>" eq ident_person($name);
314 $time_tz =~ /^\d+ [+-]\d{4}$/;
315 hash_object ( TYPE, FILENAME )
317 Compute the SHA1 object id of the given "FILENAME" considering it
318 is of the "TYPE" object type ("blob", "commit", "tree").
319 The method can be called without any instance or on a specified Git
321 repository, it makes zero difference.
322 The function returns the SHA1 hash.
324 hash_and_insert_object ( FILENAME )
326 Compute the SHA1 object id of the given "FILENAME" and add the
327 object to the object database.
328 The function returns the SHA1 hash.
330 cat_blob ( SHA1, FILEHANDLE )
332 Prints the contents of the blob identified by "SHA1" to
333 "FILEHANDLE" and returns the number of bytes printed.
334 temp_acquire ( NAME )
336 Attempts to retreive the temporary file mapped to the string
337 "NAME". If an associated temp file has not been created this
338 session or was closed, it is created, cached, and set for autoflush
339 and binmode.
340 Internally locks the file mapped to "NAME". This lock must be
342 released with "temp_release()" when the temp file is no longer
343 needed. Subsequent attempts to retrieve temporary files mapped to
344 the same "NAME" while still locked will cause an error. This
345 locking mechanism provides a weak guarantee and is not threadsafe.
346 It does provide some error checking to help prevent temp file refs
347 writing over one another.
348 In general, the File::Handle returned should not be closed by
350 consumers as it defeats the purpose of this caching mechanism. If
351 you need to close the temp file handle, then you should use
352 File::Temp or another temp file faculty directly. If a handle is
353 closed and then requested again, then a warning will issue.
354 temp_release ( NAME )
356 temp_release ( FILEHANDLE )
357 Releases a lock acquired through "temp_acquire()". Can be called
358 either with the "NAME" mapping used when acquiring the temp file or
359 with the "FILEHANDLE" referencing a locked temp file.
360 Warns if an attempt is made to release a file that is not locked.
362 The temp file will be truncated before being released. This can
364 help to reduce disk I/O where the system is smart enough to detect
365 the truncation while data is in the output buffers. Beware that
366 after the temp file is released and truncated, any operations on
367 that file may fail miserably until it is re-acquired. All contents
368 are lost between each release and acquire mapped to the same
369 string.
370 temp_reset ( FILEHANDLE )
372 Truncates and resets the position of the "FILEHANDLE".
373 temp_path ( NAME )
375 temp_path ( FILEHANDLE )
376 Returns the filename associated with the given tempfile.
377
379 All functions are supposed to throw Perl exceptions in case of errors.
380 See the Error module on how to catch those. Most exceptions are mere
381 Error::Simple instances.
382 However, the "command()", "command_oneline()" and "command_noisy()"
384 functions suite can throw "Git::Error::Command" exceptions as well:
385 those are thrown when the external command returns an error code and
386 contain the error code as well as access to the captured command's
387 output. The exception class provides the usual "stringify" and "value"
388 (command's exit code) methods and in addition also a "cmd_output"
389 method that returns either an array or a string with the captured
390 command output (depending on the original function call context;
391 "command_noisy()" returns "undef") and $<cmdline> which returns the
392 command and its arguments (but without proper quoting).
393 Note that the "command_*_pipe()" functions cannot throw this exception
395 since it has no idea whether the command failed or not. You will only
396 find out at the time you "close" the pipe; if you want to have that
397 automated, use "command_close_pipe()", which can throw the exception.
398 git_cmd_try { CODE } ERRMSG
400 This magical statement will automatically catch any
401 "Git::Error::Command" exceptions thrown by "CODE" and make your
402 program die with "ERRMSG" on its lips; the message will have %s
403 substituted for the command line and %d for the exit status. This
404 statement is useful mostly for producing more user-friendly error
405 messages.
406 In case of no exception caught the statement returns "CODE"'s
408 return value.
409 Note that this is the only auto-exported function.
411
413 Copyright 2006 by Petr Baudis <pasky@suse.cz>.
414 This module is free software; it may be used, copied, modified and
416 distributed under the terms of the GNU General Public Licence, either
417 version 2, or (at your option) any later version.
418perl v5.12.3 2011-04-06 Git(3)