tgupdate: merge girocco base into girocco
[git/gitweb.git] / perl / Git.pm
blobb2732822af0f34c6f7731df8a1a017d19f3e0508
1 =head1 NAME
3 Git - Perl interface to the Git version control system
5 =cut
8 package Git;
10 use 5.008;
11 use strict;
14 BEGIN {
16 our ($VERSION, @ISA, @EXPORT, @EXPORT_OK);
18 # Totally unstable API.
19 $VERSION = '0.01';
22 =head1 SYNOPSIS
24 use Git;
26 my $version = Git::command_oneline('version');
28 git_cmd_try { Git::command_noisy('update-server-info') }
29 '%s failed w/ code %d';
31 my $repo = Git->repository (Directory => '/srv/git/cogito.git');
34 my @revs = $repo->command('rev-list', '--since=last monday', '--all');
36 my ($fh, $c) = $repo->command_output_pipe('rev-list', '--since=last monday', '--all');
37 my $lastrev = <$fh>; chomp $lastrev;
38 $repo->command_close_pipe($fh, $c);
40 my $lastrev = $repo->command_oneline( [ 'rev-list', '--all' ],
41 STDERR => 0 );
43 my $sha1 = $repo->hash_and_insert_object('file.txt');
44 my $tempfile = tempfile();
45 my $size = $repo->cat_blob($sha1, $tempfile);
47 =cut
50 require Exporter;
52 @ISA = qw(Exporter);
54 @EXPORT = qw(git_cmd_try);
56 # Methods which can be called as standalone functions as well:
57 @EXPORT_OK = qw(command command_oneline command_noisy
58 command_output_pipe command_input_pipe command_close_pipe
59 command_bidi_pipe command_close_bidi_pipe
60 version exec_path html_path hash_object git_cmd_try
61 remote_refs prompt
62 get_tz_offset get_record
63 credential credential_read credential_write
64 temp_acquire temp_is_locked temp_release temp_reset temp_path);
67 =head1 DESCRIPTION
69 This module provides Perl scripts easy way to interface the Git version control
70 system. The modules have an easy and well-tested way to call arbitrary Git
71 commands; in the future, the interface will also provide specialized methods
72 for doing easily operations which are not totally trivial to do over
73 the generic command interface.
75 While some commands can be executed outside of any context (e.g. 'version'
76 or 'init'), most operations require a repository context, which in practice
77 means getting an instance of the Git object using the repository() constructor.
78 (In the future, we will also get a new_repository() constructor.) All commands
79 called as methods of the object are then executed in the context of the
80 repository.
82 Part of the "repository state" is also information about path to the attached
83 working copy (unless you work with a bare repository). You can also navigate
84 inside of the working copy using the C<wc_chdir()> method. (Note that
85 the repository object is self-contained and will not change working directory
86 of your process.)
88 TODO: In the future, we might also do
90 my $remoterepo = $repo->remote_repository (Name => 'cogito', Branch => 'master');
91 $remoterepo ||= Git->remote_repository ('http://git.or.cz/cogito.git/');
92 my @refs = $remoterepo->refs();
94 Currently, the module merely wraps calls to external Git tools. In the future,
95 it will provide a much faster way to interact with Git by linking directly
96 to libgit. This should be completely opaque to the user, though (performance
97 increase notwithstanding).
99 =cut
102 use Carp qw(carp croak); # but croak is bad - throw instead
103 use Error qw(:try);
104 use Cwd qw(abs_path cwd);
105 use IPC::Open2 qw(open2);
106 use Fcntl qw(SEEK_SET SEEK_CUR);
107 use Time::Local qw(timegm);
111 =head1 CONSTRUCTORS
113 =over 4
115 =item repository ( OPTIONS )
117 =item repository ( DIRECTORY )
119 =item repository ()
121 Construct a new repository object.
122 C<OPTIONS> are passed in a hash like fashion, using key and value pairs.
123 Possible options are:
125 B<Repository> - Path to the Git repository.
127 B<WorkingCopy> - Path to the associated working copy; not strictly required
128 as many commands will happily crunch on a bare repository.
130 B<WorkingSubdir> - Subdirectory in the working copy to work inside.
131 Just left undefined if you do not want to limit the scope of operations.
133 B<Directory> - Path to the Git working directory in its usual setup.
134 The C<.git> directory is searched in the directory and all the parent
135 directories; if found, C<WorkingCopy> is set to the directory containing
136 it and C<Repository> to the C<.git> directory itself. If no C<.git>
137 directory was found, the C<Directory> is assumed to be a bare repository,
138 C<Repository> is set to point at it and C<WorkingCopy> is left undefined.
139 If the C<$GIT_DIR> environment variable is set, things behave as expected
140 as well.
142 You should not use both C<Directory> and either of C<Repository> and
143 C<WorkingCopy> - the results of that are undefined.
145 Alternatively, a directory path may be passed as a single scalar argument
146 to the constructor; it is equivalent to setting only the C<Directory> option
147 field.
149 Calling the constructor with no options whatsoever is equivalent to
150 calling it with C<< Directory => '.' >>. In general, if you are building
151 a standard porcelain command, simply doing C<< Git->repository() >> should
152 do the right thing and setup the object to reflect exactly where the user
153 is right now.
155 =cut
157 sub repository {
158 my $class = shift;
159 my @args = @_;
160 my %opts = ();
161 my $self;
163 if (defined $args[0]) {
164 if ($#args % 2 != 1) {
165 # Not a hash.
166 $#args == 0 or throw Error::Simple("bad usage");
167 %opts = ( Directory => $args[0] );
168 } else {
169 %opts = @args;
173 if (not defined $opts{Repository} and not defined $opts{WorkingCopy}
174 and not defined $opts{Directory}) {
175 $opts{Directory} = '.';
178 if (defined $opts{Directory}) {
179 -d $opts{Directory} or throw Error::Simple("Directory not found: $opts{Directory} $!");
181 my $search = Git->repository(WorkingCopy => $opts{Directory});
182 my $dir;
183 try {
184 $dir = $search->command_oneline(['rev-parse', '--git-dir'],
185 STDERR => 0);
186 } catch Git::Error::Command with {
187 $dir = undef;
190 if ($dir) {
191 _verify_require();
192 File::Spec->file_name_is_absolute($dir) or $dir = $opts{Directory} . '/' . $dir;
193 $opts{Repository} = abs_path($dir);
195 # If --git-dir went ok, this shouldn't die either.
196 my $prefix = $search->command_oneline('rev-parse', '--show-prefix');
197 $dir = abs_path($opts{Directory}) . '/';
198 if ($prefix) {
199 if (substr($dir, -length($prefix)) ne $prefix) {
200 throw Error::Simple("rev-parse confused me - $dir does not have trailing $prefix");
202 substr($dir, -length($prefix)) = '';
204 $opts{WorkingCopy} = $dir;
205 $opts{WorkingSubdir} = $prefix;
207 } else {
208 # A bare repository? Let's see...
209 $dir = $opts{Directory};
211 unless (-d "$dir/refs" and -d "$dir/objects" and -e "$dir/HEAD") {
212 # Mimic git-rev-parse --git-dir error message:
213 throw Error::Simple("fatal: Not a git repository: $dir");
215 my $search = Git->repository(Repository => $dir);
216 try {
217 $search->command('symbolic-ref', 'HEAD');
218 } catch Git::Error::Command with {
219 # Mimic git-rev-parse --git-dir error message:
220 throw Error::Simple("fatal: Not a git repository: $dir");
223 $opts{Repository} = abs_path($dir);
226 delete $opts{Directory};
229 $self = { opts => \%opts };
230 bless $self, $class;
233 =back
235 =head1 METHODS
237 =over 4
239 =item command ( COMMAND [, ARGUMENTS... ] )
241 =item command ( [ COMMAND, ARGUMENTS... ], { Opt => Val ... } )
243 Execute the given Git C<COMMAND> (specify it without the 'git-'
244 prefix), optionally with the specified extra C<ARGUMENTS>.
246 The second more elaborate form can be used if you want to further adjust
247 the command execution. Currently, only one option is supported:
249 B<STDERR> - How to deal with the command's error output. By default (C<undef>)
250 it is delivered to the caller's C<STDERR>. A false value (0 or '') will cause
251 it to be thrown away. If you want to process it, you can get it in a filehandle
252 you specify, but you must be extremely careful; if the error output is not
253 very short and you want to read it in the same process as where you called
254 C<command()>, you are set up for a nice deadlock!
256 The method can be called without any instance or on a specified Git repository
257 (in that case the command will be run in the repository context).
259 In scalar context, it returns all the command output in a single string
260 (verbatim).
262 In array context, it returns an array containing lines printed to the
263 command's stdout (without trailing newlines).
265 In both cases, the command's stdin and stderr are the same as the caller's.
267 =cut
269 sub command {
270 my ($fh, $ctx) = command_output_pipe(@_);
272 if (not defined wantarray) {
273 # Nothing to pepper the possible exception with.
274 _cmd_close($ctx, $fh);
276 } elsif (not wantarray) {
277 local $/;
278 my $text = <$fh>;
279 try {
280 _cmd_close($ctx, $fh);
281 } catch Git::Error::Command with {
282 # Pepper with the output:
283 my $E = shift;
284 $E->{'-outputref'} = \$text;
285 throw $E;
287 return $text;
289 } else {
290 my @lines = <$fh>;
291 defined and chomp for @lines;
292 try {
293 _cmd_close($ctx, $fh);
294 } catch Git::Error::Command with {
295 my $E = shift;
296 $E->{'-outputref'} = \@lines;
297 throw $E;
299 return @lines;
304 =item command_oneline ( COMMAND [, ARGUMENTS... ] )
306 =item command_oneline ( [ COMMAND, ARGUMENTS... ], { Opt => Val ... } )
308 Execute the given C<COMMAND> in the same way as command()
309 does but always return a scalar string containing the first line
310 of the command's standard output.
312 =cut
314 sub command_oneline {
315 my ($fh, $ctx) = command_output_pipe(@_);
317 my $line = <$fh>;
318 defined $line and chomp $line;
319 try {
320 _cmd_close($ctx, $fh);
321 } catch Git::Error::Command with {
322 # Pepper with the output:
323 my $E = shift;
324 $E->{'-outputref'} = \$line;
325 throw $E;
327 return $line;
331 =item command_output_pipe ( COMMAND [, ARGUMENTS... ] )
333 =item command_output_pipe ( [ COMMAND, ARGUMENTS... ], { Opt => Val ... } )
335 Execute the given C<COMMAND> in the same way as command()
336 does but return a pipe filehandle from which the command output can be
337 read.
339 The function can return C<($pipe, $ctx)> in array context.
340 See C<command_close_pipe()> for details.
342 =cut
344 sub command_output_pipe {
345 _command_common_pipe('-|', @_);
349 =item command_input_pipe ( COMMAND [, ARGUMENTS... ] )
351 =item command_input_pipe ( [ COMMAND, ARGUMENTS... ], { Opt => Val ... } )
353 Execute the given C<COMMAND> in the same way as command_output_pipe()
354 does but return an input pipe filehandle instead; the command output
355 is not captured.
357 The function can return C<($pipe, $ctx)> in array context.
358 See C<command_close_pipe()> for details.
360 =cut
362 sub command_input_pipe {
363 _command_common_pipe('|-', @_);
367 =item command_close_pipe ( PIPE [, CTX ] )
369 Close the C<PIPE> as returned from C<command_*_pipe()>, checking
370 whether the command finished successfully. The optional C<CTX> argument
371 is required if you want to see the command name in the error message,
372 and it is the second value returned by C<command_*_pipe()> when
373 called in array context. The call idiom is:
375 my ($fh, $ctx) = $r->command_output_pipe('status');
376 while (<$fh>) { ... }
377 $r->command_close_pipe($fh, $ctx);
379 Note that you should not rely on whatever actually is in C<CTX>;
380 currently it is simply the command name but in future the context might
381 have more complicated structure.
383 =cut
385 sub command_close_pipe {
386 my ($self, $fh, $ctx) = _maybe_self(@_);
387 $ctx ||= '<unknown>';
388 _cmd_close($ctx, $fh);
391 =item command_bidi_pipe ( COMMAND [, ARGUMENTS... ] )
393 Execute the given C<COMMAND> in the same way as command_output_pipe()
394 does but return both an input pipe filehandle and an output pipe filehandle.
396 The function will return C<($pid, $pipe_in, $pipe_out, $ctx)>.
397 See C<command_close_bidi_pipe()> for details.
399 =cut
401 sub command_bidi_pipe {
402 my ($pid, $in, $out);
403 my ($self) = _maybe_self(@_);
404 local %ENV = %ENV;
405 my $cwd_save = undef;
406 if ($self) {
407 shift;
408 $cwd_save = cwd();
409 _setup_git_cmd_env($self);
411 $pid = open2($in, $out, 'git', @_);
412 chdir($cwd_save) if $cwd_save;
413 return ($pid, $in, $out, join(' ', @_));
416 =item command_close_bidi_pipe ( PID, PIPE_IN, PIPE_OUT [, CTX] )
418 Close the C<PIPE_IN> and C<PIPE_OUT> as returned from C<command_bidi_pipe()>,
419 checking whether the command finished successfully. The optional C<CTX>
420 argument is required if you want to see the command name in the error message,
421 and it is the fourth value returned by C<command_bidi_pipe()>. The call idiom
424 my ($pid, $in, $out, $ctx) = $r->command_bidi_pipe('cat-file --batch-check');
425 print $out "000000000\n";
426 while (<$in>) { ... }
427 $r->command_close_bidi_pipe($pid, $in, $out, $ctx);
429 Note that you should not rely on whatever actually is in C<CTX>;
430 currently it is simply the command name but in future the context might
431 have more complicated structure.
433 C<PIPE_IN> and C<PIPE_OUT> may be C<undef> if they have been closed prior to
434 calling this function. This may be useful in a query-response type of
435 commands where caller first writes a query and later reads response, eg:
437 my ($pid, $in, $out, $ctx) = $r->command_bidi_pipe('cat-file --batch-check');
438 print $out "000000000\n";
439 close $out;
440 while (<$in>) { ... }
441 $r->command_close_bidi_pipe($pid, $in, undef, $ctx);
443 This idiom may prevent potential dead locks caused by data sent to the output
444 pipe not being flushed and thus not reaching the executed command.
446 =cut
448 sub command_close_bidi_pipe {
449 local $?;
450 my ($self, $pid, $in, $out, $ctx) = _maybe_self(@_);
451 _cmd_close($ctx, (grep { defined } ($in, $out)));
452 waitpid $pid, 0;
453 if ($? >> 8) {
454 throw Git::Error::Command($ctx, $? >>8);
459 =item command_noisy ( COMMAND [, ARGUMENTS... ] )
461 Execute the given C<COMMAND> in the same way as command() does but do not
462 capture the command output - the standard output is not redirected and goes
463 to the standard output of the caller application.
465 While the method is called command_noisy(), you might want to as well use
466 it for the most silent Git commands which you know will never pollute your
467 stdout but you want to avoid the overhead of the pipe setup when calling them.
469 The function returns only after the command has finished running.
471 =cut
473 sub command_noisy {
474 my ($self, $cmd, @args) = _maybe_self(@_);
475 _check_valid_cmd($cmd);
477 my $pid = fork;
478 if (not defined $pid) {
479 throw Error::Simple("fork failed: $!");
480 } elsif ($pid == 0) {
481 _cmd_exec($self, $cmd, @args);
483 if (waitpid($pid, 0) > 0 and $?>>8 != 0) {
484 throw Git::Error::Command(join(' ', $cmd, @args), $? >> 8);
489 =item version ()
491 Return the Git version in use.
493 =cut
495 sub version {
496 my $verstr = command_oneline('--version');
497 $verstr =~ s/^git version //;
498 $verstr;
502 =item exec_path ()
504 Return path to the Git sub-command executables (the same as
505 C<git --exec-path>). Useful mostly only internally.
507 =cut
509 sub exec_path { command_oneline('--exec-path') }
512 =item html_path ()
514 Return path to the Git html documentation (the same as
515 C<git --html-path>). Useful mostly only internally.
517 =cut
519 sub html_path { command_oneline('--html-path') }
522 =item get_tz_offset ( TIME )
524 Return the time zone offset from GMT in the form +/-HHMM where HH is
525 the number of hours from GMT and MM is the number of minutes. This is
526 the equivalent of what strftime("%z", ...) would provide on a GNU
527 platform.
529 If TIME is not supplied, the current local time is used.
531 =cut
533 sub get_tz_offset {
534 # some systmes don't handle or mishandle %z, so be creative.
535 my $t = shift || time;
536 my $gm = timegm(localtime($t));
537 my $sign = qw( + + - )[ $gm <=> $t ];
538 return sprintf("%s%02d%02d", $sign, (gmtime(abs($t - $gm)))[2,1]);
541 =item get_record ( FILEHANDLE, INPUT_RECORD_SEPARATOR )
543 Read one record from FILEHANDLE delimited by INPUT_RECORD_SEPARATOR,
544 removing any trailing INPUT_RECORD_SEPARATOR.
546 =cut
548 sub get_record {
549 my ($fh, $rs) = @_;
550 local $/ = $rs;
551 my $rec = <$fh>;
552 chomp $rec if defined $rs;
553 $rec;
556 =item prompt ( PROMPT , ISPASSWORD )
558 Query user C<PROMPT> and return answer from user.
560 Honours GIT_ASKPASS and SSH_ASKPASS environment variables for querying
561 the user. If no *_ASKPASS variable is set or an error occoured,
562 the terminal is tried as a fallback.
563 If C<ISPASSWORD> is set and true, the terminal disables echo.
565 =cut
567 sub prompt {
568 my ($prompt, $isPassword) = @_;
569 my $ret;
570 if (exists $ENV{'GIT_ASKPASS'}) {
571 $ret = _prompt($ENV{'GIT_ASKPASS'}, $prompt);
573 if (!defined $ret && exists $ENV{'SSH_ASKPASS'}) {
574 $ret = _prompt($ENV{'SSH_ASKPASS'}, $prompt);
576 if (!defined $ret) {
577 print STDERR $prompt;
578 STDERR->flush;
579 if (defined $isPassword && $isPassword) {
580 require Term::ReadKey;
581 Term::ReadKey::ReadMode('noecho');
582 $ret = '';
583 while (defined(my $key = Term::ReadKey::ReadKey(0))) {
584 last if $key =~ /[\012\015]/; # \n\r
585 $ret .= $key;
587 Term::ReadKey::ReadMode('restore');
588 print STDERR "\n";
589 STDERR->flush;
590 } else {
591 chomp($ret = <STDIN>);
594 return $ret;
597 sub _prompt {
598 my ($askpass, $prompt) = @_;
599 return unless length $askpass;
600 $prompt =~ s/\n/ /g;
601 my $ret;
602 open my $fh, "-|", $askpass, $prompt or return;
603 $ret = <$fh>;
604 $ret =~ s/[\015\012]//g; # strip \r\n, chomp does not work on all systems (i.e. windows) as expected
605 close ($fh);
606 return $ret;
609 =item repo_path ()
611 Return path to the git repository. Must be called on a repository instance.
613 =cut
615 sub repo_path { $_[0]->{opts}->{Repository} }
618 =item wc_path ()
620 Return path to the working copy. Must be called on a repository instance.
622 =cut
624 sub wc_path { $_[0]->{opts}->{WorkingCopy} }
627 =item wc_subdir ()
629 Return path to the subdirectory inside of a working copy. Must be called
630 on a repository instance.
632 =cut
634 sub wc_subdir { $_[0]->{opts}->{WorkingSubdir} ||= '' }
637 =item wc_chdir ( SUBDIR )
639 Change the working copy subdirectory to work within. The C<SUBDIR> is
640 relative to the working copy root directory (not the current subdirectory).
641 Must be called on a repository instance attached to a working copy
642 and the directory must exist.
644 =cut
646 sub wc_chdir {
647 my ($self, $subdir) = @_;
648 $self->wc_path()
649 or throw Error::Simple("bare repository");
651 -d $self->wc_path().'/'.$subdir
652 or throw Error::Simple("subdir not found: $subdir $!");
653 # Of course we will not "hold" the subdirectory so anyone
654 # can delete it now and we will never know. But at least we tried.
656 $self->{opts}->{WorkingSubdir} = $subdir;
660 =item config ( VARIABLE )
662 Retrieve the configuration C<VARIABLE> in the same manner as C<config>
663 does. In scalar context requires the variable to be set only one time
664 (exception is thrown otherwise), in array context returns allows the
665 variable to be set multiple times and returns all the values.
667 =cut
669 sub config {
670 return _config_common({}, @_);
674 =item config_bool ( VARIABLE )
676 Retrieve the bool configuration C<VARIABLE>. The return value
677 is usable as a boolean in perl (and C<undef> if it's not defined,
678 of course).
680 =cut
682 sub config_bool {
683 my $val = scalar _config_common({'kind' => '--bool'}, @_);
685 # Do not rewrite this as return (defined $val && $val eq 'true')
686 # as some callers do care what kind of falsehood they receive.
687 if (!defined $val) {
688 return undef;
689 } else {
690 return $val eq 'true';
695 =item config_path ( VARIABLE )
697 Retrieve the path configuration C<VARIABLE>. The return value
698 is an expanded path or C<undef> if it's not defined.
700 =cut
702 sub config_path {
703 return _config_common({'kind' => '--path'}, @_);
707 =item config_int ( VARIABLE )
709 Retrieve the integer configuration C<VARIABLE>. The return value
710 is simple decimal number. An optional value suffix of 'k', 'm',
711 or 'g' in the config file will cause the value to be multiplied
712 by 1024, 1048576 (1024^2), or 1073741824 (1024^3) prior to output.
713 It would return C<undef> if configuration variable is not defined.
715 =cut
717 sub config_int {
718 return scalar _config_common({'kind' => '--int'}, @_);
721 # Common subroutine to implement bulk of what the config* family of methods
722 # do. This currently wraps command('config') so it is not so fast.
723 sub _config_common {
724 my ($opts) = shift @_;
725 my ($self, $var) = _maybe_self(@_);
727 try {
728 my @cmd = ('config', $opts->{'kind'} ? $opts->{'kind'} : ());
729 unshift @cmd, $self if $self;
730 if (wantarray) {
731 return command(@cmd, '--get-all', $var);
732 } else {
733 return command_oneline(@cmd, '--get', $var);
735 } catch Git::Error::Command with {
736 my $E = shift;
737 if ($E->value() == 1) {
738 # Key not found.
739 return;
740 } else {
741 throw $E;
746 =item get_colorbool ( NAME )
748 Finds if color should be used for NAMEd operation from the configuration,
749 and returns boolean (true for "use color", false for "do not use color").
751 =cut
753 sub get_colorbool {
754 my ($self, $var) = @_;
755 my $stdout_to_tty = (-t STDOUT) ? "true" : "false";
756 my $use_color = $self->command_oneline('config', '--get-colorbool',
757 $var, $stdout_to_tty);
758 return ($use_color eq 'true');
761 =item get_color ( SLOT, COLOR )
763 Finds color for SLOT from the configuration, while defaulting to COLOR,
764 and returns the ANSI color escape sequence:
766 print $repo->get_color("color.interactive.prompt", "underline blue white");
767 print "some text";
768 print $repo->get_color("", "normal");
770 =cut
772 sub get_color {
773 my ($self, $slot, $default) = @_;
774 my $color = $self->command_oneline('config', '--get-color', $slot, $default);
775 if (!defined $color) {
776 $color = "";
778 return $color;
781 =item remote_refs ( REPOSITORY [, GROUPS [, REFGLOBS ] ] )
783 This function returns a hashref of refs stored in a given remote repository.
784 The hash is in the format C<refname =\> hash>. For tags, the C<refname> entry
785 contains the tag object while a C<refname^{}> entry gives the tagged objects.
787 C<REPOSITORY> has the same meaning as the appropriate C<git-ls-remote>
788 argument; either a URL or a remote name (if called on a repository instance).
789 C<GROUPS> is an optional arrayref that can contain 'tags' to return all the
790 tags and/or 'heads' to return all the heads. C<REFGLOB> is an optional array
791 of strings containing a shell-like glob to further limit the refs returned in
792 the hash; the meaning is again the same as the appropriate C<git-ls-remote>
793 argument.
795 This function may or may not be called on a repository instance. In the former
796 case, remote names as defined in the repository are recognized as repository
797 specifiers.
799 =cut
801 sub remote_refs {
802 my ($self, $repo, $groups, $refglobs) = _maybe_self(@_);
803 my @args;
804 if (ref $groups eq 'ARRAY') {
805 foreach (@$groups) {
806 if ($_ eq 'heads') {
807 push (@args, '--heads');
808 } elsif ($_ eq 'tags') {
809 push (@args, '--tags');
810 } else {
811 # Ignore unknown groups for future
812 # compatibility
816 push (@args, $repo);
817 if (ref $refglobs eq 'ARRAY') {
818 push (@args, @$refglobs);
821 my @self = $self ? ($self) : (); # Ultra trickery
822 my ($fh, $ctx) = Git::command_output_pipe(@self, 'ls-remote', @args);
823 my %refs;
824 while (<$fh>) {
825 chomp;
826 my ($hash, $ref) = split(/\t/, $_, 2);
827 $refs{$ref} = $hash;
829 Git::command_close_pipe(@self, $fh, $ctx);
830 return \%refs;
834 =item ident ( TYPE | IDENTSTR )
836 =item ident_person ( TYPE | IDENTSTR | IDENTARRAY )
838 This suite of functions retrieves and parses ident information, as stored
839 in the commit and tag objects or produced by C<var GIT_type_IDENT> (thus
840 C<TYPE> can be either I<author> or I<committer>; case is insignificant).
842 The C<ident> method retrieves the ident information from C<git var>
843 and either returns it as a scalar string or as an array with the fields parsed.
844 Alternatively, it can take a prepared ident string (e.g. from the commit
845 object) and just parse it.
847 C<ident_person> returns the person part of the ident - name and email;
848 it can take the same arguments as C<ident> or the array returned by C<ident>.
850 The synopsis is like:
852 my ($name, $email, $time_tz) = ident('author');
853 "$name <$email>" eq ident_person('author');
854 "$name <$email>" eq ident_person($name);
855 $time_tz =~ /^\d+ [+-]\d{4}$/;
857 =cut
859 sub ident {
860 my ($self, $type) = _maybe_self(@_);
861 my $identstr;
862 if (lc $type eq lc 'committer' or lc $type eq lc 'author') {
863 my @cmd = ('var', 'GIT_'.uc($type).'_IDENT');
864 unshift @cmd, $self if $self;
865 $identstr = command_oneline(@cmd);
866 } else {
867 $identstr = $type;
869 if (wantarray) {
870 return $identstr =~ /^(.*) <(.*)> (\d+ [+-]\d{4})$/;
871 } else {
872 return $identstr;
876 sub ident_person {
877 my ($self, @ident) = _maybe_self(@_);
878 $#ident == 0 and @ident = $self ? $self->ident($ident[0]) : ident($ident[0]);
879 return "$ident[0] <$ident[1]>";
882 =item parse_mailboxes
884 Return an array of mailboxes extracted from a string.
886 =cut
888 # Very close to Mail::Address's parser, but we still have minor
889 # differences in some cases (see t9000 for examples).
890 sub parse_mailboxes {
891 my $re_comment = qr/\((?:[^)]*)\)/;
892 my $re_quote = qr/"(?:[^\"\\]|\\.)*"/;
893 my $re_word = qr/(?:[^]["\s()<>:;@\\,.]|\\.)+/;
895 # divide the string in tokens of the above form
896 my $re_token = qr/(?:$re_quote|$re_word|$re_comment|\S)/;
897 my @tokens = map { $_ =~ /\s*($re_token)\s*/g } @_;
898 my $end_of_addr_seen = 0;
900 # add a delimiter to simplify treatment for the last mailbox
901 push @tokens, ",";
903 my (@addr_list, @phrase, @address, @comment, @buffer) = ();
904 foreach my $token (@tokens) {
905 if ($token =~ /^[,;]$/) {
906 # if buffer still contains undeterminated strings
907 # append it at the end of @address or @phrase
908 if ($end_of_addr_seen) {
909 push @phrase, @buffer;
910 } else {
911 push @address, @buffer;
914 my $str_phrase = join ' ', @phrase;
915 my $str_address = join '', @address;
916 my $str_comment = join ' ', @comment;
918 # quote are necessary if phrase contains
919 # special characters
920 if ($str_phrase =~ /[][()<>:;@\\,.\000-\037\177]/) {
921 $str_phrase =~ s/(^|[^\\])"/$1/g;
922 $str_phrase = qq["$str_phrase"];
925 # add "<>" around the address if necessary
926 if ($str_address ne "" && $str_phrase ne "") {
927 $str_address = qq[<$str_address>];
930 my $str_mailbox = "$str_phrase $str_address $str_comment";
931 $str_mailbox =~ s/^\s*|\s*$//g;
932 push @addr_list, $str_mailbox if ($str_mailbox);
934 @phrase = @address = @comment = @buffer = ();
935 $end_of_addr_seen = 0;
936 } elsif ($token =~ /^\(/) {
937 push @comment, $token;
938 } elsif ($token eq "<") {
939 push @phrase, (splice @address), (splice @buffer);
940 } elsif ($token eq ">") {
941 $end_of_addr_seen = 1;
942 push @address, (splice @buffer);
943 } elsif ($token eq "@" && !$end_of_addr_seen) {
944 push @address, (splice @buffer), "@";
945 } else {
946 push @buffer, $token;
950 return @addr_list;
953 =item hash_object ( TYPE, FILENAME )
955 Compute the SHA1 object id of the given C<FILENAME> considering it is
956 of the C<TYPE> object type (C<blob>, C<commit>, C<tree>).
958 The method can be called without any instance or on a specified Git repository,
959 it makes zero difference.
961 The function returns the SHA1 hash.
963 =cut
965 # TODO: Support for passing FILEHANDLE instead of FILENAME
966 sub hash_object {
967 my ($self, $type, $file) = _maybe_self(@_);
968 command_oneline('hash-object', '-t', $type, $file);
972 =item hash_and_insert_object ( FILENAME )
974 Compute the SHA1 object id of the given C<FILENAME> and add the object to the
975 object database.
977 The function returns the SHA1 hash.
979 =cut
981 # TODO: Support for passing FILEHANDLE instead of FILENAME
982 sub hash_and_insert_object {
983 my ($self, $filename) = @_;
985 carp "Bad filename \"$filename\"" if $filename =~ /[\r\n]/;
987 $self->_open_hash_and_insert_object_if_needed();
988 my ($in, $out) = ($self->{hash_object_in}, $self->{hash_object_out});
990 unless (print $out $filename, "\n") {
991 $self->_close_hash_and_insert_object();
992 throw Error::Simple("out pipe went bad");
995 chomp(my $hash = <$in>);
996 unless (defined($hash)) {
997 $self->_close_hash_and_insert_object();
998 throw Error::Simple("in pipe went bad");
1001 return $hash;
1004 sub _open_hash_and_insert_object_if_needed {
1005 my ($self) = @_;
1007 return if defined($self->{hash_object_pid});
1009 ($self->{hash_object_pid}, $self->{hash_object_in},
1010 $self->{hash_object_out}, $self->{hash_object_ctx}) =
1011 $self->command_bidi_pipe(qw(hash-object -w --stdin-paths --no-filters));
1014 sub _close_hash_and_insert_object {
1015 my ($self) = @_;
1017 return unless defined($self->{hash_object_pid});
1019 my @vars = map { 'hash_object_' . $_ } qw(pid in out ctx);
1021 command_close_bidi_pipe(@$self{@vars});
1022 delete @$self{@vars};
1025 =item cat_blob ( SHA1, FILEHANDLE )
1027 Prints the contents of the blob identified by C<SHA1> to C<FILEHANDLE> and
1028 returns the number of bytes printed.
1030 =cut
1032 sub cat_blob {
1033 my ($self, $sha1, $fh) = @_;
1035 $self->_open_cat_blob_if_needed();
1036 my ($in, $out) = ($self->{cat_blob_in}, $self->{cat_blob_out});
1038 unless (print $out $sha1, "\n") {
1039 $self->_close_cat_blob();
1040 throw Error::Simple("out pipe went bad");
1043 my $description = <$in>;
1044 if ($description =~ / missing$/) {
1045 carp "$sha1 doesn't exist in the repository";
1046 return -1;
1049 if ($description !~ /^[0-9a-fA-F]{40} \S+ (\d+)$/) {
1050 carp "Unexpected result returned from git cat-file";
1051 return -1;
1054 my $size = $1;
1056 my $blob;
1057 my $bytesLeft = $size;
1059 while (1) {
1060 last unless $bytesLeft;
1062 my $bytesToRead = $bytesLeft < 1024 ? $bytesLeft : 1024;
1063 my $read = read($in, $blob, $bytesToRead);
1064 unless (defined($read)) {
1065 $self->_close_cat_blob();
1066 throw Error::Simple("in pipe went bad");
1068 unless (print $fh $blob) {
1069 $self->_close_cat_blob();
1070 throw Error::Simple("couldn't write to passed in filehandle");
1072 $bytesLeft -= $read;
1075 # Skip past the trailing newline.
1076 my $newline;
1077 my $read = read($in, $newline, 1);
1078 unless (defined($read)) {
1079 $self->_close_cat_blob();
1080 throw Error::Simple("in pipe went bad");
1082 unless ($read == 1 && $newline eq "\n") {
1083 $self->_close_cat_blob();
1084 throw Error::Simple("didn't find newline after blob");
1087 return $size;
1090 sub _open_cat_blob_if_needed {
1091 my ($self) = @_;
1093 return if defined($self->{cat_blob_pid});
1095 ($self->{cat_blob_pid}, $self->{cat_blob_in},
1096 $self->{cat_blob_out}, $self->{cat_blob_ctx}) =
1097 $self->command_bidi_pipe(qw(cat-file --batch));
1100 sub _close_cat_blob {
1101 my ($self) = @_;
1103 return unless defined($self->{cat_blob_pid});
1105 my @vars = map { 'cat_blob_' . $_ } qw(pid in out ctx);
1107 command_close_bidi_pipe(@$self{@vars});
1108 delete @$self{@vars};
1112 =item credential_read( FILEHANDLE )
1114 Reads credential key-value pairs from C<FILEHANDLE>. Reading stops at EOF or
1115 when an empty line is encountered. Each line must be of the form C<key=value>
1116 with a non-empty key. Function returns hash with all read values. Any white
1117 space (other than new-line character) is preserved.
1119 =cut
1121 sub credential_read {
1122 my ($self, $reader) = _maybe_self(@_);
1123 my %credential;
1124 while (<$reader>) {
1125 chomp;
1126 if ($_ eq '') {
1127 last;
1128 } elsif (!/^([^=]+)=(.*)$/) {
1129 throw Error::Simple("unable to parse git credential data:\n$_");
1131 $credential{$1} = $2;
1133 return %credential;
1136 =item credential_write( FILEHANDLE, CREDENTIAL_HASHREF )
1138 Writes credential key-value pairs from hash referenced by
1139 C<CREDENTIAL_HASHREF> to C<FILEHANDLE>. Keys and values cannot contain
1140 new-lines or NUL bytes characters, and key cannot contain equal signs nor be
1141 empty (if they do Error::Simple is thrown). Any white space is preserved. If
1142 value for a key is C<undef>, it will be skipped.
1144 If C<'url'> key exists it will be written first. (All the other key-value
1145 pairs are written in sorted order but you should not depend on that). Once
1146 all lines are written, an empty line is printed.
1148 =cut
1150 sub credential_write {
1151 my ($self, $writer, $credential) = _maybe_self(@_);
1152 my ($key, $value);
1154 # Check if $credential is valid prior to writing anything
1155 while (($key, $value) = each %$credential) {
1156 if (!defined $key || !length $key) {
1157 throw Error::Simple("credential key empty or undefined");
1158 } elsif ($key =~ /[=\n\0]/) {
1159 throw Error::Simple("credential key contains invalid characters: $key");
1160 } elsif (defined $value && $value =~ /[\n\0]/) {
1161 throw Error::Simple("credential value for key=$key contains invalid characters: $value");
1165 for $key (sort {
1166 # url overwrites other fields, so it must come first
1167 return -1 if $a eq 'url';
1168 return 1 if $b eq 'url';
1169 return $a cmp $b;
1170 } keys %$credential) {
1171 if (defined $credential->{$key}) {
1172 print $writer $key, '=', $credential->{$key}, "\n";
1175 print $writer "\n";
1178 sub _credential_run {
1179 my ($self, $credential, $op) = _maybe_self(@_);
1180 my ($pid, $reader, $writer, $ctx) = command_bidi_pipe('credential', $op);
1182 credential_write $writer, $credential;
1183 close $writer;
1185 if ($op eq "fill") {
1186 %$credential = credential_read $reader;
1188 if (<$reader>) {
1189 throw Error::Simple("unexpected output from git credential $op response:\n$_\n");
1192 command_close_bidi_pipe($pid, $reader, undef, $ctx);
1195 =item credential( CREDENTIAL_HASHREF [, OPERATION ] )
1197 =item credential( CREDENTIAL_HASHREF, CODE )
1199 Executes C<git credential> for a given set of credentials and specified
1200 operation. In both forms C<CREDENTIAL_HASHREF> needs to be a reference to
1201 a hash which stores credentials. Under certain conditions the hash can
1202 change.
1204 In the first form, C<OPERATION> can be C<'fill'>, C<'approve'> or C<'reject'>,
1205 and function will execute corresponding C<git credential> sub-command. If
1206 it's omitted C<'fill'> is assumed. In case of C<'fill'> the values stored in
1207 C<CREDENTIAL_HASHREF> will be changed to the ones returned by the C<git
1208 credential fill> command. The usual usage would look something like:
1210 my %cred = (
1211 'protocol' => 'https',
1212 'host' => 'example.com',
1213 'username' => 'bob'
1215 Git::credential \%cred;
1216 if (try_to_authenticate($cred{'username'}, $cred{'password'})) {
1217 Git::credential \%cred, 'approve';
1218 ... do more stuff ...
1219 } else {
1220 Git::credential \%cred, 'reject';
1223 In the second form, C<CODE> needs to be a reference to a subroutine. The
1224 function will execute C<git credential fill> to fill the provided credential
1225 hash, then call C<CODE> with C<CREDENTIAL_HASHREF> as the sole argument. If
1226 C<CODE>'s return value is defined, the function will execute C<git credential
1227 approve> (if return value yields true) or C<git credential reject> (if return
1228 value is false). If the return value is undef, nothing at all is executed;
1229 this is useful, for example, if the credential could neither be verified nor
1230 rejected due to an unrelated network error. The return value is the same as
1231 what C<CODE> returns. With this form, the usage might look as follows:
1233 if (Git::credential {
1234 'protocol' => 'https',
1235 'host' => 'example.com',
1236 'username' => 'bob'
1237 }, sub {
1238 my $cred = shift;
1239 return !!try_to_authenticate($cred->{'username'},
1240 $cred->{'password'});
1241 }) {
1242 ... do more stuff ...
1245 =cut
1247 sub credential {
1248 my ($self, $credential, $op_or_code) = (_maybe_self(@_), 'fill');
1250 if ('CODE' eq ref $op_or_code) {
1251 _credential_run $credential, 'fill';
1252 my $ret = $op_or_code->($credential);
1253 if (defined $ret) {
1254 _credential_run $credential, $ret ? 'approve' : 'reject';
1256 return $ret;
1257 } else {
1258 _credential_run $credential, $op_or_code;
1262 { # %TEMP_* Lexical Context
1264 my (%TEMP_FILEMAP, %TEMP_FILES);
1266 =item temp_acquire ( NAME )
1268 Attempts to retrieve the temporary file mapped to the string C<NAME>. If an
1269 associated temp file has not been created this session or was closed, it is
1270 created, cached, and set for autoflush and binmode.
1272 Internally locks the file mapped to C<NAME>. This lock must be released with
1273 C<temp_release()> when the temp file is no longer needed. Subsequent attempts
1274 to retrieve temporary files mapped to the same C<NAME> while still locked will
1275 cause an error. This locking mechanism provides a weak guarantee and is not
1276 threadsafe. It does provide some error checking to help prevent temp file refs
1277 writing over one another.
1279 In general, the L<File::Handle> returned should not be closed by consumers as
1280 it defeats the purpose of this caching mechanism. If you need to close the temp
1281 file handle, then you should use L<File::Temp> or another temp file faculty
1282 directly. If a handle is closed and then requested again, then a warning will
1283 issue.
1285 =cut
1287 sub temp_acquire {
1288 my $temp_fd = _temp_cache(@_);
1290 $TEMP_FILES{$temp_fd}{locked} = 1;
1291 $temp_fd;
1294 =item temp_is_locked ( NAME )
1296 Returns true if the internal lock created by a previous C<temp_acquire()>
1297 call with C<NAME> is still in effect.
1299 When temp_acquire is called on a C<NAME>, it internally locks the temporary
1300 file mapped to C<NAME>. That lock will not be released until C<temp_release()>
1301 is called with either the original C<NAME> or the L<File::Handle> that was
1302 returned from the original call to temp_acquire.
1304 Subsequent attempts to call C<temp_acquire()> with the same C<NAME> will fail
1305 unless there has been an intervening C<temp_release()> call for that C<NAME>
1306 (or its corresponding L<File::Handle> that was returned by the original
1307 C<temp_acquire()> call).
1309 If true is returned by C<temp_is_locked()> for a C<NAME>, an attempt to
1310 C<temp_acquire()> the same C<NAME> will cause an error unless
1311 C<temp_release> is first called on that C<NAME> (or its corresponding
1312 L<File::Handle> that was returned by the original C<temp_acquire()> call).
1314 =cut
1316 sub temp_is_locked {
1317 my ($self, $name) = _maybe_self(@_);
1318 my $temp_fd = \$TEMP_FILEMAP{$name};
1320 defined $$temp_fd && $$temp_fd->opened && $TEMP_FILES{$$temp_fd}{locked};
1323 =item temp_release ( NAME )
1325 =item temp_release ( FILEHANDLE )
1327 Releases a lock acquired through C<temp_acquire()>. Can be called either with
1328 the C<NAME> mapping used when acquiring the temp file or with the C<FILEHANDLE>
1329 referencing a locked temp file.
1331 Warns if an attempt is made to release a file that is not locked.
1333 The temp file will be truncated before being released. This can help to reduce
1334 disk I/O where the system is smart enough to detect the truncation while data
1335 is in the output buffers. Beware that after the temp file is released and
1336 truncated, any operations on that file may fail miserably until it is
1337 re-acquired. All contents are lost between each release and acquire mapped to
1338 the same string.
1340 =cut
1342 sub temp_release {
1343 my ($self, $temp_fd, $trunc) = _maybe_self(@_);
1345 if (exists $TEMP_FILEMAP{$temp_fd}) {
1346 $temp_fd = $TEMP_FILES{$temp_fd};
1348 unless ($TEMP_FILES{$temp_fd}{locked}) {
1349 carp "Attempt to release temp file '",
1350 $temp_fd, "' that has not been locked";
1352 temp_reset($temp_fd) if $trunc and $temp_fd->opened;
1354 $TEMP_FILES{$temp_fd}{locked} = 0;
1355 undef;
1358 sub _temp_cache {
1359 my ($self, $name) = _maybe_self(@_);
1361 _verify_require();
1363 my $temp_fd = \$TEMP_FILEMAP{$name};
1364 if (defined $$temp_fd and $$temp_fd->opened) {
1365 if ($TEMP_FILES{$$temp_fd}{locked}) {
1366 throw Error::Simple("Temp file with moniker '" .
1367 $name . "' already in use");
1369 } else {
1370 if (defined $$temp_fd) {
1371 # then we're here because of a closed handle.
1372 carp "Temp file '", $name,
1373 "' was closed. Opening replacement.";
1375 my $fname;
1377 my $tmpdir;
1378 if (defined $self) {
1379 $tmpdir = $self->repo_path();
1382 my $n = $name;
1383 $n =~ s/\W/_/g; # no strange chars
1385 ($$temp_fd, $fname) = File::Temp::tempfile(
1386 "Git_${n}_XXXXXX", UNLINK => 1, DIR => $tmpdir,
1387 ) or throw Error::Simple("couldn't open new temp file");
1389 $$temp_fd->autoflush;
1390 binmode $$temp_fd;
1391 $TEMP_FILES{$$temp_fd}{fname} = $fname;
1393 $$temp_fd;
1396 sub _verify_require {
1397 eval { require File::Temp; require File::Spec; };
1398 $@ and throw Error::Simple($@);
1401 =item temp_reset ( FILEHANDLE )
1403 Truncates and resets the position of the C<FILEHANDLE>.
1405 =cut
1407 sub temp_reset {
1408 my ($self, $temp_fd) = _maybe_self(@_);
1410 truncate $temp_fd, 0
1411 or throw Error::Simple("couldn't truncate file");
1412 sysseek($temp_fd, 0, SEEK_SET) and seek($temp_fd, 0, SEEK_SET)
1413 or throw Error::Simple("couldn't seek to beginning of file");
1414 sysseek($temp_fd, 0, SEEK_CUR) == 0 and tell($temp_fd) == 0
1415 or throw Error::Simple("expected file position to be reset");
1418 =item temp_path ( NAME )
1420 =item temp_path ( FILEHANDLE )
1422 Returns the filename associated with the given tempfile.
1424 =cut
1426 sub temp_path {
1427 my ($self, $temp_fd) = _maybe_self(@_);
1429 if (exists $TEMP_FILEMAP{$temp_fd}) {
1430 $temp_fd = $TEMP_FILEMAP{$temp_fd};
1432 $TEMP_FILES{$temp_fd}{fname};
1435 sub END {
1436 unlink values %TEMP_FILEMAP if %TEMP_FILEMAP;
1439 } # %TEMP_* Lexical Context
1441 =back
1443 =head1 ERROR HANDLING
1445 All functions are supposed to throw Perl exceptions in case of errors.
1446 See the L<Error> module on how to catch those. Most exceptions are mere
1447 L<Error::Simple> instances.
1449 However, the C<command()>, C<command_oneline()> and C<command_noisy()>
1450 functions suite can throw C<Git::Error::Command> exceptions as well: those are
1451 thrown when the external command returns an error code and contain the error
1452 code as well as access to the captured command's output. The exception class
1453 provides the usual C<stringify> and C<value> (command's exit code) methods and
1454 in addition also a C<cmd_output> method that returns either an array or a
1455 string with the captured command output (depending on the original function
1456 call context; C<command_noisy()> returns C<undef>) and $<cmdline> which
1457 returns the command and its arguments (but without proper quoting).
1459 Note that the C<command_*_pipe()> functions cannot throw this exception since
1460 it has no idea whether the command failed or not. You will only find out
1461 at the time you C<close> the pipe; if you want to have that automated,
1462 use C<command_close_pipe()>, which can throw the exception.
1464 =cut
1467 package Git::Error::Command;
1469 @Git::Error::Command::ISA = qw(Error);
1471 sub new {
1472 my $self = shift;
1473 my $cmdline = '' . shift;
1474 my $value = 0 + shift;
1475 my $outputref = shift;
1476 my(@args) = ();
1478 local $Error::Depth = $Error::Depth + 1;
1480 push(@args, '-cmdline', $cmdline);
1481 push(@args, '-value', $value);
1482 push(@args, '-outputref', $outputref);
1484 $self->SUPER::new(-text => 'command returned error', @args);
1487 sub stringify {
1488 my $self = shift;
1489 my $text = $self->SUPER::stringify;
1490 $self->cmdline() . ': ' . $text . ': ' . $self->value() . "\n";
1493 sub cmdline {
1494 my $self = shift;
1495 $self->{'-cmdline'};
1498 sub cmd_output {
1499 my $self = shift;
1500 my $ref = $self->{'-outputref'};
1501 defined $ref or undef;
1502 if (ref $ref eq 'ARRAY') {
1503 return @$ref;
1504 } else { # SCALAR
1505 return $$ref;
1510 =over 4
1512 =item git_cmd_try { CODE } ERRMSG
1514 This magical statement will automatically catch any C<Git::Error::Command>
1515 exceptions thrown by C<CODE> and make your program die with C<ERRMSG>
1516 on its lips; the message will have %s substituted for the command line
1517 and %d for the exit status. This statement is useful mostly for producing
1518 more user-friendly error messages.
1520 In case of no exception caught the statement returns C<CODE>'s return value.
1522 Note that this is the only auto-exported function.
1524 =cut
1526 sub git_cmd_try(&$) {
1527 my ($code, $errmsg) = @_;
1528 my @result;
1529 my $err;
1530 my $array = wantarray;
1531 try {
1532 if ($array) {
1533 @result = &$code;
1534 } else {
1535 $result[0] = &$code;
1537 } catch Git::Error::Command with {
1538 my $E = shift;
1539 $err = $errmsg;
1540 $err =~ s/\%s/$E->cmdline()/ge;
1541 $err =~ s/\%d/$E->value()/ge;
1542 # We can't croak here since Error.pm would mangle
1543 # that to Error::Simple.
1545 $err and croak $err;
1546 return $array ? @result : $result[0];
1550 =back
1552 =head1 COPYRIGHT
1554 Copyright 2006 by Petr Baudis E<lt>pasky@suse.czE<gt>.
1556 This module is free software; it may be used, copied, modified
1557 and distributed under the terms of the GNU General Public Licence,
1558 either version 2, or (at your option) any later version.
1560 =cut
1563 # Take raw method argument list and return ($obj, @args) in case
1564 # the method was called upon an instance and (undef, @args) if
1565 # it was called directly.
1566 sub _maybe_self {
1567 UNIVERSAL::isa($_[0], 'Git') ? @_ : (undef, @_);
1570 # Check if the command id is something reasonable.
1571 sub _check_valid_cmd {
1572 my ($cmd) = @_;
1573 $cmd =~ /^[a-z0-9A-Z_-]+$/ or throw Error::Simple("bad command: $cmd");
1576 # Common backend for the pipe creators.
1577 sub _command_common_pipe {
1578 my $direction = shift;
1579 my ($self, @p) = _maybe_self(@_);
1580 my (%opts, $cmd, @args);
1581 if (ref $p[0]) {
1582 ($cmd, @args) = @{shift @p};
1583 %opts = ref $p[0] ? %{$p[0]} : @p;
1584 } else {
1585 ($cmd, @args) = @p;
1587 _check_valid_cmd($cmd);
1589 my $fh;
1590 if ($^O eq 'MSWin32') {
1591 # ActiveState Perl
1592 #defined $opts{STDERR} and
1593 # warn 'ignoring STDERR option - running w/ ActiveState';
1594 $direction eq '-|' or
1595 die 'input pipe for ActiveState not implemented';
1596 # the strange construction with *ACPIPE is just to
1597 # explain the tie below that we want to bind to
1598 # a handle class, not scalar. It is not known if
1599 # it is something specific to ActiveState Perl or
1600 # just a Perl quirk.
1601 tie (*ACPIPE, 'Git::activestate_pipe', $cmd, @args);
1602 $fh = *ACPIPE;
1604 } else {
1605 my $pid = open($fh, $direction);
1606 if (not defined $pid) {
1607 throw Error::Simple("open failed: $!");
1608 } elsif ($pid == 0) {
1609 if ($opts{STDERR}) {
1610 open (STDERR, '>&', $opts{STDERR})
1611 or die "dup failed: $!";
1612 } elsif (defined $opts{STDERR}) {
1613 open (STDERR, '>', '/dev/null')
1614 or die "opening /dev/null failed: $!";
1616 _cmd_exec($self, $cmd, @args);
1619 return wantarray ? ($fh, join(' ', $cmd, @args)) : $fh;
1622 # When already in the subprocess, set up the appropriate state
1623 # for the given repository and execute the git command.
1624 sub _cmd_exec {
1625 my ($self, @args) = @_;
1626 _setup_git_cmd_env($self);
1627 _execv_git_cmd(@args);
1628 die qq[exec "@args" failed: $!];
1631 # set up the appropriate state for git command
1632 sub _setup_git_cmd_env {
1633 my $self = shift;
1634 if ($self) {
1635 $self->repo_path() and $ENV{'GIT_DIR'} = $self->repo_path();
1636 $self->repo_path() and $self->wc_path()
1637 and $ENV{'GIT_WORK_TREE'} = $self->wc_path();
1638 $self->wc_path() and chdir($self->wc_path());
1639 $self->wc_subdir() and chdir($self->wc_subdir());
1643 # Execute the given Git command ($_[0]) with arguments ($_[1..])
1644 # by searching for it at proper places.
1645 sub _execv_git_cmd { exec('git', @_); }
1647 # Close pipe to a subprocess.
1648 sub _cmd_close {
1649 my $ctx = shift @_;
1650 foreach my $fh (@_) {
1651 if (close $fh) {
1652 # nop
1653 } elsif ($!) {
1654 # It's just close, no point in fatalities
1655 carp "error closing pipe: $!";
1656 } elsif ($? >> 8) {
1657 # The caller should pepper this.
1658 throw Git::Error::Command($ctx, $? >> 8);
1660 # else we might e.g. closed a live stream; the command
1661 # dying of SIGPIPE would drive us here.
1666 sub DESTROY {
1667 my ($self) = @_;
1668 $self->_close_hash_and_insert_object();
1669 $self->_close_cat_blob();
1673 # Pipe implementation for ActiveState Perl.
1675 package Git::activestate_pipe;
1676 use strict;
1678 sub TIEHANDLE {
1679 my ($class, @params) = @_;
1680 # FIXME: This is probably horrible idea and the thing will explode
1681 # at the moment you give it arguments that require some quoting,
1682 # but I have no ActiveState clue... --pasky
1683 # Let's just hope ActiveState Perl does at least the quoting
1684 # correctly.
1685 my @data = qx{git @params};
1686 bless { i => 0, data => \@data }, $class;
1689 sub READLINE {
1690 my $self = shift;
1691 if ($self->{i} >= scalar @{$self->{data}}) {
1692 return undef;
1694 my $i = $self->{i};
1695 if (wantarray) {
1696 $self->{i} = $#{$self->{'data'}} + 1;
1697 return splice(@{$self->{'data'}}, $i);
1699 $self->{i} = $i + 1;
1700 return $self->{'data'}->[ $i ];
1703 sub CLOSE {
1704 my $self = shift;
1705 delete $self->{data};
1706 delete $self->{i};
1709 sub EOF {
1710 my $self = shift;
1711 return ($self->{i} >= scalar @{$self->{data}});
1715 1; # Famous last words