1Git::Repository(3)    User Contributed Perl Documentation   Git::Repository(3)
2
3
4

NAME

6       Git::Repository - Perl interface to Git repositories
7

SYNOPSIS

9           use Git::Repository;
10
11           # start from an existing repository
12           $r = Git::Repository->new( git_dir => $gitdir );
13
14           # start from an existing working copy
15           $r = Git::Repository->new( work_tree => $dir );
16
17           # start from a repository reachable from the current directory
18           $r = Git::Repository->new();
19
20           # or init our own repository first
21           Git::Repository->run( init => $dir, ... );
22           $r = Git::Repository->new( work_tree => $dir );
23
24           # or clone from a URL first
25           Git::Repository->run( clone => $url, $dir, ... );
26           $r = Git::Repository->new( work_tree => $dir );
27
28           # provide an option hash for Git::Repository::Command
29           # (see Git::Repository::Command for all available options)
30           $r = Git::Repository->new( ..., \%options );
31
32           # run commands
33           # - get the full output (no errput) passing options for this command only
34           $output = $r->run( @cmd, \%options );
35
36           # - get the full output as a list of lines (no errput), with options
37           @output = $r->run( @cmd, \%options );
38
39           # - process the output with callbacks
40           $output = $r->run( @cmd, sub {...} );
41           @output = $r->run( @cmd, sub {...} );
42
43           # - obtain a Git::Repository::Command object
44           #   (see Git::Repository::Command for details)
45           $cmd = $r->command( @cmd, \%options );
46
47           # obtain version information
48           my $version = $r->version();
49
50           # compare current git version
51           if ( $r->version_gt('1.6.5') ) {
52               ...;
53           }
54

DESCRIPTION

56       Git::Repository is a Perl interface to Git, for scripted interactions
57       with repositories. It's a low-level interface that allows calling any
58       Git command, whether porcelain or plumbing, including bidirectional
59       commands such as "git commit-tree".
60
61       A Git::Repository object simply provides context to the git commands
62       being run. It is possible to call the  "command()" and "run()" methods
63       against the class itself, and the context (typically current working
64       directory) will be obtained from the options and environment.
65
66       As a low-level interface, it provides no sugar for particular Git
67       commands. Specifically, it will not prepare environment variables that
68       individual Git commands may need or use.
69
70       However, the "GIT_DIR" and "GIT_WORK_TREE" environment variables are
71       special: if the command is run in the context of a Git::Repository
72       object, they will be overridden by the object's "git_dir" and
73       "work_tree" attributes, respectively. It is still possible to override
74       them if necessary, using the "env" option.
75
76       Git::Repository requires at least Git 1.5.0, and is expected to support
77       any later version.
78
79       See Git::Repository::Tutorial for more code examples.
80

CONSTRUCTOR

82   new
83           Git::Repository->new( %args, $options );
84
85       Create a new Git::Repository object, based on an existing Git
86       repository.
87
88       Parameters are:
89
90       git_dir => $gitdir
91           The location of the git repository (.git directory or equivalent).
92
93           For backward compatibility with versions 1.06 and before,
94           "repository" is accepted in place of "git_dir" (but the newer name
95           takes precedence).
96
97       work_tree => $dir
98           The location of the git working copy (for a non-bare repository).
99
100           If "work_tree" actually points to a subdirectory of the work tree,
101           Git::Repository will automatically recompute the proper value.
102
103           For backward compatibility with versions 1.06 and before,
104           "working_copy" is accepted in place of "work_tree" (but the newer
105           name takes precedence).
106
107       If none of the parameter is given, Git::Repository will find the
108       appropriate repository just like Git itself does. Otherwise, one of the
109       parameters is usually enough, as Git::Repository can work out where the
110       other directory (if any) is.
111
112       "new()" also accepts a reference to an option hash which will be used
113       as the default by Git::Repository::Command when working with the
114       corresponding Git::Repository instance.
115
116       So this:
117
118           my $r = Git::Repository->new(
119               # parameters
120               work_tree => $dir,
121               # options
122               {   git => '/path/to/some/other/git',
123                   env => {
124                       GIT_COMMITTER_EMAIL => 'book@cpan.org',
125                       GIT_COMMITTER_NAME  => 'Philippe Bruhat (BooK)',
126                   },
127               }
128           );
129
130       is equivalent to explicitly passing the option hash to each "run()" or
131       "command()" call.  The documentation for Git::Repository::Command lists
132       all available options.
133
134       Note that Git::Repository and Git::Repository::Command take great care
135       in finding the option hash wherever it may be in @_, and to merge
136       multiple option hashes if more than one is provided.
137
138       It probably makes no sense to set the "input" option in "new()", but
139       Git::Repository won't stop you.  Note that on some systems, some git
140       commands may close standard input on startup, which will cause a
141       "SIGPIPE". Git::Repository::Command will raise an exception.
142
143       To create a Git repository and obtain a Git::Repository object pointing
144       to it, simply do it in two steps:
145
146           # run a clone or init command without an instance,
147           # using options like cwd
148           Git::Repository->run( ... );
149
150           # obtain a Git::Repository instance
151           # on the resulting repository
152           $r = Git::Repository->new( ... );
153

