3 Git - Perl interface to the Git version control system
15 our ($VERSION, @ISA, @EXPORT, @EXPORT_OK);
17 # Totally unstable API.
25 my $version = Git::command_oneline('version');
27 Git::command_noisy('update-server-info');
29 my $repo = Git->repository (Directory => '/srv/git/cogito.git');
32 my @revs = $repo->command('rev-list', '--since=last monday', '--all');
34 my $fh = $repo->command_pipe('rev-list', '--since=last monday', '--all');
35 my $lastrev = <$fh>; chomp $lastrev;
36 close $fh; # You may want to test rev-list exit status here
38 my $lastrev = $repo->command_oneline('rev-list', '--all');
49 # Methods which can be called as standalone functions as well:
50 @EXPORT_OK = qw(command command_oneline command_pipe command_noisy
51 exec_path hash_object);
56 This module provides Perl scripts easy way to interface the Git version control
57 system. The modules have an easy and well-tested way to call arbitrary Git
58 commands; in the future, the interface will also provide specialized methods
59 for doing easily operations which are not totally trivial to do over
60 the generic command interface.
62 While some commands can be executed outside of any context (e.g. 'version'
63 or 'init-db'), most operations require a repository context, which in practice
64 means getting an instance of the Git object using the repository() constructor.
65 (In the future, we will also get a new_repository() constructor.) All commands
66 called as methods of the object are then executed in the context of the
69 TODO: In the future, we might also do
71 my $subdir = $repo->subdir('Documentation');
72 # Gets called in the subdirectory context:
73 $subdir->command('status');
75 my $remoterepo = $repo->remote_repository (Name => 'cogito', Branch => 'master');
76 $remoterepo ||= Git->remote_repository ('http://git.or.cz/cogito.git/');
77 my @refs = $remoterepo->refs();
79 So far, all functions just die if anything goes wrong. If you don't want that,
80 make appropriate provisions to catch the possible deaths. Better error recovery
81 mechanisms will be provided in the future.
83 Currently, the module merely wraps calls to external Git tools. In the future,
84 it will provide a much faster way to interact with Git by linking directly
85 to libgit. This should be completely opaque to the user, though (performance
86 increate nonwithstanding).
91 use Carp
qw(carp croak);
94 XSLoader
::load
('Git', $VERSION);
103 =item repository ( OPTIONS )
105 =item repository ( DIRECTORY )
109 Construct a new repository object.
110 C<OPTIONS> are passed in a hash like fashion, using key and value pairs.
111 Possible options are:
113 B<Repository> - Path to the Git repository.
115 B<WorkingCopy> - Path to the associated working copy; not strictly required
116 as many commands will happily crunch on a bare repository.
118 B<Directory> - Path to the Git working directory in its usual setup. This
119 is just for convenient setting of both C<Repository> and C<WorkingCopy>
120 at once: If the directory as a C<.git> subdirectory, C<Repository> is pointed
121 to the subdirectory and the directory is assumed to be the working copy.
122 If the directory does not have the subdirectory, C<WorkingCopy> is left
123 undefined and C<Repository> is pointed to the directory itself.
125 B<GitPath> - Path to the C<git> binary executable. By default the C<$PATH>
128 You should not use both C<Directory> and either of C<Repository> and
129 C<WorkingCopy> - the results of that are undefined.
131 Alternatively, a directory path may be passed as a single scalar argument
132 to the constructor; it is equivalent to setting only the C<Directory> option
135 Calling the constructor with no options whatsoever is equivalent to
136 calling it with C<< Directory => '.' >>.
146 if (defined $args[0]) {
147 if ($#args % 2 != 1) {
149 $#args == 0 or croak
"bad usage";
150 %opts = (Directory
=> $args[0]);
155 if ($opts{Directory
}) {
156 -d
$opts{Directory
} or croak
"Directory not found: $!";
157 if (-d
$opts{Directory
}."/.git") {
158 # TODO: Might make this more clever
159 $opts{WorkingCopy
} = $opts{Directory
};
160 $opts{Repository
} = $opts{Directory
}."/.git";
162 $opts{Repository
} = $opts{Directory
};
164 delete $opts{Directory
};
168 $self = { opts
=> \
%opts };
179 =item command ( COMMAND [, ARGUMENTS... ] )
181 Execute the given Git C<COMMAND> (specify it without the 'git-'
182 prefix), optionally with the specified extra C<ARGUMENTS>.
184 The method can be called without any instance or on a specified Git repository
185 (in that case the command will be run in the repository context).
187 In scalar context, it returns all the command output in a single string
190 In array context, it returns an array containing lines printed to the
191 command's stdout (without trailing newlines).
193 In both cases, the command's stdin and stderr are the same as the caller's.
198 my $fh = command_pipe
(@_);
200 if (not defined wantarray) {
203 } elsif (not wantarray) {
218 =item command_oneline ( COMMAND [, ARGUMENTS... ] )
220 Execute the given C<COMMAND> in the same way as command()
221 does but always return a scalar string containing the first line
222 of the command's standard output.
226 sub command_oneline
{
227 my $fh = command_pipe
(@_);
237 =item command_pipe ( COMMAND [, ARGUMENTS... ] )
239 Execute the given C<COMMAND> in the same way as command()
240 does but return a pipe filehandle from which the command output can be
246 my ($self, $cmd, @args) = _maybe_self
(@_);
248 $cmd =~ /^[a-z0-9A-Z_-]+$/ or croak
"bad command: $cmd";
250 my $pid = open(my $fh, "-|");
251 if (not defined $pid) {
252 croak
"open failed: $!";
253 } elsif ($pid == 0) {
254 _cmd_exec
($self, $cmd, @args);
260 =item command_noisy ( COMMAND [, ARGUMENTS... ] )
262 Execute the given C<COMMAND> in the same way as command() does but do not
263 capture the command output - the standard output is not redirected and goes
264 to the standard output of the caller application.
266 While the method is called command_noisy(), you might want to as well use
267 it for the most silent Git commands which you know will never pollute your
268 stdout but you want to avoid the overhead of the pipe setup when calling them.
270 The function returns only after the command has finished running.
275 my ($self, $cmd, @args) = _maybe_self
(@_);
277 $cmd =~ /^[a-z0-9A-Z_-]+$/ or croak
"bad command: $cmd";
280 if (not defined $pid) {
281 croak
"fork failed: $!";
282 } elsif ($pid == 0) {
283 _cmd_exec
($self, $cmd, @args);
285 if (waitpid($pid, 0) > 0 and $?
!= 0) {
286 croak
"exit status: $?";
293 Return path to the git sub-command executables (the same as
294 C<git --exec-path>). Useful mostly only internally.
296 Implementation of this function is very fast; no external command calls
301 # Implemented in Git.xs.
304 =item hash_object ( FILENAME [, TYPE ] )
306 =item hash_object ( FILEHANDLE [, TYPE ] )
308 Compute the SHA1 object id of the given C<FILENAME> (or data waiting in
309 C<FILEHANDLE>) considering it is of the C<TYPE> object type (C<blob>
310 (default), C<commit>, C<tree>).
312 In case of C<FILEHANDLE> passed instead of file name, all the data
313 available are read and hashed, and the filehandle is automatically
314 closed. The file handle should be freshly opened - if you have already
315 read anything from the file handle, the results are undefined (since
316 this function works directly with the file descriptor and internal
317 PerlIO buffering might have messed things up).
319 The method can be called without any instance or on a specified Git repository,
320 it makes zero difference.
322 The function returns the SHA1 hash.
324 Implementation of this function is very fast; no external command calls
329 # Implemented in Git.xs.
336 This is still fairly crude.
337 We need some good way to report errors back except just dying.
341 Copyright 2006 by Petr Baudis E<lt>pasky@suse.czE<gt>.
343 This module is free software; it may be used, copied, modified
344 and distributed under the terms of the GNU General Public Licence,
345 either version 2, or (at your option) any later version.
350 # Take raw method argument list and return ($obj, @args) in case
351 # the method was called upon an instance and (undef, @args) if
352 # it was called directly.
354 # This breaks inheritance. Oh well.
355 ref $_[0] eq 'Git' ?
@_ : (undef, @_);
358 # When already in the subprocess, set up the appropriate state
359 # for the given repository and execute the git command.
361 my ($self, @args) = @_;
363 $self->{opts
}->{Repository
} and $ENV{'GIT_DIR'} = $self->{opts
}->{Repository
};
364 $self->{opts
}->{WorkingCopy
} and chdir($self->{opts
}->{WorkingCopy
});
366 my $git = $self->{opts
}->{GitPath
};
368 exec ($git, @args) or croak
"exec failed: $!";
371 # Close pipe to a subprocess.
376 # It's just close, no point in fatalities
377 carp
"error closing pipe: $!";
379 croak
"exit status: ".($?
>> 8);
381 # else we might e.g. closed a live stream; the command
382 # dying of SIGPIPE would drive us here.
387 # Trickery for .xs routines: In order to avoid having some horrid
388 # C code trying to do stuff with undefs and hashes, we gate all
389 # xs calls through the following and in case we are being ran upon
390 # an instance call a C part of the gate which will set up the
391 # environment properly.
394 my ($self, @args) = _maybe_self
(@_);
397 # XXX: We ignore the WorkingCopy! To properly support
398 # that will require heavy changes in libgit.
400 # XXX: And we ignore everything else as well. libgit
401 # at least needs to be extended to let us specify
402 # the $GIT_DIR instead of looking it up in environment.
403 #xs_call_gate($self->{opts}->{Repository});
412 ($xsname = $AUTOLOAD) =~ s/.*:://;
413 croak
"&Git::$xsname not defined" if $xsname =~ /^xs_/;
414 $xsname = 'xs_'.$xsname;
415 _call_gate
(\
&$xsname, @_);
421 1; # Famous last words