1Git::Repository(3) User Contributed Perl Documentation Git::Repository(3)
2
6 Git::Repository - Perl interface to Git repositories
7
9 use Git::Repository;
10 # start from an existing repository
12 $r = Git::Repository->new( git_dir => $gitdir );
13 # start from an existing working copy
15 $r = Git::Repository->new( work_tree => $dir );
16 # start from a repository reachable from the current directory
18 $r = Git::Repository->new();
19 # or init our own repository first
21 Git::Repository->run( init => $dir, ... );
22 $r = Git::Repository->new( work_tree => $dir );
23 # or clone from a URL first
25 Git::Repository->run( clone => $url, $dir, ... );
26 $r = Git::Repository->new( work_tree => $dir );
27 # provide an option hash for Git::Repository::Command
29 # (see Git::Repository::Command for all available options)
30 $r = Git::Repository->new( ..., \%options );
31 # run commands
33 # - get the full output (no errput) passing options for this command only
34 $output = $r->run( @cmd, \%options );
35 # - get the full output as a list of lines (no errput), with options
37 @output = $r->run( @cmd, \%options );
38 # - process the output with callbacks
40 $output = $r->run( @cmd, sub {...} );
41 @output = $r->run( @cmd, sub {...} );
42 # - obtain a Git::Repository::Command object
44 # (see Git::Repository::Command for details)
45 $cmd = $r->command( @cmd, \%options );
46 # obtain version information
48 my $version = $r->version();
49 # compare current git version
51 if ( $r->version_gt('1.6.5') ) {
52 ...;
53 }
54
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 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 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 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 Git::Repository requires at least Git 1.5.0, and is expected to support
77 any later version.
78 See Git::Repository::Tutorial for more code examples.
80
82 new
83 Git::Repository->new( %args, $options );
84 Create a new Git::Repository object, based on an existing Git
86 repository.
87 Parameters are:
89 git_dir => $gitdir
91 The location of the git repository (.git directory or equivalent).
92 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 work_tree => $dir
98 The location of the git working copy (for a non-bare repository).
99 If "work_tree" actually points to a subdirectory of the work tree,
101 Git::Repository will automatically recompute the proper value.
102 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 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 "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 So this:
117 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 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 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 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 To create a Git repository and obtain a Git::Repository object pointing
144 to it, simply do it in two steps:
145 # run a clone or init command without an instance,
147 # using options like cwd
148 Git::Repository->run( ... );
149 # obtain a Git::Repository instance
151 # on the resulting repository
152 $r = Git::Repository->new( ... );
153
155 Git::Repository supports the following methods:
156 command
158 Git::Repository->command( @cmd );
159 $r->command( @cmd );
160 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 As described in the Git::Repository::Command documentation, @cmd may
166 also contain a hashref containing options for the command.
167 run
169 Git::Repository->run( @cmd );
170 $r->run( @cmd );
171 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 Lines are automatically "chomp"ed.
177 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 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 The exit status of the command that was just run is accessible as usual
191 using "$? >> 8". See perlvar for details about $?.
192 git_dir
194 Returns the repository path.
195 work_tree
197 Returns the working copy path. Used as current working directory by
198 Git::Repository::Command.
199 options
201 Return the option hash that was passed to "Git::Repository->new()".
202 version
204 Return the version of git, as given by "git --version".
205 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 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 The methods are:
218 version_lt( $version )
220 version_gt( $version )
221 version_le( $version )
222 version_ge( $version )
223 version_eq( $version )
224 version_ne( $version )
225 All those methods also accept an option hash, just like the others.
227 The actual version-comparison logic is managed by
229 Git::Version::Compare. Check its documentation for details.
230
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 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 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 use Git::Repository qw( Hello );
245 my $r = Git::Repository->new();
247 print $r->hello();
248 print $r->hello_gitdir();
249 It's possible to load only a selection of methods from the plugin:
251 use Git::Repository [ Hello => 'hello' ];
253 my $r = Git::Repository->new();
255 print $r->hello();
256 # dies: Can't locate object method "hello_gitdir"
258 print $r->hello_gitdir();
259 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 use Git::Repository qw( +MyGit::Hello );
265 See Git::Repository::Plugin about how to create a new plugin.
267
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
275 (This section was written in June 2010. The other Git wrappers have
276 probably evolved since that time.)
277 A number of Perl git wrappers already exist. Why create a new one?
279 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 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 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 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 It doesn't allow calling "git init" or "git clone".
306 The "command_bidi_pipe" function especially has problems:
308 <http://kerneltrap.org/mailarchive/git/2008/10/24/3789584>
309 The Git module from git.git was packaged as a CPAN distribution by
311 MSOUTH in June 2013.
312 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 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 Git::Wrapper
324 Git::Wrapper doesn't support streams or bidirectional commands.
325 Git::Sub
327 (This description was added for completeness in May 2013.)
328 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 Git::Sub doesn't support working with streams.
335 Git::Raw
337 (This description was added for completeness in September 2014, upon
338 request of the author of Git::Raw.)
339 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
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 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
358 You can find documentation for this module with the perldoc command.
359 perldoc Git::Repository
361 You can also look for information at:
363 • RT: CPAN's request tracker
365 <http://rt.cpan.org/NoAuth/Bugs.html?Dist=Git-Repository>
367 • AnnoCPAN: Annotated CPAN documentation
369 <http://annocpan.org/dist/Git-Repository>
371 • CPAN Ratings
373 <http://cpanratings.perl.org/d/Git-Repository>
375 • Search CPAN
377 <http://search.cpan.org/dist/Git-Repository>
379
381 Philippe Bruhat (BooK) <book@cpan.org>
382
384 Copyright 2010-2016 Philippe Bruhat (BooK), all rights reserved.
385
387 This program is free software; you can redistribute it and/or modify it
388 under the same terms as Perl itself.
389perl v5.34.0 2021-07-22 Git::Repository(3)