METHODS

155       Git::Repository supports the following methods:
156
157   command
158           Git::Repository->command( @cmd );
159           $r->command( @cmd );
160
161       Runs the git sub-command and options, and returns a
162       Git::Repository::Command object pointing to the sub-process running the
163       command.
164
165       As described in the Git::Repository::Command documentation, @cmd may
166       also contain a hashref containing options for the command.
167
168   run
169           Git::Repository->run( @cmd );
170           $r->run( @cmd );
171
172       Runs the command and returns the output as a string in scalar context,
173       or as a list of lines in list context. Also accepts a hashref of
174       options.
175
176       Lines are automatically "chomp"ed.
177
178       In addition to the options hashref supported by
179       Git::Repository::Command, the parameter list can also contain code
180       references, that will be applied successively to each line of output.
181       The line being processed is in $_, but the coderef must still return
182       the result string (like "map").
183
184       If the git command printed anything on stderr, it will be printed as
185       warnings. For convenience, if the git sub-process exited with status
186       128 (fatal error), or 129 (usage message), "run()" will "die()".  The
187       exit status values for which "run()" dies can be modified using the
188       "fatal" option (see Git::Repository::Command for details).
189
190       The exit status of the command that was just run is accessible as usual
191       using "$? >> 8". See perlvar for details about $?.
192
193   git_dir
194       Returns the repository path.
195
196   work_tree
197       Returns the working copy path.  Used as current working directory by
198       Git::Repository::Command.
199
200   options
201       Return the option hash that was passed to "Git::Repository->new()".
202
203   version
204       Return the version of git, as given by "git --version".
205
206   Version-comparison "operators"
207       Git evolves very fast, and new features are constantly added.  To
208       facilitate the creation of programs that can properly handle the wide
209       variety of Git versions seen in the wild, a number of version
210       comparison "operators" are available.
211
212       They are named "version_op" where op is the equivalent of the Perl
213       operators "lt", "gt", "le", "ge", "eq", "ne". They return a boolean
214       value, obtained by comparing the version of the git binary and the
215       version string passed as parameter.
216
217       The methods are:
218
219       version_lt( $version )
220       version_gt( $version )
221       version_le( $version )
222       version_ge( $version )
223       version_eq( $version )
224       version_ne( $version )
225
226       All those methods also accept an option hash, just like the others.
227
228       The actual version-comparison logic is managed by
229       Git::Version::Compare.  Check its documentation for details.
230

PLUGIN SUPPORT

232       Git::Repository intentionally has only few methods.  The idea is to
233       provide a lightweight wrapper around git, to be used to create
234       interesting tools based on Git.
235
236       However, people will want to add extra functionality to
237       Git::Repository, the obvious example being a "log()" method that
238       returns simple objects with useful attributes.
239
240       Taking the hypothetical "Git::Repository::Plugin::Hello" module which
241       source code is listed in the previous reference, the methods it
242       provides would be loaded and used as follows:
243
244           use Git::Repository qw( Hello );
245
246           my $r = Git::Repository->new();
247           print $r->hello();
248           print $r->hello_gitdir();
249
250       It's possible to load only a selection of methods from the plugin:
251
252           use Git::Repository [ Hello => 'hello' ];
253
254           my $r = Git::Repository->new();
255           print $r->hello();
256
257           # dies: Can't locate object method "hello_gitdir"
258           print $r->hello_gitdir();
259
260       If your plugin lives in another namespace than
261       "Git::Repository::Plugin::", just prefix the fully qualified class name
262       with a "+". For example:
263
264           use Git::Repository qw( +MyGit::Hello );
265
266       See Git::Repository::Plugin about how to create a new plugin.
267

ACKNOWLEDGEMENTS

