t7701-repack-unpack-unreachable.sh: check timestamp of unpacked objects
[git/git.git] / perl / Git.pm
CommitLineData
b1edc53d
PB
1=head1 NAME
2
3Git - Perl interface to the Git version control system
4
5=cut
6
7
8package Git;
9
10use strict;
11
12
13BEGIN {
14
15our ($VERSION, @ISA, @EXPORT, @EXPORT_OK);
16
17# Totally unstable API.
18$VERSION = '0.01';
19
20
21=head1 SYNOPSIS
22
23 use Git;
24
25 my $version = Git::command_oneline('version');
26
8b9150e3
PB
27 git_cmd_try { Git::command_noisy('update-server-info') }
28 '%s failed w/ code %d';
b1edc53d
PB
29
30 my $repo = Git->repository (Directory => '/srv/git/cogito.git');
31
32
33 my @revs = $repo->command('rev-list', '--since=last monday', '--all');
34
d79850e1 35 my ($fh, $c) = $repo->command_output_pipe('rev-list', '--since=last monday', '--all');
b1edc53d 36 my $lastrev = <$fh>; chomp $lastrev;
8b9150e3 37 $repo->command_close_pipe($fh, $c);
b1edc53d 38
d43ba468
PB
39 my $lastrev = $repo->command_oneline( [ 'rev-list', '--all' ],
40 STDERR => 0 );
b1edc53d 41
7182530d
AR
42 my $sha1 = $repo->hash_and_insert_object('file.txt');
43 my $tempfile = tempfile();
44 my $size = $repo->cat_blob($sha1, $tempfile);
45
b1edc53d
PB
46=cut
47
48
49require Exporter;
50
51@ISA = qw(Exporter);
52
8b9150e3 53@EXPORT = qw(git_cmd_try);
b1edc53d
PB
54
55# Methods which can be called as standalone functions as well:
d79850e1
PB
56@EXPORT_OK = qw(command command_oneline command_noisy
57 command_output_pipe command_input_pipe command_close_pipe
d1a29af9 58 command_bidi_pipe command_close_bidi_pipe
8b9150e3 59 version exec_path hash_object git_cmd_try);
b1edc53d
PB
60
61
62=head1 DESCRIPTION
63
64This module provides Perl scripts easy way to interface the Git version control
65system. The modules have an easy and well-tested way to call arbitrary Git
66commands; in the future, the interface will also provide specialized methods
67for doing easily operations which are not totally trivial to do over
68the generic command interface.
69
70While some commands can be executed outside of any context (e.g. 'version'
5c94f87e 71or 'init'), most operations require a repository context, which in practice
b1edc53d
PB
72means getting an instance of the Git object using the repository() constructor.
73(In the future, we will also get a new_repository() constructor.) All commands
74called as methods of the object are then executed in the context of the
75repository.
76
d5c7721d
PB
77Part of the "repository state" is also information about path to the attached
78working copy (unless you work with a bare repository). You can also navigate
79inside of the working copy using the C<wc_chdir()> method. (Note that
80the repository object is self-contained and will not change working directory
81of your process.)
b1edc53d 82
d5c7721d 83TODO: In the future, we might also do
b1edc53d
PB
84
85 my $remoterepo = $repo->remote_repository (Name => 'cogito', Branch => 'master');
86 $remoterepo ||= Git->remote_repository ('http://git.or.cz/cogito.git/');
87 my @refs = $remoterepo->refs();
88
b1edc53d
PB
89Currently, the module merely wraps calls to external Git tools. In the future,
90it will provide a much faster way to interact with Git by linking directly
91to libgit. This should be completely opaque to the user, though (performance
92increate nonwithstanding).
93
94=cut
95
96
8b9150e3 97use Carp qw(carp croak); # but croak is bad - throw instead
97b16c06 98use Error qw(:try);
d5c7721d 99use Cwd qw(abs_path);
d1a29af9 100use IPC::Open2 qw(open2);
b1edc53d 101
b1edc53d
PB
102}
103
104
105=head1 CONSTRUCTORS
106
107=over 4
108
109=item repository ( OPTIONS )
110
111=item repository ( DIRECTORY )
112
113=item repository ()
114
115Construct a new repository object.
116C<OPTIONS> are passed in a hash like fashion, using key and value pairs.
117Possible options are:
118
119B<Repository> - Path to the Git repository.
120
121B<WorkingCopy> - Path to the associated working copy; not strictly required
122as many commands will happily crunch on a bare repository.
123
d5c7721d
PB
124B<WorkingSubdir> - Subdirectory in the working copy to work inside.
125Just left undefined if you do not want to limit the scope of operations.
126
127B<Directory> - Path to the Git working directory in its usual setup.
128The C<.git> directory is searched in the directory and all the parent
129directories; if found, C<WorkingCopy> is set to the directory containing
130it and C<Repository> to the C<.git> directory itself. If no C<.git>
131directory was found, the C<Directory> is assumed to be a bare repository,
132C<Repository> is set to point at it and C<WorkingCopy> is left undefined.
133If the C<$GIT_DIR> environment variable is set, things behave as expected
134as well.
b1edc53d 135
b1edc53d
PB
136You should not use both C<Directory> and either of C<Repository> and
137C<WorkingCopy> - the results of that are undefined.
138
139Alternatively, a directory path may be passed as a single scalar argument
140to the constructor; it is equivalent to setting only the C<Directory> option
141field.
142
143Calling the constructor with no options whatsoever is equivalent to
d5c7721d
PB
144calling it with C<< Directory => '.' >>. In general, if you are building
145a standard porcelain command, simply doing C<< Git->repository() >> should
146do the right thing and setup the object to reflect exactly where the user
147is right now.
b1edc53d
PB
148
149=cut
150
151sub repository {
152 my $class = shift;
153 my @args = @_;
154 my %opts = ();
155 my $self;
156
157 if (defined $args[0]) {
158 if ($#args % 2 != 1) {
159 # Not a hash.
97b16c06
PB
160 $#args == 0 or throw Error::Simple("bad usage");
161 %opts = ( Directory => $args[0] );
b1edc53d
PB
162 } else {
163 %opts = @args;
164 }
d5c7721d
PB
165 }
166
167 if (not defined $opts{Repository} and not defined $opts{WorkingCopy}) {
168 $opts{Directory} ||= '.';
169 }
170
171 if ($opts{Directory}) {
172 -d $opts{Directory} or throw Error::Simple("Directory not found: $!");
173
174 my $search = Git->repository(WorkingCopy => $opts{Directory});
175 my $dir;
176 try {
177 $dir = $search->command_oneline(['rev-parse', '--git-dir'],
178 STDERR => 0);
179 } catch Git::Error::Command with {
180 $dir = undef;
181 };
b1edc53d 182
d5c7721d 183 if ($dir) {
71efe0ca
PB
184 $dir =~ m#^/# or $dir = $opts{Directory} . '/' . $dir;
185 $opts{Repository} = $dir;
d5c7721d
PB
186
187 # If --git-dir went ok, this shouldn't die either.
188 my $prefix = $search->command_oneline('rev-parse', '--show-prefix');
189 $dir = abs_path($opts{Directory}) . '/';
190 if ($prefix) {
191 if (substr($dir, -length($prefix)) ne $prefix) {
192 throw Error::Simple("rev-parse confused me - $dir does not have trailing $prefix");
193 }
194 substr($dir, -length($prefix)) = '';
b1edc53d 195 }
d5c7721d
PB
196 $opts{WorkingCopy} = $dir;
197 $opts{WorkingSubdir} = $prefix;
198
199 } else {
200 # A bare repository? Let's see...
201 $dir = $opts{Directory};
202
203 unless (-d "$dir/refs" and -d "$dir/objects" and -e "$dir/HEAD") {
204 # Mimick git-rev-parse --git-dir error message:
205 throw Error::Simple('fatal: Not a git repository');
206 }
207 my $search = Git->repository(Repository => $dir);
208 try {
209 $search->command('symbolic-ref', 'HEAD');
210 } catch Git::Error::Command with {
211 # Mimick git-rev-parse --git-dir error message:
212 throw Error::Simple('fatal: Not a git repository');
213 }
214
215 $opts{Repository} = abs_path($dir);
b1edc53d 216 }
d5c7721d
PB
217
218 delete $opts{Directory};
b1edc53d
PB
219 }
220
81a71734 221 $self = { opts => \%opts };
b1edc53d
PB
222 bless $self, $class;
223}
224
b1edc53d
PB
225=back
226
227=head1 METHODS
228
229=over 4
230
231=item command ( COMMAND [, ARGUMENTS... ] )
232
d43ba468
PB
233=item command ( [ COMMAND, ARGUMENTS... ], { Opt => Val ... } )
234
b1edc53d
PB
235Execute the given Git C<COMMAND> (specify it without the 'git-'
236prefix), optionally with the specified extra C<ARGUMENTS>.
237
d43ba468
PB
238The second more elaborate form can be used if you want to further adjust
239the command execution. Currently, only one option is supported:
240
241B<STDERR> - How to deal with the command's error output. By default (C<undef>)
242it is delivered to the caller's C<STDERR>. A false value (0 or '') will cause
243it to be thrown away. If you want to process it, you can get it in a filehandle
244you specify, but you must be extremely careful; if the error output is not
245very short and you want to read it in the same process as where you called
246C<command()>, you are set up for a nice deadlock!
247
b1edc53d
PB
248The method can be called without any instance or on a specified Git repository
249(in that case the command will be run in the repository context).
250
251In scalar context, it returns all the command output in a single string
252(verbatim).
253
254In array context, it returns an array containing lines printed to the
255command's stdout (without trailing newlines).
256
257In both cases, the command's stdin and stderr are the same as the caller's.
258
259=cut
260
261sub command {
d79850e1 262 my ($fh, $ctx) = command_output_pipe(@_);
b1edc53d
PB
263
264 if (not defined wantarray) {
8b9150e3
PB
265 # Nothing to pepper the possible exception with.
266 _cmd_close($fh, $ctx);
b1edc53d
PB
267
268 } elsif (not wantarray) {
269 local $/;
270 my $text = <$fh>;
8b9150e3
PB
271 try {
272 _cmd_close($fh, $ctx);
273 } catch Git::Error::Command with {
274 # Pepper with the output:
275 my $E = shift;
276 $E->{'-outputref'} = \$text;
277 throw $E;
278 };
b1edc53d
PB
279 return $text;
280
281 } else {
282 my @lines = <$fh>;
67e4baf8 283 defined and chomp for @lines;
8b9150e3
PB
284 try {
285 _cmd_close($fh, $ctx);
286 } catch Git::Error::Command with {
287 my $E = shift;
288 $E->{'-outputref'} = \@lines;
289 throw $E;
290 };
b1edc53d
PB
291 return @lines;
292 }
293}
294
295
296=item command_oneline ( COMMAND [, ARGUMENTS... ] )
297
d43ba468
PB
298=item command_oneline ( [ COMMAND, ARGUMENTS... ], { Opt => Val ... } )
299
b1edc53d
PB
300Execute the given C<COMMAND> in the same way as command()
301does but always return a scalar string containing the first line
302of the command's standard output.
303
304=cut
305
306sub command_oneline {
d79850e1 307 my ($fh, $ctx) = command_output_pipe(@_);
b1edc53d
PB
308
309 my $line = <$fh>;
d5c7721d 310 defined $line and chomp $line;
8b9150e3
PB
311 try {
312 _cmd_close($fh, $ctx);
313 } catch Git::Error::Command with {
314 # Pepper with the output:
315 my $E = shift;
316 $E->{'-outputref'} = \$line;
317 throw $E;
318 };
b1edc53d
PB
319 return $line;
320}
321
322
d79850e1 323=item command_output_pipe ( COMMAND [, ARGUMENTS... ] )
b1edc53d 324
d43ba468
PB
325=item command_output_pipe ( [ COMMAND, ARGUMENTS... ], { Opt => Val ... } )
326
b1edc53d
PB
327Execute the given C<COMMAND> in the same way as command()
328does but return a pipe filehandle from which the command output can be
329read.
330
d79850e1
PB
331The function can return C<($pipe, $ctx)> in array context.
332See C<command_close_pipe()> for details.
333
b1edc53d
PB
334=cut
335
d79850e1
PB
336sub command_output_pipe {
337 _command_common_pipe('-|', @_);
338}
b1edc53d 339
b1edc53d 340
d79850e1
PB
341=item command_input_pipe ( COMMAND [, ARGUMENTS... ] )
342
d43ba468
PB
343=item command_input_pipe ( [ COMMAND, ARGUMENTS... ], { Opt => Val ... } )
344
d79850e1
PB
345Execute the given C<COMMAND> in the same way as command_output_pipe()
346does but return an input pipe filehandle instead; the command output
347is not captured.
348
349The function can return C<($pipe, $ctx)> in array context.
350See C<command_close_pipe()> for details.
351
352=cut
353
354sub command_input_pipe {
355 _command_common_pipe('|-', @_);
8b9150e3
PB
356}
357
358
359=item command_close_pipe ( PIPE [, CTX ] )
360
d79850e1 361Close the C<PIPE> as returned from C<command_*_pipe()>, checking
3dff5379 362whether the command finished successfully. The optional C<CTX> argument
8b9150e3 363is required if you want to see the command name in the error message,
d79850e1 364and it is the second value returned by C<command_*_pipe()> when
8b9150e3
PB
365called in array context. The call idiom is:
366
d79850e1
PB
367 my ($fh, $ctx) = $r->command_output_pipe('status');
368 while (<$fh>) { ... }
369 $r->command_close_pipe($fh, $ctx);
8b9150e3
PB
370
371Note that you should not rely on whatever actually is in C<CTX>;
372currently it is simply the command name but in future the context might
373have more complicated structure.
374
375=cut
376
377sub command_close_pipe {
378 my ($self, $fh, $ctx) = _maybe_self(@_);
379 $ctx ||= '<unknown>';
380 _cmd_close($fh, $ctx);
b1edc53d
PB
381}
382
d1a29af9
AR
383=item command_bidi_pipe ( COMMAND [, ARGUMENTS... ] )
384
385Execute the given C<COMMAND> in the same way as command_output_pipe()
386does but return both an input pipe filehandle and an output pipe filehandle.
387
388The function will return return C<($pid, $pipe_in, $pipe_out, $ctx)>.
389See C<command_close_bidi_pipe()> for details.
390
391=cut
392
393sub command_bidi_pipe {
394 my ($pid, $in, $out);
395 $pid = open2($in, $out, 'git', @_);
396 return ($pid, $in, $out, join(' ', @_));
397}
398
399=item command_close_bidi_pipe ( PID, PIPE_IN, PIPE_OUT [, CTX] )
400
401Close the C<PIPE_IN> and C<PIPE_OUT> as returned from C<command_bidi_pipe()>,
402checking whether the command finished successfully. The optional C<CTX>
403argument is required if you want to see the command name in the error message,
404and it is the fourth value returned by C<command_bidi_pipe()>. The call idiom
405is:
406
407 my ($pid, $in, $out, $ctx) = $r->command_bidi_pipe('cat-file --batch-check');
408 print "000000000\n" $out;
409 while (<$in>) { ... }
410 $r->command_close_bidi_pipe($pid, $in, $out, $ctx);
411
412Note that you should not rely on whatever actually is in C<CTX>;
413currently it is simply the command name but in future the context might
414have more complicated structure.
415
416=cut
417
418sub command_close_bidi_pipe {
419 my ($pid, $in, $out, $ctx) = @_;
420 foreach my $fh ($in, $out) {
421 unless (close $fh) {
422 if ($!) {
423 carp "error closing pipe: $!";
424 } elsif ($? >> 8) {
425 throw Git::Error::Command($ctx, $? >>8);
426 }
427 }
428 }
429
430 waitpid $pid, 0;
431
432 if ($? >> 8) {
433 throw Git::Error::Command($ctx, $? >>8);
434 }
435}
436
b1edc53d
PB
437
438=item command_noisy ( COMMAND [, ARGUMENTS... ] )
439
440Execute the given C<COMMAND> in the same way as command() does but do not
441capture the command output - the standard output is not redirected and goes
442to the standard output of the caller application.
443
444While the method is called command_noisy(), you might want to as well use
445it for the most silent Git commands which you know will never pollute your
446stdout but you want to avoid the overhead of the pipe setup when calling them.
447
448The function returns only after the command has finished running.
449
450=cut
451
452sub command_noisy {
453 my ($self, $cmd, @args) = _maybe_self(@_);
d79850e1 454 _check_valid_cmd($cmd);
b1edc53d
PB
455
456 my $pid = fork;
457 if (not defined $pid) {
97b16c06 458 throw Error::Simple("fork failed: $!");
b1edc53d
PB
459 } elsif ($pid == 0) {
460 _cmd_exec($self, $cmd, @args);
461 }
8b9150e3
PB
462 if (waitpid($pid, 0) > 0 and $?>>8 != 0) {
463 throw Git::Error::Command(join(' ', $cmd, @args), $? >> 8);
b1edc53d
PB
464 }
465}
466
467
63df97ae
PB
468=item version ()
469
470Return the Git version in use.
471
63df97ae
PB
472=cut
473
18b0fc1c
PB
474sub version {
475 my $verstr = command_oneline('--version');
476 $verstr =~ s/^git version //;
477 $verstr;
478}
63df97ae
PB
479
480
eca1f6fd
PB
481=item exec_path ()
482
d5c7721d 483Return path to the Git sub-command executables (the same as
eca1f6fd
PB
484C<git --exec-path>). Useful mostly only internally.
485
eca1f6fd
PB
486=cut
487
18b0fc1c 488sub exec_path { command_oneline('--exec-path') }
eca1f6fd
PB
489
490
d5c7721d
PB
491=item repo_path ()
492
493Return path to the git repository. Must be called on a repository instance.
494
495=cut
496
497sub repo_path { $_[0]->{opts}->{Repository} }
498
499
500=item wc_path ()
501
502Return path to the working copy. Must be called on a repository instance.
503
504=cut
505
506sub wc_path { $_[0]->{opts}->{WorkingCopy} }
507
508
509=item wc_subdir ()
510
511Return path to the subdirectory inside of a working copy. Must be called
512on a repository instance.
513
514=cut
515
516sub wc_subdir { $_[0]->{opts}->{WorkingSubdir} ||= '' }
517
518
519=item wc_chdir ( SUBDIR )
520
521Change the working copy subdirectory to work within. The C<SUBDIR> is
522relative to the working copy root directory (not the current subdirectory).
523Must be called on a repository instance attached to a working copy
524and the directory must exist.
525
526=cut
527
528sub wc_chdir {
529 my ($self, $subdir) = @_;
d5c7721d
PB
530 $self->wc_path()
531 or throw Error::Simple("bare repository");
532
533 -d $self->wc_path().'/'.$subdir
534 or throw Error::Simple("subdir not found: $!");
535 # Of course we will not "hold" the subdirectory so anyone
536 # can delete it now and we will never know. But at least we tried.
537
538 $self->{opts}->{WorkingSubdir} = $subdir;
539}
540
541
dc2613de
PB
542=item config ( VARIABLE )
543
e0d10e1c 544Retrieve the configuration C<VARIABLE> in the same manner as C<config>
dc2613de
PB
545does. In scalar context requires the variable to be set only one time
546(exception is thrown otherwise), in array context returns allows the
547variable to be set multiple times and returns all the values.
548
e0d10e1c 549This currently wraps command('config') so it is not so fast.
dc2613de
PB
550
551=cut
552
553sub config {
c2e357c2 554 my ($self, $var) = _maybe_self(@_);
dc2613de
PB
555
556 try {
c2e357c2
FL
557 my @cmd = ('config');
558 unshift @cmd, $self if $self;
dc2613de 559 if (wantarray) {
c2e357c2 560 return command(@cmd, '--get-all', $var);
dc2613de 561 } else {
c2e357c2 562 return command_oneline(@cmd, '--get', $var);
dc2613de
PB
563 }
564 } catch Git::Error::Command with {
565 my $E = shift;
566 if ($E->value() == 1) {
567 # Key not found.
32d8050a 568 return;
dc2613de
PB
569 } else {
570 throw $E;
571 }
572 };
573}
574
575
35c49eea 576=item config_bool ( VARIABLE )
7b9a13ec 577
35c49eea
PB
578Retrieve the bool configuration C<VARIABLE>. The return value
579is usable as a boolean in perl (and C<undef> if it's not defined,
580of course).
7b9a13ec 581
7b9a13ec
TT
582This currently wraps command('config') so it is not so fast.
583
584=cut
585
35c49eea 586sub config_bool {
c2e357c2 587 my ($self, $var) = _maybe_self(@_);
7b9a13ec
TT
588
589 try {
c2e357c2
FL
590 my @cmd = ('config', '--bool', '--get', $var);
591 unshift @cmd, $self if $self;
592 my $val = command_oneline(@cmd);
35c49eea
PB
593 return undef unless defined $val;
594 return $val eq 'true';
7b9a13ec
TT
595 } catch Git::Error::Command with {
596 my $E = shift;
597 if ($E->value() == 1) {
598 # Key not found.
599 return undef;
600 } else {
601 throw $E;
602 }
603 };
604}
605
346d203b
JN
606=item config_int ( VARIABLE )
607
608Retrieve the integer configuration C<VARIABLE>. The return value
609is simple decimal number. An optional value suffix of 'k', 'm',
610or 'g' in the config file will cause the value to be multiplied
611by 1024, 1048576 (1024^2), or 1073741824 (1024^3) prior to output.
612It would return C<undef> if configuration variable is not defined,
613
346d203b
JN
614This currently wraps command('config') so it is not so fast.
615
616=cut
617
618sub config_int {
c2e357c2 619 my ($self, $var) = _maybe_self(@_);
346d203b
JN
620
621 try {
c2e357c2
FL
622 my @cmd = ('config', '--int', '--get', $var);
623 unshift @cmd, $self if $self;
624 return command_oneline(@cmd);
346d203b
JN
625 } catch Git::Error::Command with {
626 my $E = shift;
627 if ($E->value() == 1) {
628 # Key not found.
629 return undef;
630 } else {
631 throw $E;
632 }
633 };
634}
7b9a13ec 635
b4c61ed6
JH
636=item get_colorbool ( NAME )
637
638Finds if color should be used for NAMEd operation from the configuration,
639and returns boolean (true for "use color", false for "do not use color").
640
641=cut
642
643sub get_colorbool {
644 my ($self, $var) = @_;
645 my $stdout_to_tty = (-t STDOUT) ? "true" : "false";
646 my $use_color = $self->command_oneline('config', '--get-colorbool',
647 $var, $stdout_to_tty);
648 return ($use_color eq 'true');
649}
650
651=item get_color ( SLOT, COLOR )
652
653Finds color for SLOT from the configuration, while defaulting to COLOR,
654and returns the ANSI color escape sequence:
655
656 print $repo->get_color("color.interactive.prompt", "underline blue white");
657 print "some text";
658 print $repo->get_color("", "normal");
659
660=cut
661
662sub get_color {
663 my ($self, $slot, $default) = @_;
664 my $color = $self->command_oneline('config', '--get-color', $slot, $default);
665 if (!defined $color) {
666 $color = "";
667 }
668 return $color;
669}
670
c7a30e56
PB
671=item ident ( TYPE | IDENTSTR )
672
673=item ident_person ( TYPE | IDENTSTR | IDENTARRAY )
674
675This suite of functions retrieves and parses ident information, as stored
676in the commit and tag objects or produced by C<var GIT_type_IDENT> (thus
677C<TYPE> can be either I<author> or I<committer>; case is insignificant).
678
679The C<ident> method retrieves the ident information from C<git-var>
680and either returns it as a scalar string or as an array with the fields parsed.
681Alternatively, it can take a prepared ident string (e.g. from the commit
682object) and just parse it.
683
684C<ident_person> returns the person part of the ident - name and email;
685it can take the same arguments as C<ident> or the array returned by C<ident>.
686
687The synopsis is like:
688
689 my ($name, $email, $time_tz) = ident('author');
690 "$name <$email>" eq ident_person('author');
691 "$name <$email>" eq ident_person($name);
692 $time_tz =~ /^\d+ [+-]\d{4}$/;
693
c7a30e56
PB
694=cut
695
696sub ident {
44617928 697 my ($self, $type) = _maybe_self(@_);
c7a30e56
PB
698 my $identstr;
699 if (lc $type eq lc 'committer' or lc $type eq lc 'author') {
44617928
FL
700 my @cmd = ('var', 'GIT_'.uc($type).'_IDENT');
701 unshift @cmd, $self if $self;
702 $identstr = command_oneline(@cmd);
c7a30e56
PB
703 } else {
704 $identstr = $type;
705 }
706 if (wantarray) {
707 return $identstr =~ /^(.*) <(.*)> (\d+ [+-]\d{4})$/;
708 } else {
709 return $identstr;
710 }
711}
712
713sub ident_person {
44617928
FL
714 my ($self, @ident) = _maybe_self(@_);
715 $#ident == 0 and @ident = $self ? $self->ident($ident[0]) : ident($ident[0]);
c7a30e56
PB
716 return "$ident[0] <$ident[1]>";
717}
718
719
24c4b714 720=item hash_object ( TYPE, FILENAME )
b1edc53d 721
58c8dd21
LW
722Compute the SHA1 object id of the given C<FILENAME> considering it is
723of the C<TYPE> object type (C<blob>, C<commit>, C<tree>).
b1edc53d 724
b1edc53d
PB
725The method can be called without any instance or on a specified Git repository,
726it makes zero difference.
727
728The function returns the SHA1 hash.
729
b1edc53d
PB
730=cut
731
18b0fc1c 732# TODO: Support for passing FILEHANDLE instead of FILENAME
e6634ac9
PB
733sub hash_object {
734 my ($self, $type, $file) = _maybe_self(@_);
18b0fc1c 735 command_oneline('hash-object', '-t', $type, $file);
e6634ac9 736}
b1edc53d
PB
737
738
7182530d
AR
739=item hash_and_insert_object ( FILENAME )
740
741Compute the SHA1 object id of the given C<FILENAME> and add the object to the
742object database.
743
744The function returns the SHA1 hash.
745
746=cut
747
748# TODO: Support for passing FILEHANDLE instead of FILENAME
749sub hash_and_insert_object {
750 my ($self, $filename) = @_;
751
752 carp "Bad filename \"$filename\"" if $filename =~ /[\r\n]/;
753
754 $self->_open_hash_and_insert_object_if_needed();
755 my ($in, $out) = ($self->{hash_object_in}, $self->{hash_object_out});
756
757 unless (print $out $filename, "\n") {
758 $self->_close_hash_and_insert_object();
759 throw Error::Simple("out pipe went bad");
760 }
761
762 chomp(my $hash = <$in>);
763 unless (defined($hash)) {
764 $self->_close_hash_and_insert_object();
765 throw Error::Simple("in pipe went bad");
766 }
767
768 return $hash;
769}
770
771sub _open_hash_and_insert_object_if_needed {
772 my ($self) = @_;
773
774 return if defined($self->{hash_object_pid});
775
776 ($self->{hash_object_pid}, $self->{hash_object_in},
777 $self->{hash_object_out}, $self->{hash_object_ctx}) =
778 command_bidi_pipe(qw(hash-object -w --stdin-paths));
779}
780
781sub _close_hash_and_insert_object {
782 my ($self) = @_;
783
784 return unless defined($self->{hash_object_pid});
785
786 my @vars = map { 'hash_object_' . $_ } qw(pid in out ctx);
787
788 command_close_bidi_pipe($self->{@vars});
789 delete $self->{@vars};
790}
791
792=item cat_blob ( SHA1, FILEHANDLE )
793
794Prints the contents of the blob identified by C<SHA1> to C<FILEHANDLE> and
795returns the number of bytes printed.
796
797=cut
798
799sub cat_blob {
800 my ($self, $sha1, $fh) = @_;
801
802 $self->_open_cat_blob_if_needed();
803 my ($in, $out) = ($self->{cat_blob_in}, $self->{cat_blob_out});
804
805 unless (print $out $sha1, "\n") {
806 $self->_close_cat_blob();
807 throw Error::Simple("out pipe went bad");
808 }
809
810 my $description = <$in>;
811 if ($description =~ / missing$/) {
812 carp "$sha1 doesn't exist in the repository";
d683a0e0 813 return -1;
7182530d
AR
814 }
815
816 if ($description !~ /^[0-9a-fA-F]{40} \S+ (\d+)$/) {
817 carp "Unexpected result returned from git cat-file";
d683a0e0 818 return -1;
7182530d
AR
819 }
820
821 my $size = $1;
822
823 my $blob;
824 my $bytesRead = 0;
825
826 while (1) {
827 my $bytesLeft = $size - $bytesRead;
828 last unless $bytesLeft;
829
830 my $bytesToRead = $bytesLeft < 1024 ? $bytesLeft : 1024;
831 my $read = read($in, $blob, $bytesToRead, $bytesRead);
832 unless (defined($read)) {
833 $self->_close_cat_blob();
834 throw Error::Simple("in pipe went bad");
835 }
836
837 $bytesRead += $read;
838 }
839
840 # Skip past the trailing newline.
841 my $newline;
842 my $read = read($in, $newline, 1);
843 unless (defined($read)) {
844 $self->_close_cat_blob();
845 throw Error::Simple("in pipe went bad");
846 }
847 unless ($read == 1 && $newline eq "\n") {
848 $self->_close_cat_blob();
849 throw Error::Simple("didn't find newline after blob");
850 }
851
852 unless (print $fh $blob) {
853 $self->_close_cat_blob();
854 throw Error::Simple("couldn't write to passed in filehandle");
855 }
856
857 return $size;
858}
859
860sub _open_cat_blob_if_needed {
861 my ($self) = @_;
862
863 return if defined($self->{cat_blob_pid});
864
865 ($self->{cat_blob_pid}, $self->{cat_blob_in},
866 $self->{cat_blob_out}, $self->{cat_blob_ctx}) =
867 command_bidi_pipe(qw(cat-file --batch));
868}
869
870sub _close_cat_blob {
871 my ($self) = @_;
872
873 return unless defined($self->{cat_blob_pid});
874
875 my @vars = map { 'cat_blob_' . $_ } qw(pid in out ctx);
876
877 command_close_bidi_pipe($self->{@vars});
878 delete $self->{@vars};
879}
8b9150e3 880
b1edc53d
PB
881=back
882
97b16c06 883=head1 ERROR HANDLING
b1edc53d 884
97b16c06 885All functions are supposed to throw Perl exceptions in case of errors.
8b9150e3
PB
886See the L<Error> module on how to catch those. Most exceptions are mere
887L<Error::Simple> instances.
888
889However, the C<command()>, C<command_oneline()> and C<command_noisy()>
890functions suite can throw C<Git::Error::Command> exceptions as well: those are
891thrown when the external command returns an error code and contain the error
892code as well as access to the captured command's output. The exception class
893provides the usual C<stringify> and C<value> (command's exit code) methods and
894in addition also a C<cmd_output> method that returns either an array or a
895string with the captured command output (depending on the original function
896call context; C<command_noisy()> returns C<undef>) and $<cmdline> which
897returns the command and its arguments (but without proper quoting).
898
d79850e1 899Note that the C<command_*_pipe()> functions cannot throw this exception since
8b9150e3
PB
900it has no idea whether the command failed or not. You will only find out
901at the time you C<close> the pipe; if you want to have that automated,
902use C<command_close_pipe()>, which can throw the exception.
903
904=cut
905
906{
907 package Git::Error::Command;
908
909 @Git::Error::Command::ISA = qw(Error);
910
911 sub new {
912 my $self = shift;
913 my $cmdline = '' . shift;
914 my $value = 0 + shift;
915 my $outputref = shift;
916 my(@args) = ();
917
918 local $Error::Depth = $Error::Depth + 1;
919
920 push(@args, '-cmdline', $cmdline);
921 push(@args, '-value', $value);
922 push(@args, '-outputref', $outputref);
923
924 $self->SUPER::new(-text => 'command returned error', @args);
925 }
926
927 sub stringify {
928 my $self = shift;
929 my $text = $self->SUPER::stringify;
930 $self->cmdline() . ': ' . $text . ': ' . $self->value() . "\n";
931 }
932
933 sub cmdline {
934 my $self = shift;
935 $self->{'-cmdline'};
936 }
937
938 sub cmd_output {
939 my $self = shift;
940 my $ref = $self->{'-outputref'};
941 defined $ref or undef;
942 if (ref $ref eq 'ARRAY') {
943 return @$ref;
944 } else { # SCALAR
945 return $$ref;
946 }
947 }
948}
949
950=over 4
951
952=item git_cmd_try { CODE } ERRMSG
953
954This magical statement will automatically catch any C<Git::Error::Command>
955exceptions thrown by C<CODE> and make your program die with C<ERRMSG>
956on its lips; the message will have %s substituted for the command line
957and %d for the exit status. This statement is useful mostly for producing
958more user-friendly error messages.
959
960In case of no exception caught the statement returns C<CODE>'s return value.
961
962Note that this is the only auto-exported function.
963
964=cut
965
966sub git_cmd_try(&$) {
967 my ($code, $errmsg) = @_;
968 my @result;
969 my $err;
970 my $array = wantarray;
971 try {
972 if ($array) {
973 @result = &$code;
974 } else {
975 $result[0] = &$code;
976 }
977 } catch Git::Error::Command with {
978 my $E = shift;
979 $err = $errmsg;
980 $err =~ s/\%s/$E->cmdline()/ge;
981 $err =~ s/\%d/$E->value()/ge;
982 # We can't croak here since Error.pm would mangle
983 # that to Error::Simple.
984 };
985 $err and croak $err;
986 return $array ? @result : $result[0];
987}
988
989
990=back
b1edc53d
PB
991
992=head1 COPYRIGHT
993
994Copyright 2006 by Petr Baudis E<lt>pasky@suse.czE<gt>.
995
996This module is free software; it may be used, copied, modified
997and distributed under the terms of the GNU General Public Licence,
998either version 2, or (at your option) any later version.
999
1000=cut
1001
1002
1003# Take raw method argument list and return ($obj, @args) in case
1004# the method was called upon an instance and (undef, @args) if
1005# it was called directly.
1006sub _maybe_self {
1007 # This breaks inheritance. Oh well.
1008 ref $_[0] eq 'Git' ? @_ : (undef, @_);
1009}
1010
d79850e1
PB
1011# Check if the command id is something reasonable.
1012sub _check_valid_cmd {
1013 my ($cmd) = @_;
1014 $cmd =~ /^[a-z0-9A-Z_-]+$/ or throw Error::Simple("bad command: $cmd");
1015}
1016
1017# Common backend for the pipe creators.
1018sub _command_common_pipe {
1019 my $direction = shift;
d43ba468
PB
1020 my ($self, @p) = _maybe_self(@_);
1021 my (%opts, $cmd, @args);
1022 if (ref $p[0]) {
1023 ($cmd, @args) = @{shift @p};
1024 %opts = ref $p[0] ? %{$p[0]} : @p;
1025 } else {
1026 ($cmd, @args) = @p;
1027 }
d79850e1
PB
1028 _check_valid_cmd($cmd);
1029
a6065b54 1030 my $fh;
d3b1785f 1031 if ($^O eq 'MSWin32') {
a6065b54
PB
1032 # ActiveState Perl
1033 #defined $opts{STDERR} and
1034 # warn 'ignoring STDERR option - running w/ ActiveState';
1035 $direction eq '-|' or
1036 die 'input pipe for ActiveState not implemented';
bed118d6
AR
1037 # the strange construction with *ACPIPE is just to
1038 # explain the tie below that we want to bind to
1039 # a handle class, not scalar. It is not known if
1040 # it is something specific to ActiveState Perl or
1041 # just a Perl quirk.
1042 tie (*ACPIPE, 'Git::activestate_pipe', $cmd, @args);
1043 $fh = *ACPIPE;
a6065b54
PB
1044
1045 } else {
1046 my $pid = open($fh, $direction);
1047 if (not defined $pid) {
1048 throw Error::Simple("open failed: $!");
1049 } elsif ($pid == 0) {
1050 if (defined $opts{STDERR}) {
1051 close STDERR;
1052 }
1053 if ($opts{STDERR}) {
1054 open (STDERR, '>&', $opts{STDERR})
1055 or die "dup failed: $!";
1056 }
1057 _cmd_exec($self, $cmd, @args);
d43ba468 1058 }
d79850e1
PB
1059 }
1060 return wantarray ? ($fh, join(' ', $cmd, @args)) : $fh;
1061}
1062
b1edc53d
PB
1063# When already in the subprocess, set up the appropriate state
1064# for the given repository and execute the git command.
1065sub _cmd_exec {
1066 my ($self, @args) = @_;
1067 if ($self) {
d5c7721d
PB
1068 $self->repo_path() and $ENV{'GIT_DIR'} = $self->repo_path();
1069 $self->wc_path() and chdir($self->wc_path());
1070 $self->wc_subdir() and chdir($self->wc_subdir());
b1edc53d 1071 }
97b16c06 1072 _execv_git_cmd(@args);
6aaa65da 1073 die qq[exec "@args" failed: $!];
b1edc53d
PB
1074}
1075
8062f81c
PB
1076# Execute the given Git command ($_[0]) with arguments ($_[1..])
1077# by searching for it at proper places.
18b0fc1c 1078sub _execv_git_cmd { exec('git', @_); }
8062f81c 1079
b1edc53d
PB
1080# Close pipe to a subprocess.
1081sub _cmd_close {
8b9150e3 1082 my ($fh, $ctx) = @_;
b1edc53d
PB
1083 if (not close $fh) {
1084 if ($!) {
1085 # It's just close, no point in fatalities
1086 carp "error closing pipe: $!";
1087 } elsif ($? >> 8) {
8b9150e3
PB
1088 # The caller should pepper this.
1089 throw Git::Error::Command($ctx, $? >> 8);
b1edc53d
PB
1090 }
1091 # else we might e.g. closed a live stream; the command
1092 # dying of SIGPIPE would drive us here.
1093 }
1094}
1095
1096
7182530d
AR
1097sub DESTROY {
1098 my ($self) = @_;
1099 $self->_close_hash_and_insert_object();
1100 $self->_close_cat_blob();
1101}
b1edc53d
PB
1102
1103
a6065b54
PB
1104# Pipe implementation for ActiveState Perl.
1105
1106package Git::activestate_pipe;
1107use strict;
1108
1109sub TIEHANDLE {
1110 my ($class, @params) = @_;
1111 # FIXME: This is probably horrible idea and the thing will explode
1112 # at the moment you give it arguments that require some quoting,
1113 # but I have no ActiveState clue... --pasky
d3b1785f
AR
1114 # Let's just hope ActiveState Perl does at least the quoting
1115 # correctly.
1116 my @data = qx{git @params};
a6065b54
PB
1117 bless { i => 0, data => \@data }, $class;
1118}
1119
1120sub READLINE {
1121 my $self = shift;
1122 if ($self->{i} >= scalar @{$self->{data}}) {
1123 return undef;
1124 }
2f5b3980
AR
1125 my $i = $self->{i};
1126 if (wantarray) {
1127 $self->{i} = $#{$self->{'data'}} + 1;
1128 return splice(@{$self->{'data'}}, $i);
1129 }
1130 $self->{i} = $i + 1;
1131 return $self->{'data'}->[ $i ];
a6065b54
PB
1132}
1133
1134sub CLOSE {
1135 my $self = shift;
1136 delete $self->{data};
1137 delete $self->{i};
1138}
1139
1140sub EOF {
1141 my $self = shift;
1142 return ($self->{i} >= scalar @{$self->{data}});
1143}
1144
1145
b1edc53d 11461; # Famous last words