Make the MSVC projects use PDB/IDB files named after the project
[git/dscho.git] / perl / Git.pm
blobe8df55d2f290210ba4cf7ae8c91639f2a34c834e
1 =head1 NAME
3 Git - Perl interface to the Git version control system
5 =cut
8 package Git;
10 use strict;
13 BEGIN {
15 our ($VERSION, @ISA, @EXPORT, @EXPORT_OK);
17 # Totally unstable API.
18 $VERSION = '0.01';
21 =head1 SYNOPSIS
23 use Git;
25 my $version = Git::command_oneline('version');
27 git_cmd_try { Git::command_noisy('update-server-info') }
28 '%s failed w/ code %d';
30 my $repo = Git->repository (Directory => '/srv/git/cogito.git');
33 my @revs = $repo->command('rev-list', '--since=last monday', '--all');
35 my ($fh, $c) = $repo->command_output_pipe('rev-list', '--since=last monday', '--all');
36 my $lastrev = <$fh>; chomp $lastrev;
37 $repo->command_close_pipe($fh, $c);
39 my $lastrev = $repo->command_oneline( [ 'rev-list', '--all' ],
40 STDERR => 0 );
42 my $sha1 = $repo->hash_and_insert_object('file.txt');
43 my $tempfile = tempfile();
44 my $size = $repo->cat_blob($sha1, $tempfile);
46 =cut
49 require Exporter;
51 @ISA = qw(Exporter);
53 @EXPORT = qw(git_cmd_try);
55 # Methods which can be called as standalone functions as well:
56 @EXPORT_OK = qw(command command_oneline command_noisy
57 command_output_pipe command_input_pipe command_close_pipe
58 command_bidi_pipe command_close_bidi_pipe
59 version exec_path html_path hash_object git_cmd_try
60 remote_refs
61 temp_acquire temp_release temp_reset temp_path);
64 =head1 DESCRIPTION
66 This module provides Perl scripts easy way to interface the Git version control
67 system. The modules have an easy and well-tested way to call arbitrary Git
68 commands; in the future, the interface will also provide specialized methods
69 for doing easily operations which are not totally trivial to do over
70 the generic command interface.
72 While some commands can be executed outside of any context (e.g. 'version'
73 or 'init'), most operations require a repository context, which in practice
74 means getting an instance of the Git object using the repository() constructor.
75 (In the future, we will also get a new_repository() constructor.) All commands
76 called as methods of the object are then executed in the context of the
77 repository.
79 Part of the "repository state" is also information about path to the attached
80 working copy (unless you work with a bare repository). You can also navigate
81 inside of the working copy using the C<wc_chdir()> method. (Note that
82 the repository object is self-contained and will not change working directory
83 of your process.)
85 TODO: In the future, we might also do
87 my $remoterepo = $repo->remote_repository (Name => 'cogito', Branch => 'master');
88 $remoterepo ||= Git->remote_repository ('http://git.or.cz/cogito.git/');
89 my @refs = $remoterepo->refs();
91 Currently, the module merely wraps calls to external Git tools. In the future,
92 it will provide a much faster way to interact with Git by linking directly
93 to libgit. This should be completely opaque to the user, though (performance
94 increase notwithstanding).
96 =cut
99 use Carp qw(carp croak); # but croak is bad - throw instead
100 use Error qw(:try);
101 use Cwd qw(abs_path);
102 use IPC::Open2 qw(open2);
103 use Fcntl qw(SEEK_SET SEEK_CUR);
107 =head1 CONSTRUCTORS
109 =over 4
111 =item repository ( OPTIONS )
113 =item repository ( DIRECTORY )
115 =item repository ()
117 Construct a new repository object.
118 C<OPTIONS> are passed in a hash like fashion, using key and value pairs.
119 Possible options are:
121 B<Repository> - Path to the Git repository.
123 B<WorkingCopy> - Path to the associated working copy; not strictly required
124 as many commands will happily crunch on a bare repository.
126 B<WorkingSubdir> - Subdirectory in the working copy to work inside.
127 Just left undefined if you do not want to limit the scope of operations.
129 B<Directory> - Path to the Git working directory in its usual setup.
130 The C<.git> directory is searched in the directory and all the parent
131 directories; if found, C<WorkingCopy> is set to the directory containing
132 it and C<Repository> to the C<.git> directory itself. If no C<.git>
133 directory was found, the C<Directory> is assumed to be a bare repository,
134 C<Repository> is set to point at it and C<WorkingCopy> is left undefined.
135 If the C<$GIT_DIR> environment variable is set, things behave as expected
136 as well.
138 You should not use both C<Directory> and either of C<Repository> and
139 C<WorkingCopy> - the results of that are undefined.
141 Alternatively, a directory path may be passed as a single scalar argument
142 to the constructor; it is equivalent to setting only the C<Directory> option
143 field.
145 Calling the constructor with no options whatsoever is equivalent to
146 calling it with C<< Directory => '.' >>. In general, if you are building
147 a standard porcelain command, simply doing C<< Git->repository() >> should
148 do the right thing and setup the object to reflect exactly where the user
149 is right now.
151 =cut
153 sub repository {
154 my $class = shift;
155 my @args = @_;
156 my %opts = ();
157 my $self;
159 if (defined $args[0]) {
160 if ($#args % 2 != 1) {
161 # Not a hash.
162 $#args == 0 or throw Error::Simple("bad usage");
163 %opts = ( Directory => $args[0] );
164 } else {
165 %opts = @args;
169 if (not defined $opts{Repository} and not defined $opts{WorkingCopy}
170 and not defined $opts{Directory}) {
171 $opts{Directory} = '.';
174 if (defined $opts{Directory}) {
175 -d $opts{Directory} or throw Error::Simple("Directory not found: $!");
177 my $search = Git->repository(WorkingCopy => $opts{Directory});
178 my $dir;
179 try {
180 $dir = $search->command_oneline(['rev-parse', '--git-dir'],
181 STDERR => 0);
182 } catch Git::Error::Command with {
183 $dir = undef;
186 if ($dir) {
187 $dir =~ m#^/# or $dir = $opts{Directory} . '/' . $dir;
188 $opts{Repository} = abs_path($dir);
190 # If --git-dir went ok, this shouldn't die either.
191 my $prefix = $search->command_oneline('rev-parse', '--show-prefix');
192 $dir = abs_path($opts{Directory}) . '/';
193 if ($prefix) {
194 if (substr($dir, -length($prefix)) ne $prefix) {
195 throw Error::Simple("rev-parse confused me - $dir does not have trailing $prefix");
197 substr($dir, -length($prefix)) = '';
199 $opts{WorkingCopy} = $dir;
200 $opts{WorkingSubdir} = $prefix;
202 } else {
203 # A bare repository? Let's see...
204 $dir = $opts{Directory};
206 unless (-d "$dir/refs" and -d "$dir/objects" and -e "$dir/HEAD") {
207 # Mimick git-rev-parse --git-dir error message:
208 throw Error::Simple("fatal: Not a git repository: $dir");
210 my $search = Git->repository(Repository => $dir);
211 try {
212 $search->command('symbolic-ref', 'HEAD');
213 } catch Git::Error::Command with {
214 # Mimick git-rev-parse --git-dir error message:
215 throw Error::Simple("fatal: Not a git repository: $dir");
218 $opts{Repository} = abs_path($dir);
221 delete $opts{Directory};
224 $self = { opts => \%opts };
225 bless $self, $class;
228 =back
230 =head1 METHODS
232 =over 4
234 =item command ( COMMAND [, ARGUMENTS... ] )
236 =item command ( [ COMMAND, ARGUMENTS... ], { Opt => Val ... } )
238 Execute the given Git C<COMMAND> (specify it without the 'git-'
239 prefix), optionally with the specified extra C<ARGUMENTS>.
241 The second more elaborate form can be used if you want to further adjust
242 the command execution. Currently, only one option is supported:
244 B<STDERR> - How to deal with the command's error output. By default (C<undef>)
245 it is delivered to the caller's C<STDERR>. A false value (0 or '') will cause
246 it to be thrown away. If you want to process it, you can get it in a filehandle
247 you specify, but you must be extremely careful; if the error output is not
248 very short and you want to read it in the same process as where you called
249 C<command()>, you are set up for a nice deadlock!
251 The method can be called without any instance or on a specified Git repository
252 (in that case the command will be run in the repository context).
254 In scalar context, it returns all the command output in a single string
255 (verbatim).
257 In array context, it returns an array containing lines printed to the
258 command's stdout (without trailing newlines).
260 In both cases, the command's stdin and stderr are the same as the caller's.
262 =cut
264 sub command {
265 my ($fh, $ctx) = command_output_pipe(@_);
267 if (not defined wantarray) {
268 # Nothing to pepper the possible exception with.
269 _cmd_close($fh, $ctx);
271 } elsif (not wantarray) {
272 local $/;
273 my $text = <$fh>;
274 try {
275 _cmd_close($fh, $ctx);
276 } catch Git::Error::Command with {
277 # Pepper with the output:
278 my $E = shift;
279 $E->{'-outputref'} = \$text;
280 throw $E;
282 return $text;
284 } else {
285 my @lines = <$fh>;
286 defined and chomp for @lines;
287 try {
288 _cmd_close($fh, $ctx);
289 } catch Git::Error::Command with {
290 my $E = shift;
291 $E->{'-outputref'} = \@lines;
292 throw $E;
294 return @lines;
299 =item command_oneline ( COMMAND [, ARGUMENTS... ] )
301 =item command_oneline ( [ COMMAND, ARGUMENTS... ], { Opt => Val ... } )
303 Execute the given C<COMMAND> in the same way as command()
304 does but always return a scalar string containing the first line
305 of the command's standard output.
307 =cut
309 sub command_oneline {
310 my ($fh, $ctx) = command_output_pipe(@_);
312 my $line = <$fh>;
313 defined $line and chomp $line;
314 try {
315 _cmd_close($fh, $ctx);
316 } catch Git::Error::Command with {
317 # Pepper with the output:
318 my $E = shift;
319 $E->{'-outputref'} = \$line;
320 throw $E;
322 return $line;
326 =item command_output_pipe ( COMMAND [, ARGUMENTS... ] )
328 =item command_output_pipe ( [ COMMAND, ARGUMENTS... ], { Opt => Val ... } )
330 Execute the given C<COMMAND> in the same way as command()
331 does but return a pipe filehandle from which the command output can be
332 read.
334 The function can return C<($pipe, $ctx)> in array context.
335 See C<command_close_pipe()> for details.
337 =cut
339 sub command_output_pipe {
340 _command_common_pipe('-|', @_);
344 =item command_input_pipe ( COMMAND [, ARGUMENTS... ] )
346 =item command_input_pipe ( [ COMMAND, ARGUMENTS... ], { Opt => Val ... } )
348 Execute the given C<COMMAND> in the same way as command_output_pipe()
349 does but return an input pipe filehandle instead; the command output
350 is not captured.
352 The function can return C<($pipe, $ctx)> in array context.
353 See C<command_close_pipe()> for details.
355 =cut
357 sub command_input_pipe {
358 _command_common_pipe('|-', @_);
362 =item command_close_pipe ( PIPE [, CTX ] )
364 Close the C<PIPE> as returned from C<command_*_pipe()>, checking
365 whether the command finished successfully. The optional C<CTX> argument
366 is required if you want to see the command name in the error message,
367 and it is the second value returned by C<command_*_pipe()> when
368 called in array context. The call idiom is:
370 my ($fh, $ctx) = $r->command_output_pipe('status');
371 while (<$fh>) { ... }
372 $r->command_close_pipe($fh, $ctx);
374 Note that you should not rely on whatever actually is in C<CTX>;
375 currently it is simply the command name but in future the context might
376 have more complicated structure.
378 =cut
380 sub command_close_pipe {
381 my ($self, $fh, $ctx) = _maybe_self(@_);
382 $ctx ||= '<unknown>';
383 _cmd_close($fh, $ctx);
386 =item command_bidi_pipe ( COMMAND [, ARGUMENTS... ] )
388 Execute the given C<COMMAND> in the same way as command_output_pipe()
389 does but return both an input pipe filehandle and an output pipe filehandle.
391 The function will return return C<($pid, $pipe_in, $pipe_out, $ctx)>.
392 See C<command_close_bidi_pipe()> for details.
394 =cut
396 sub command_bidi_pipe {
397 my ($pid, $in, $out);
398 $pid = open2($in, $out, 'git', @_);
399 return ($pid, $in, $out, join(' ', @_));
402 =item command_close_bidi_pipe ( PID, PIPE_IN, PIPE_OUT [, CTX] )
404 Close the C<PIPE_IN> and C<PIPE_OUT> as returned from C<command_bidi_pipe()>,
405 checking whether the command finished successfully. The optional C<CTX>
406 argument is required if you want to see the command name in the error message,
407 and it is the fourth value returned by C<command_bidi_pipe()>. The call idiom
410 my ($pid, $in, $out, $ctx) = $r->command_bidi_pipe('cat-file --batch-check');
411 print "000000000\n" $out;
412 while (<$in>) { ... }
413 $r->command_close_bidi_pipe($pid, $in, $out, $ctx);
415 Note that you should not rely on whatever actually is in C<CTX>;
416 currently it is simply the command name but in future the context might
417 have more complicated structure.
419 =cut
421 sub command_close_bidi_pipe {
422 local $?;
423 my ($pid, $in, $out, $ctx) = @_;
424 foreach my $fh ($in, $out) {
425 unless (close $fh) {
426 if ($!) {
427 carp "error closing pipe: $!";
428 } elsif ($? >> 8) {
429 throw Git::Error::Command($ctx, $? >>8);
434 waitpid $pid, 0;
436 if ($? >> 8) {
437 throw Git::Error::Command($ctx, $? >>8);
442 =item command_noisy ( COMMAND [, ARGUMENTS... ] )
444 Execute the given C<COMMAND> in the same way as command() does but do not
445 capture the command output - the standard output is not redirected and goes
446 to the standard output of the caller application.
448 While the method is called command_noisy(), you might want to as well use
449 it for the most silent Git commands which you know will never pollute your
450 stdout but you want to avoid the overhead of the pipe setup when calling them.
452 The function returns only after the command has finished running.
454 =cut
456 sub command_noisy {
457 my ($self, $cmd, @args) = _maybe_self(@_);
458 _check_valid_cmd($cmd);
460 my $pid = fork;
461 if (not defined $pid) {
462 throw Error::Simple("fork failed: $!");
463 } elsif ($pid == 0) {
464 _cmd_exec($self, $cmd, @args);
466 if (waitpid($pid, 0) > 0 and $?>>8 != 0) {
467 throw Git::Error::Command(join(' ', $cmd, @args), $? >> 8);
472 =item version ()
474 Return the Git version in use.
476 =cut
478 sub version {
479 my $verstr = command_oneline('--version');
480 $verstr =~ s/^git version //;
481 $verstr;
485 =item exec_path ()
487 Return path to the Git sub-command executables (the same as
488 C<git --exec-path>). Useful mostly only internally.
490 =cut
492 sub exec_path { command_oneline('--exec-path') }
495 =item html_path ()
497 Return path to the Git html documentation (the same as
498 C<git --html-path>). Useful mostly only internally.
500 =cut
502 sub html_path { command_oneline('--html-path') }
505 =item repo_path ()
507 Return path to the git repository. Must be called on a repository instance.
509 =cut
511 sub repo_path { $_[0]->{opts}->{Repository} }
514 =item wc_path ()
516 Return path to the working copy. Must be called on a repository instance.
518 =cut
520 sub wc_path { $_[0]->{opts}->{WorkingCopy} }
523 =item wc_subdir ()
525 Return path to the subdirectory inside of a working copy. Must be called
526 on a repository instance.
528 =cut
530 sub wc_subdir { $_[0]->{opts}->{WorkingSubdir} ||= '' }
533 =item wc_chdir ( SUBDIR )
535 Change the working copy subdirectory to work within. The C<SUBDIR> is
536 relative to the working copy root directory (not the current subdirectory).
537 Must be called on a repository instance attached to a working copy
538 and the directory must exist.
540 =cut
542 sub wc_chdir {
543 my ($self, $subdir) = @_;
544 $self->wc_path()
545 or throw Error::Simple("bare repository");
547 -d $self->wc_path().'/'.$subdir
548 or throw Error::Simple("subdir not found: $!");
549 # Of course we will not "hold" the subdirectory so anyone
550 # can delete it now and we will never know. But at least we tried.
552 $self->{opts}->{WorkingSubdir} = $subdir;
556 =item config ( VARIABLE )
558 Retrieve the configuration C<VARIABLE> in the same manner as C<config>
559 does. In scalar context requires the variable to be set only one time
560 (exception is thrown otherwise), in array context returns allows the
561 variable to be set multiple times and returns all the values.
563 This currently wraps command('config') so it is not so fast.
565 =cut
567 sub config {
568 my ($self, $var) = _maybe_self(@_);
570 try {
571 my @cmd = ('config');
572 unshift @cmd, $self if $self;
573 if (wantarray) {
574 return command(@cmd, '--get-all', $var);
575 } else {
576 return command_oneline(@cmd, '--get', $var);
578 } catch Git::Error::Command with {
579 my $E = shift;
580 if ($E->value() == 1) {
581 # Key not found.
582 return;
583 } else {
584 throw $E;
590 =item config_bool ( VARIABLE )
592 Retrieve the bool configuration C<VARIABLE>. The return value
593 is usable as a boolean in perl (and C<undef> if it's not defined,
594 of course).
596 This currently wraps command('config') so it is not so fast.
598 =cut
600 sub config_bool {
601 my ($self, $var) = _maybe_self(@_);
603 try {
604 my @cmd = ('config', '--bool', '--get', $var);
605 unshift @cmd, $self if $self;
606 my $val = command_oneline(@cmd);
607 return undef unless defined $val;
608 return $val eq 'true';
609 } catch Git::Error::Command with {
610 my $E = shift;
611 if ($E->value() == 1) {
612 # Key not found.
613 return undef;
614 } else {
615 throw $E;
620 =item config_int ( VARIABLE )
622 Retrieve the integer configuration C<VARIABLE>. The return value
623 is simple decimal number. An optional value suffix of 'k', 'm',
624 or 'g' in the config file will cause the value to be multiplied
625 by 1024, 1048576 (1024^2), or 1073741824 (1024^3) prior to output.
626 It would return C<undef> if configuration variable is not defined,
628 This currently wraps command('config') so it is not so fast.
630 =cut
632 sub config_int {
633 my ($self, $var) = _maybe_self(@_);
635 try {
636 my @cmd = ('config', '--int', '--get', $var);
637 unshift @cmd, $self if $self;
638 return command_oneline(@cmd);
639 } catch Git::Error::Command with {
640 my $E = shift;
641 if ($E->value() == 1) {
642 # Key not found.
643 return undef;
644 } else {
645 throw $E;
650 =item get_colorbool ( NAME )
652 Finds if color should be used for NAMEd operation from the configuration,
653 and returns boolean (true for "use color", false for "do not use color").
655 =cut
657 sub get_colorbool {
658 my ($self, $var) = @_;
659 my $stdout_to_tty = (-t STDOUT) ? "true" : "false";
660 my $use_color = $self->command_oneline('config', '--get-colorbool',
661 $var, $stdout_to_tty);
662 return ($use_color eq 'true');
665 =item get_color ( SLOT, COLOR )
667 Finds color for SLOT from the configuration, while defaulting to COLOR,
668 and returns the ANSI color escape sequence:
670 print $repo->get_color("color.interactive.prompt", "underline blue white");
671 print "some text";
672 print $repo->get_color("", "normal");
674 =cut
676 sub get_color {
677 my ($self, $slot, $default) = @_;
678 my $color = $self->command_oneline('config', '--get-color', $slot, $default);
679 if (!defined $color) {
680 $color = "";
682 return $color;
685 =item remote_refs ( REPOSITORY [, GROUPS [, REFGLOBS ] ] )
687 This function returns a hashref of refs stored in a given remote repository.
688 The hash is in the format C<refname =\> hash>. For tags, the C<refname> entry
689 contains the tag object while a C<refname^{}> entry gives the tagged objects.
691 C<REPOSITORY> has the same meaning as the appropriate C<git-ls-remote>
692 argument; either an URL or a remote name (if called on a repository instance).
693 C<GROUPS> is an optional arrayref that can contain 'tags' to return all the
694 tags and/or 'heads' to return all the heads. C<REFGLOB> is an optional array
695 of strings containing a shell-like glob to further limit the refs returned in
696 the hash; the meaning is again the same as the appropriate C<git-ls-remote>
697 argument.
699 This function may or may not be called on a repository instance. In the former
700 case, remote names as defined in the repository are recognized as repository
701 specifiers.
703 =cut
705 sub remote_refs {
706 my ($self, $repo, $groups, $refglobs) = _maybe_self(@_);
707 my @args;
708 if (ref $groups eq 'ARRAY') {
709 foreach (@$groups) {
710 if ($_ eq 'heads') {
711 push (@args, '--heads');
712 } elsif ($_ eq 'tags') {
713 push (@args, '--tags');
714 } else {
715 # Ignore unknown groups for future
716 # compatibility
720 push (@args, $repo);
721 if (ref $refglobs eq 'ARRAY') {
722 push (@args, @$refglobs);
725 my @self = $self ? ($self) : (); # Ultra trickery
726 my ($fh, $ctx) = Git::command_output_pipe(@self, 'ls-remote', @args);
727 my %refs;
728 while (<$fh>) {
729 chomp;
730 my ($hash, $ref) = split(/\t/, $_, 2);
731 $refs{$ref} = $hash;
733 Git::command_close_pipe(@self, $fh, $ctx);
734 return \%refs;
738 =item ident ( TYPE | IDENTSTR )
740 =item ident_person ( TYPE | IDENTSTR | IDENTARRAY )
742 This suite of functions retrieves and parses ident information, as stored
743 in the commit and tag objects or produced by C<var GIT_type_IDENT> (thus
744 C<TYPE> can be either I<author> or I<committer>; case is insignificant).
746 The C<ident> method retrieves the ident information from C<git var>
747 and either returns it as a scalar string or as an array with the fields parsed.
748 Alternatively, it can take a prepared ident string (e.g. from the commit
749 object) and just parse it.
751 C<ident_person> returns the person part of the ident - name and email;
752 it can take the same arguments as C<ident> or the array returned by C<ident>.
754 The synopsis is like:
756 my ($name, $email, $time_tz) = ident('author');
757 "$name <$email>" eq ident_person('author');
758 "$name <$email>" eq ident_person($name);
759 $time_tz =~ /^\d+ [+-]\d{4}$/;
761 =cut
763 sub ident {
764 my ($self, $type) = _maybe_self(@_);
765 my $identstr;
766 if (lc $type eq lc 'committer' or lc $type eq lc 'author') {
767 my @cmd = ('var', 'GIT_'.uc($type).'_IDENT');
768 unshift @cmd, $self if $self;
769 $identstr = command_oneline(@cmd);
770 } else {
771 $identstr = $type;
773 if (wantarray) {
774 return $identstr =~ /^(.*) <(.*)> (\d+ [+-]\d{4})$/;
775 } else {
776 return $identstr;
780 sub ident_person {
781 my ($self, @ident) = _maybe_self(@_);
782 $#ident == 0 and @ident = $self ? $self->ident($ident[0]) : ident($ident[0]);
783 return "$ident[0] <$ident[1]>";
787 =item hash_object ( TYPE, FILENAME )
789 Compute the SHA1 object id of the given C<FILENAME> considering it is
790 of the C<TYPE> object type (C<blob>, C<commit>, C<tree>).
792 The method can be called without any instance or on a specified Git repository,
793 it makes zero difference.
795 The function returns the SHA1 hash.
797 =cut
799 # TODO: Support for passing FILEHANDLE instead of FILENAME
800 sub hash_object {
801 my ($self, $type, $file) = _maybe_self(@_);
802 command_oneline('hash-object', '-t', $type, $file);
806 =item hash_and_insert_object ( FILENAME )
808 Compute the SHA1 object id of the given C<FILENAME> and add the object to the
809 object database.
811 The function returns the SHA1 hash.
813 =cut
815 # TODO: Support for passing FILEHANDLE instead of FILENAME
816 sub hash_and_insert_object {
817 my ($self, $filename) = @_;
819 carp "Bad filename \"$filename\"" if $filename =~ /[\r\n]/;
821 $self->_open_hash_and_insert_object_if_needed();
822 my ($in, $out) = ($self->{hash_object_in}, $self->{hash_object_out});
824 unless (print $out $filename, "\n") {
825 $self->_close_hash_and_insert_object();
826 throw Error::Simple("out pipe went bad");
829 chomp(my $hash = <$in>);
830 unless (defined($hash)) {
831 $self->_close_hash_and_insert_object();
832 throw Error::Simple("in pipe went bad");
835 return $hash;
838 sub _open_hash_and_insert_object_if_needed {
839 my ($self) = @_;
841 return if defined($self->{hash_object_pid});
843 ($self->{hash_object_pid}, $self->{hash_object_in},
844 $self->{hash_object_out}, $self->{hash_object_ctx}) =
845 command_bidi_pipe(qw(hash-object -w --stdin-paths));
848 sub _close_hash_and_insert_object {
849 my ($self) = @_;
851 return unless defined($self->{hash_object_pid});
853 my @vars = map { 'hash_object_' . $_ } qw(pid in out ctx);
855 command_close_bidi_pipe(@$self{@vars});
856 delete @$self{@vars};
859 =item cat_blob ( SHA1, FILEHANDLE )
861 Prints the contents of the blob identified by C<SHA1> to C<FILEHANDLE> and
862 returns the number of bytes printed.
864 =cut
866 sub cat_blob {
867 my ($self, $sha1, $fh) = @_;
869 $self->_open_cat_blob_if_needed();
870 my ($in, $out) = ($self->{cat_blob_in}, $self->{cat_blob_out});
872 unless (print $out $sha1, "\n") {
873 $self->_close_cat_blob();
874 throw Error::Simple("out pipe went bad");
877 my $description = <$in>;
878 if ($description =~ / missing$/) {
879 carp "$sha1 doesn't exist in the repository";
880 return -1;
883 if ($description !~ /^[0-9a-fA-F]{40} \S+ (\d+)$/) {
884 carp "Unexpected result returned from git cat-file";
885 return -1;
888 my $size = $1;
890 my $blob;
891 my $bytesRead = 0;
893 while (1) {
894 my $bytesLeft = $size - $bytesRead;
895 last unless $bytesLeft;
897 my $bytesToRead = $bytesLeft < 1024 ? $bytesLeft : 1024;
898 my $read = read($in, $blob, $bytesToRead, $bytesRead);
899 unless (defined($read)) {
900 $self->_close_cat_blob();
901 throw Error::Simple("in pipe went bad");
904 $bytesRead += $read;
907 # Skip past the trailing newline.
908 my $newline;
909 my $read = read($in, $newline, 1);
910 unless (defined($read)) {
911 $self->_close_cat_blob();
912 throw Error::Simple("in pipe went bad");
914 unless ($read == 1 && $newline eq "\n") {
915 $self->_close_cat_blob();
916 throw Error::Simple("didn't find newline after blob");
919 unless (print $fh $blob) {
920 $self->_close_cat_blob();
921 throw Error::Simple("couldn't write to passed in filehandle");
924 return $size;
927 sub _open_cat_blob_if_needed {
928 my ($self) = @_;
930 return if defined($self->{cat_blob_pid});
932 ($self->{cat_blob_pid}, $self->{cat_blob_in},
933 $self->{cat_blob_out}, $self->{cat_blob_ctx}) =
934 command_bidi_pipe(qw(cat-file --batch));
937 sub _close_cat_blob {
938 my ($self) = @_;
940 return unless defined($self->{cat_blob_pid});
942 my @vars = map { 'cat_blob_' . $_ } qw(pid in out ctx);
944 command_close_bidi_pipe(@$self{@vars});
945 delete @$self{@vars};
949 { # %TEMP_* Lexical Context
951 my (%TEMP_FILEMAP, %TEMP_FILES);
953 =item temp_acquire ( NAME )
955 Attempts to retreive the temporary file mapped to the string C<NAME>. If an
956 associated temp file has not been created this session or was closed, it is
957 created, cached, and set for autoflush and binmode.
959 Internally locks the file mapped to C<NAME>. This lock must be released with
960 C<temp_release()> when the temp file is no longer needed. Subsequent attempts
961 to retrieve temporary files mapped to the same C<NAME> while still locked will
962 cause an error. This locking mechanism provides a weak guarantee and is not
963 threadsafe. It does provide some error checking to help prevent temp file refs
964 writing over one another.
966 In general, the L<File::Handle> returned should not be closed by consumers as
967 it defeats the purpose of this caching mechanism. If you need to close the temp
968 file handle, then you should use L<File::Temp> or another temp file faculty
969 directly. If a handle is closed and then requested again, then a warning will
970 issue.
972 =cut
974 sub temp_acquire {
975 my $temp_fd = _temp_cache(@_);
977 $TEMP_FILES{$temp_fd}{locked} = 1;
978 $temp_fd;
981 =item temp_release ( NAME )
983 =item temp_release ( FILEHANDLE )
985 Releases a lock acquired through C<temp_acquire()>. Can be called either with
986 the C<NAME> mapping used when acquiring the temp file or with the C<FILEHANDLE>
987 referencing a locked temp file.
989 Warns if an attempt is made to release a file that is not locked.
991 The temp file will be truncated before being released. This can help to reduce
992 disk I/O where the system is smart enough to detect the truncation while data
993 is in the output buffers. Beware that after the temp file is released and
994 truncated, any operations on that file may fail miserably until it is
995 re-acquired. All contents are lost between each release and acquire mapped to
996 the same string.
998 =cut
1000 sub temp_release {
1001 my ($self, $temp_fd, $trunc) = _maybe_self(@_);
1003 if (exists $TEMP_FILEMAP{$temp_fd}) {
1004 $temp_fd = $TEMP_FILES{$temp_fd};
1006 unless ($TEMP_FILES{$temp_fd}{locked}) {
1007 carp "Attempt to release temp file '",
1008 $temp_fd, "' that has not been locked";
1010 temp_reset($temp_fd) if $trunc and $temp_fd->opened;
1012 $TEMP_FILES{$temp_fd}{locked} = 0;
1013 undef;
1016 sub _temp_cache {
1017 my ($self, $name) = _maybe_self(@_);
1019 _verify_require();
1021 my $temp_fd = \$TEMP_FILEMAP{$name};
1022 if (defined $$temp_fd and $$temp_fd->opened) {
1023 if ($TEMP_FILES{$$temp_fd}{locked}) {
1024 throw Error::Simple("Temp file with moniker '" .
1025 $name . "' already in use");
1027 } else {
1028 if (defined $$temp_fd) {
1029 # then we're here because of a closed handle.
1030 carp "Temp file '", $name,
1031 "' was closed. Opening replacement.";
1033 my $fname;
1035 my $tmpdir;
1036 if (defined $self) {
1037 $tmpdir = $self->repo_path();
1040 ($$temp_fd, $fname) = File::Temp->tempfile(
1041 'Git_XXXXXX', UNLINK => 1, DIR => $tmpdir,
1042 ) or throw Error::Simple("couldn't open new temp file");
1044 $$temp_fd->autoflush;
1045 binmode $$temp_fd;
1046 $TEMP_FILES{$$temp_fd}{fname} = $fname;
1048 $$temp_fd;
1051 sub _verify_require {
1052 eval { require File::Temp; require File::Spec; };
1053 $@ and throw Error::Simple($@);
1056 =item temp_reset ( FILEHANDLE )
1058 Truncates and resets the position of the C<FILEHANDLE>.
1060 =cut
1062 sub temp_reset {
1063 my ($self, $temp_fd) = _maybe_self(@_);
1065 truncate $temp_fd, 0
1066 or throw Error::Simple("couldn't truncate file");
1067 sysseek($temp_fd, 0, SEEK_SET) and seek($temp_fd, 0, SEEK_SET)
1068 or throw Error::Simple("couldn't seek to beginning of file");
1069 sysseek($temp_fd, 0, SEEK_CUR) == 0 and tell($temp_fd) == 0
1070 or throw Error::Simple("expected file position to be reset");
1073 =item temp_path ( NAME )
1075 =item temp_path ( FILEHANDLE )
1077 Returns the filename associated with the given tempfile.
1079 =cut
1081 sub temp_path {
1082 my ($self, $temp_fd) = _maybe_self(@_);
1084 if (exists $TEMP_FILEMAP{$temp_fd}) {
1085 $temp_fd = $TEMP_FILEMAP{$temp_fd};
1087 $TEMP_FILES{$temp_fd}{fname};
1090 sub END {
1091 unlink values %TEMP_FILEMAP if %TEMP_FILEMAP;
1094 } # %TEMP_* Lexical Context
1096 =back
1098 =head1 ERROR HANDLING
1100 All functions are supposed to throw Perl exceptions in case of errors.
1101 See the L<Error> module on how to catch those. Most exceptions are mere
1102 L<Error::Simple> instances.
1104 However, the C<command()>, C<command_oneline()> and C<command_noisy()>
1105 functions suite can throw C<Git::Error::Command> exceptions as well: those are
1106 thrown when the external command returns an error code and contain the error
1107 code as well as access to the captured command's output. The exception class
1108 provides the usual C<stringify> and C<value> (command's exit code) methods and
1109 in addition also a C<cmd_output> method that returns either an array or a
1110 string with the captured command output (depending on the original function
1111 call context; C<command_noisy()> returns C<undef>) and $<cmdline> which
1112 returns the command and its arguments (but without proper quoting).
1114 Note that the C<command_*_pipe()> functions cannot throw this exception since
1115 it has no idea whether the command failed or not. You will only find out
1116 at the time you C<close> the pipe; if you want to have that automated,
1117 use C<command_close_pipe()>, which can throw the exception.
1119 =cut
1122 package Git::Error::Command;
1124 @Git::Error::Command::ISA = qw(Error);
1126 sub new {
1127 my $self = shift;
1128 my $cmdline = '' . shift;
1129 my $value = 0 + shift;
1130 my $outputref = shift;
1131 my(@args) = ();
1133 local $Error::Depth = $Error::Depth + 1;
1135 push(@args, '-cmdline', $cmdline);
1136 push(@args, '-value', $value);
1137 push(@args, '-outputref', $outputref);
1139 $self->SUPER::new(-text => 'command returned error', @args);
1142 sub stringify {
1143 my $self = shift;
1144 my $text = $self->SUPER::stringify;
1145 $self->cmdline() . ': ' . $text . ': ' . $self->value() . "\n";
1148 sub cmdline {
1149 my $self = shift;
1150 $self->{'-cmdline'};
1153 sub cmd_output {
1154 my $self = shift;
1155 my $ref = $self->{'-outputref'};
1156 defined $ref or undef;
1157 if (ref $ref eq 'ARRAY') {
1158 return @$ref;
1159 } else { # SCALAR
1160 return $$ref;
1165 =over 4
1167 =item git_cmd_try { CODE } ERRMSG
1169 This magical statement will automatically catch any C<Git::Error::Command>
1170 exceptions thrown by C<CODE> and make your program die with C<ERRMSG>
1171 on its lips; the message will have %s substituted for the command line
1172 and %d for the exit status. This statement is useful mostly for producing
1173 more user-friendly error messages.
1175 In case of no exception caught the statement returns C<CODE>'s return value.
1177 Note that this is the only auto-exported function.
1179 =cut
1181 sub git_cmd_try(&$) {
1182 my ($code, $errmsg) = @_;
1183 my @result;
1184 my $err;
1185 my $array = wantarray;
1186 try {
1187 if ($array) {
1188 @result = &$code;
1189 } else {
1190 $result[0] = &$code;
1192 } catch Git::Error::Command with {
1193 my $E = shift;
1194 $err = $errmsg;
1195 $err =~ s/\%s/$E->cmdline()/ge;
1196 $err =~ s/\%d/$E->value()/ge;
1197 # We can't croak here since Error.pm would mangle
1198 # that to Error::Simple.
1200 $err and croak $err;
1201 return $array ? @result : $result[0];
1205 =back
1207 =head1 COPYRIGHT
1209 Copyright 2006 by Petr Baudis E<lt>pasky@suse.czE<gt>.
1211 This module is free software; it may be used, copied, modified
1212 and distributed under the terms of the GNU General Public Licence,
1213 either version 2, or (at your option) any later version.
1215 =cut
1218 # Take raw method argument list and return ($obj, @args) in case
1219 # the method was called upon an instance and (undef, @args) if
1220 # it was called directly.
1221 sub _maybe_self {
1222 UNIVERSAL::isa($_[0], 'Git') ? @_ : (undef, @_);
1225 # Check if the command id is something reasonable.
1226 sub _check_valid_cmd {
1227 my ($cmd) = @_;
1228 $cmd =~ /^[a-z0-9A-Z_-]+$/ or throw Error::Simple("bad command: $cmd");
1231 # Common backend for the pipe creators.
1232 sub _command_common_pipe {
1233 my $direction = shift;
1234 my ($self, @p) = _maybe_self(@_);
1235 my (%opts, $cmd, @args);
1236 if (ref $p[0]) {
1237 ($cmd, @args) = @{shift @p};
1238 %opts = ref $p[0] ? %{$p[0]} : @p;
1239 } else {
1240 ($cmd, @args) = @p;
1242 _check_valid_cmd($cmd);
1244 my $fh;
1245 if ($^O eq 'MSWin32') {
1246 # ActiveState Perl
1247 #defined $opts{STDERR} and
1248 # warn 'ignoring STDERR option - running w/ ActiveState';
1249 $direction eq '-|' or
1250 die 'input pipe for ActiveState not implemented';
1251 # the strange construction with *ACPIPE is just to
1252 # explain the tie below that we want to bind to
1253 # a handle class, not scalar. It is not known if
1254 # it is something specific to ActiveState Perl or
1255 # just a Perl quirk.
1256 tie (*ACPIPE, 'Git::activestate_pipe', $cmd, @args);
1257 $fh = *ACPIPE;
1259 } else {
1260 my $pid = open($fh, $direction);
1261 if (not defined $pid) {
1262 throw Error::Simple("open failed: $!");
1263 } elsif ($pid == 0) {
1264 if (defined $opts{STDERR}) {
1265 close STDERR;
1267 if ($opts{STDERR}) {
1268 open (STDERR, '>&', $opts{STDERR})
1269 or die "dup failed: $!";
1271 _cmd_exec($self, $cmd, @args);
1274 return wantarray ? ($fh, join(' ', $cmd, @args)) : $fh;
1277 # When already in the subprocess, set up the appropriate state
1278 # for the given repository and execute the git command.
1279 sub _cmd_exec {
1280 my ($self, @args) = @_;
1281 if ($self) {
1282 $self->repo_path() and $ENV{'GIT_DIR'} = $self->repo_path();
1283 $self->repo_path() and $self->wc_path()
1284 and $ENV{'GIT_WORK_TREE'} = $self->wc_path();
1285 $self->wc_path() and chdir($self->wc_path());
1286 $self->wc_subdir() and chdir($self->wc_subdir());
1288 _execv_git_cmd(@args);
1289 die qq[exec "@args" failed: $!];
1292 # Execute the given Git command ($_[0]) with arguments ($_[1..])
1293 # by searching for it at proper places.
1294 sub _execv_git_cmd { exec('git', @_); }
1296 # Close pipe to a subprocess.
1297 sub _cmd_close {
1298 my ($fh, $ctx) = @_;
1299 if (not close $fh) {
1300 if ($!) {
1301 # It's just close, no point in fatalities
1302 carp "error closing pipe: $!";
1303 } elsif ($? >> 8) {
1304 # The caller should pepper this.
1305 throw Git::Error::Command($ctx, $? >> 8);
1307 # else we might e.g. closed a live stream; the command
1308 # dying of SIGPIPE would drive us here.
1313 sub DESTROY {
1314 my ($self) = @_;
1315 $self->_close_hash_and_insert_object();
1316 $self->_close_cat_blob();
1320 # Pipe implementation for ActiveState Perl.
1322 package Git::activestate_pipe;
1323 use strict;
1325 sub TIEHANDLE {
1326 my ($class, @params) = @_;
1327 # FIXME: This is probably horrible idea and the thing will explode
1328 # at the moment you give it arguments that require some quoting,
1329 # but I have no ActiveState clue... --pasky
1330 # Let's just hope ActiveState Perl does at least the quoting
1331 # correctly.
1332 my @data = qx{git @params};
1333 bless { i => 0, data => \@data }, $class;
1336 sub READLINE {
1337 my $self = shift;
1338 if ($self->{i} >= scalar @{$self->{data}}) {
1339 return undef;
1341 my $i = $self->{i};
1342 if (wantarray) {
1343 $self->{i} = $#{$self->{'data'}} + 1;
1344 return splice(@{$self->{'data'}}, $i);
1346 $self->{i} = $i + 1;
1347 return $self->{'data'}->[ $i ];
1350 sub CLOSE {
1351 my $self = shift;
1352 delete $self->{data};
1353 delete $self->{i};
1356 sub EOF {
1357 my $self = shift;
1358 return ($self->{i} >= scalar @{$self->{data}});
1362 1; # Famous last words