269       Thanks to Todd Rinaldo, who wanted to add more methods to
270       Git::Repository, which made me look for a solution that would preserve
271       the minimalism of Git::Repository. The "::Plugin" interface is what I
272       came up with.
273

OTHER PERL GIT WRAPPERS (a.k.a. SEE ALSO)

275       (This section was written in June 2010. The other Git wrappers have
276       probably evolved since that time.)
277
278       A number of Perl git wrappers already exist. Why create a new one?
279
280       I have a lot of ideas of nice things to do with Git as a tool to
281       manipulate blobs, trees, and tags, that may or may not represent
282       revision history of a project. A lot of those commands can output huge
283       amounts of data, which I need to be able to process in chunks.  Some of
284       these commands also expect to receive input.
285
286       What follows is a short list of "missing features" that I was looking
287       for when I looked at the existing Git wrappers on CPAN. They are the
288       "rational" reason for writing my own (the real reason being of course
289       "I thought it would be fun, and I enjoyed doing it").
290
291       Even though it works well for me and others, Git::Repository has its
292       own shortcomings: it is a low-level interface to Git commands, anything
293       complex requires you to deal with input/output handles, it provides no
294       high-level interface to generate actual Git commands or process the
295       output of commands (but have a look at the plugins), etc.  One the
296       following modules may therefore be better suited for your needs,
297       depending on what you're trying to achieve.
298
299   Git.pm
300       Git.pm was not on CPAN in 2010. It is packaged with Git, and installed
301       with the system Perl libraries. Not being on CPAN made it harder to
302       install in any Perl. It made it harder for a CPAN library to depend on
303       it.
304
305       It doesn't allow calling "git init" or "git clone".
306
307       The "command_bidi_pipe" function especially has problems:
308       <http://kerneltrap.org/mailarchive/git/2008/10/24/3789584>
309
310       The Git module from git.git was packaged as a CPAN distribution by
311       MSOUTH in June 2013.
312
313   Git::Class
314       Git::Class depends on Moose, which seems an unnecessary dependency for
315       a simple wrapper around Git. The startup penalty could become
316       significant for command-line tools.
317
318       Although it supports "git init" and "git clone" (and has methods to
319       call any Git command), it is mostly aimed at porcelain commands, and
320       provides no way to control bidirectional commands (such as "git
321       commit-tree").
322
323   Git::Wrapper
324       Git::Wrapper doesn't support streams or bidirectional commands.
325
326   Git::Sub
327       (This description was added for completeness in May 2013.)
328
329       Git::Sub appeared in 2013, as a set of Git-specific System::Sub
330       functions. It provide a nice set of "git::" functions, and has some
331       limitations (due to the way System::Sub itself works) which don't
332       impact most Git commands.
333
334       Git::Sub doesn't support working with streams.
335
336   Git::Raw
337       (This description was added for completeness in September 2014, upon
338       request of the author of Git::Raw.)
339
340       Git::Raw provides bindings to libgit2 <https://libgit2.github.io/>, a
341       pure C implementation of the Git core methods. Most of the functions
342       provided by libgit2 are available. If you have complex workflows, or
343       even if speed is of the essence, this may be a more attractive solution
344       than shelling out to git.
345

BUGS

347       Since version 1.17, Git::Repository delegates the actual command
348       execution to System::Command, which has better support for Win32 since
349       version 1.100.
350
351       Please report any bugs or feature requests to "bug-git-repository at
352       rt.cpan.org", or through the web interface at
353       <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Git-Repository>.  I
354       will be notified, and then you'll automatically be notified of progress
355       on your bug as I make changes.
356

SUPPORT

358       You can find documentation for this module with the perldoc command.
359
360           perldoc Git::Repository
361
362       You can also look for information at:
363
364       •   RT: CPAN's request tracker
365
366           <http://rt.cpan.org/NoAuth/Bugs.html?Dist=Git-Repository>
367
368       •   AnnoCPAN: Annotated CPAN documentation
369
370           <http://annocpan.org/dist/Git-Repository>
371
372       •   CPAN Ratings
373
374           <http://cpanratings.perl.org/d/Git-Repository>
375
376       •   Search CPAN
377
378           <http://search.cpan.org/dist/Git-Repository>
379

AUTHOR

381       Philippe Bruhat (BooK) <book@cpan.org>
382
384       Copyright 2010-2016 Philippe Bruhat (BooK), all rights reserved.
385

LICENSE

387       This program is free software; you can redistribute it and/or modify it
388       under the same terms as Perl itself.
389
390
391
392perl v5.32.1                      2021-01-30                Git::Repository(3)
Impressum