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

NAME

6       Git::Wrapper - Wrap git(7) command-line interface
7

VERSION

9       version 0.048
10

SYNOPSIS

12         my $git = Git::Wrapper->new('/var/foo');
13
14         $git->commit(...)
15         print $_->message for $git->log;
16
17         # specify which git binary to use
18         my $git = Git::Wrapper->new({
19           dir        => '/var/foo' ,
20           git_binary => '/path/to/git/bin/git' ,
21         });
22

DESCRIPTION

24       Git::Wrapper provides an API for git(7) that uses Perl data structures
25       for argument passing, instead of CLI-style "--options" as Git does.
26

METHOD INVOCATION

28       Except as documented, every git subcommand is available as a method on
29       a Git::Wrapper object. Replace any hyphens in the git command with
30       underscores (for example, "git init-db" would become "$git->init_db").
31
32   Method Arguments
33       Methods accept a combination of hashrefs and scalars, which is used to
34       build the command used to invoke git. Arguments passed in hashrefs will
35       be automatically parsed into option pairs, but the ordering of these in
36       the resulting shell command is not guaranteed (with the exception of
37       options with a leading '-'; see below). Options that are passed as
38       plain scalars will retain their order. Some examples may help clarify.
39       This code:
40
41         $git->commit({ message => "stuff" , all => 1 });
42
43       may produce this shell command:
44
45         git commit --all --message="stuff"
46
47       This code, however:
48
49         $git->commit(qw/ --message "stuff" / , { all => 1 });
50
51       will always produce this shell command:
52
53         git commit --message "stuff" --all
54
55       In most cases, this exact control over argument ordering is not needed
56       and simply passing all options as part of a hashref, and all other
57       options as additional list arguments, will be sufficient. In some
58       cases, however, the ordering of options to particular git sub-commands
59       is significant, resulting in the need for this level of control.
60
61       N.b. Options that are given with a leading '-' (with the exception of
62       special options noted below) are applied as arguments to the "git"
63       command itself; options without a leading '-' are applied as arguments
64       to the sub-command. For example:
65
66         $git->command({ -foo => 1 , bar => 2 });
67
68       invokes the command line
69
70         git --foo=1 command --bar=2
71
72       N.b. Because of the way arguments are parsed, should you need to pass
73       an explicit '0' value to an option (for example, to have the same
74       effect as "--abbrev=0" on the command line), you should pass it with a
75       leading space, like so:
76
77         $git->describe({ abbrev => ' 0' };
78
79       To pass content via STDIN, use the -STDIN option:
80
81         $git->hash_object({ stdin => 1, -STDIN => 'content to hash' });
82
83       Output is available as an array of lines, each chomped.
84
85         @sha1s_and_titles = $git->rev_list({ all => 1, pretty => 'oneline' });
86
87       Passing stringify-able objects as arguments
88
89       Objects may be passed in the place of scalars, assuming those objects
90       overload stringification in such a way as to produce a useful value.
91       However, relying on this stringification is discouraged and likely to
92       be officially deprecated in a subsequent release. Instead, if you have
93       an object that stringifies to a meaningful value (e.g., a Path::Class
94       object), you should stringify it yourself before passing it to
95       "Git::Wrapper" methods.
96
97   Error handling
98       If a git command exits nonzero, a "Git::Wrapper::Exception" object will
99       be thrown (via "die") and may be captured via "eval" or Try::Tiny, for
100       example.
101
102       The error object has three useful methods:
103
104       •   error
105
106           Returns the full error message reported by the resulting git
107           command sent to "STDERR". This method should not be used as a
108           success/failure check, as "git" will sometimes produce output on
109           STDERR when a command is successful.
110
111       •   output
112
113           Returns the full output generated by the git command that is sent
114           to "STDOUT".  This method should not be used as a success/failure
115           check, as "git" will frequently not have any output with a
116           successful command.
117
118       •   status
119
120           Returns the non-zero exit code reported by git on error.
121
122       Using Try::Tiny
123
124       Try::Tiny is the recommended way to catch exception objects thrown by
125       Git::Wrapper.
126
127         use Try::Tiny
128
129         my $git = Git::Wrapper->new('/path/to/my/repo');
130
131         try {
132           # equivalent to, "git --non-existent-option=1" on the commandline
133           $git->status({ "non-existent-option"=>1 });
134         }
135         catch {
136           # print STERR from erroneous git command
137           print $_->error;
138
139           # print STOUT from git command
140           print $_->output;
141
142           # print non-zero exist status of git processo
143           print $_->status;
144
145           # quotes are overloaded, so:
146           print "$_"; # equivalent to $_->error
147         };
148
149       Using "eval"
150
151       If for some reason you are unable to use Try::Tiny, it is also possible
152       to use the "eval" function to catch exception objects. THIS IS NOT
153       RECOMMENDED!
154
155         my $git = Git::Wrapper->new('/path/to/my/repo');
156
157         my $ok = eval {
158           # equivalent to, "git --non-existent-option=1" on the commandline
159           $git->status({ "non-existent-option"=>1 });
160           1;
161         };
162
163         if ($@ and ref $@ eq q{Git::Wrapper::Exception}) {
164           # print STERR from erroneous git command
165           print $@->error;
166
167           # print STOUT from git command
168           print $@->output;
169
170           # print non-zero exist status of git processo
171           print $@->status;
172
173           # quotes are overloaded, so:
174           print "$@"; # equivalent to $@->error
175         }
176

METHODS

178   new
179         my $git = Git::Wrapper->new($dir);
180         my $git = Git::Wrapper->new({ dir => $dir , git_binary => '/path/to/git' });
181
182         # To force the git binary location
183         my $git = Git::Wrapper->new($dir, 'git_binary' => '/usr/local/bin/git');
184
185         # prints the content of OUT and ERR to STDOUT and STDERR
186         # after a command is run
187         my $git = Git::Wrapper->new($dir, autoprint => 1);
188
189   git
190         print $git->git; # /path/to/git/binary/being/used
191
192   dir
193         print $git->dir; # /var/foo
194
195   version
196         my $version = $git->version; # 1.6.1.4.8.15.16.23.42
197
198   branch
199         my @branches = $git->branch;
200
201       This command intentionally disables ANSI color highlighting in the
202       output. If you want ANSI color highlighting, you'll need to bypass via
203       the RUN() method (see below).
204
205   log
206         my @logs = $git->log;
207
208       Instead of giving back an arrayref of lines, the "log" method returns a
209       list of "Git::Wrapper::Log" objects.
210
211       There are five methods in a "Git::Wrapper::Log" objects:
212
213       •   id
214
215       •   author
216
217       •   date
218
219       •   message
220
221       •   modifications
222
223           Only populated with when "raw => 1" option is set; see "Raw logs"
224           below.
225
226       Raw logs
227
228       Calling the "log" method with the "raw => 1" option set, as below, will
229       do additional parsing to populate the "modifications" attribute on each
230       "Git::Wrapper::Log" object. This method returns a list of
231       "Git::Wrapper::File::RawModification" objects, which can be used to get
232       filenames, permissions, and other metadata associated with individual
233       files in the given commit. A short example, to loop over all commits in
234       the log and print the filenames that were changed in each commit, one
235       filename per file:
236
237           my @logs = $git->log({ raw => 1 });
238           foreach my $log ( @logs ) {
239               say "In commit '" . $log->id . "', the following files changed:";
240               my @mods = $log->modifications;
241               foreach my $mod ( @mods ) {
242                   say "\t" . $mod->filename;
243               }
244           }
245
246       Note that some commits (e.g., merge commits) will not contain any file
247       changes. The "modifications" method will return an empty list in that
248       case.
249
250       Custom log formats
251
252       "log" will throw an exception if it is passed the "--format" option.
253       The reason for this has to do with the fact that the parsing of the
254       full log output into "Git::Wrapper::Log" objects assumes the default
255       format provided by `git` itself. Passing "--format" to the underlying
256       `git log` method affects this assumption and the output is no longer
257       able to be processed as intented.
258
259       If you wish to specify a custom log format, please use the RUN method
260       directly.  The caller will be supplied with the full log output. From
261       there, the caller may process the output as it wishes.
262
263   has_git_in_path
264       This method returns a true or false value indicating if there is a
265       'git' binary in the current $PATH.
266
267   supports_status_porcelain
268   supports_log_no_abbrev_commit
269   supports_log_no_expand_tabs
270   supports_log_raw_dates
271   supports_hash_object_filters
272       These methods return a true or false value (1 or 0) indicating whether
273       the git binary being used has support for these options. (The
274       '--porcelain' option on 'git status', the '--no-abbrev-commit',
275       '--no-expand-tabs', and '--date=raw' options on 'git log', and the
276       '--no-filters' option on 'git hash-object' respectively.)
277
278       These are primarily for use in this distribution's test suite, but may
279       also be useful when writing code using Git::Wrapper that might be run
280       with different versions of the underlying git binary.
281
282   status
283       When running with an underlying git binary that returns false for the
284       "supports_status_porcelain" method, this method will act like any other
285       wrapped command: it will return output as an array of chomped lines.
286
287       When running with an underlying git binary that returns true for the
288       "supports_status_porcelain" method, this method instead returns an
289       instance of Git::Wrapper::Statuses:
290
291         my $statuses = $git->status;
292
293       Git::Wrapper:Statuses has two public methods. First, "is_dirty":
294
295         my $dirty_flag = $statuses->is_dirty;
296
297       which returns a true/false value depending on whether the repository
298       has any uncommitted changes.
299
300       Second, "get":
301
302         my @status = $statuses->get($group)
303
304       which returns an array of Git::Wrapper::Status objects, one per file
305       changed.
306
307       There are four status groups, each of which may contain zero or more
308       changes.
309
310       •   indexed : Changed & added to the index (aka, will be committed)
311
312       •   changed : Changed but not in the index (aka, won't be committed)
313
314       •   unknown : Untracked files
315
316       •   conflict : Merge conflicts
317
318       Note that a single file can occur in more than one group. E.g., a
319       modified file that has been added to the index will appear in the
320       'indexed' list. If it is subsequently further modified it will
321       additionally appear in the 'changed' group.
322
323       A Git::Wrapper::Status object has three methods you can call:
324
325         my $from = $status->from;
326
327       The file path of the changed file, relative to the repo root. For
328       renames, this is the original path.
329
330         my $to = $status->to;
331
332       Renames returns the new path/name for the path. In all other cases
333       returns an empty string.
334
335         my $mode = $status->mode;
336
337       Indicates what has changed about the file.
338
339       Within each group (except 'conflict') a file can be in one of a number
340       of modes, although some modes only occur in some groups (e.g., 'added'
341       never appears in the 'unknown' group).
342
343       •   modified
344
345       •   added
346
347       •   deleted
348
349       •   renamed
350
351       •   copied
352
353       •   conflict
354
355       All files in the 'unknown' group will have a mode of 'unknown' (which
356       is redundant but at least consistent).
357
358       The 'conflict' group instead has the following modes.
359
360       •   'both deleted' : deleted on both branches
361
362       •   'both added'   : added on both branches
363
364       •   'both modified' : modified on both branches
365
366       •   'added by us'  : added only on our branch
367
368       •   'deleted by us' : deleted only on our branch
369
370       •   'added by them' : added on the branch we are merging in
371
372       •   'deleted by them' : deleted on the branch we are merging in
373
374       See git-status man page for more details.
375
376       Example
377
378           my $git = Git::Wrapper->new('/path/to/git/repo');
379           my $statuses = $git->status;
380           for my $type (qw<indexed changed unknown conflict>) {
381               my @states = $statuses->get($type)
382                   or next;
383               print "Files in state $type\n";
384               for (@states) {
385                   print '  ', $_->mode, ' ', $_->from;
386                   print ' renamed to ', $_->to
387                       if $_->mode eq 'renamed';
388                   print "\n";
389               }
390           }
391
392   RUN
393       This method bypasses the output rearranging performed by some of the
394       wrapped methods described above (i.e., "log", "status", etc.). This can
395       be useful in various situations, such as when you want to produce a
396       particular log output format that isn't compatible with the way
397       "Git::Wrapper" constructs "Git::Wrapper::Log", or when you want raw
398       "git status" output that isn't parsed into a "Git::Wrapper::Status"
399       object.
400
401       This method should be called with an initial string argument of the
402       "git" subcommand you want to run, followed by a hashref containing
403       options and their values, and then a list of any other arguments.
404
405       Example
406
407           my $git = Git::Wrapper->new( '/path/to/git/repo' );
408
409           # the 'log' method returns Git::Wrapper::Log objects
410           my @log_objects = $git->log();
411
412           # while 'RUN('log')' returns an array of chomped lines
413           my @log_lines = $git->RUN('log');
414
415           # getting the full of commit SHAs via `git log` by using the '--format' option
416           my @log_lines = $git->RUN('log', '--format=%H');
417
418   AUTOPRINT( $enabled )
419       If set to "true", the content of "OUT" and "ERR" will automatically be
420       printed on, respectively, STDOUT and STDERR after a command is run.
421
422   ERR
423       After a command has been run, this method will return anything that was
424       sent to "STDERR", in the form of an array of chomped lines. This
425       information will be cleared as soon as a new command is executed. This
426       method should *NOT* be used as a success/failure check, as "git" will
427       sometimes produce output on STDERR when a command is successful.
428
429   OUT
430       After a command has been run, this method will return anything that was
431       sent to "STDOUT", in the form of an array of chomped lines. It is
432       identical to what is returned from the method call that runs the
433       command, and is provided simply for symmetry with the "ERR" method.
434       This method should *NOT* be used as a success/failure check, as "git"
435       will frequently not have any output with a successful command.
436

COMPATIBILITY

438       On Win32 Git::Wrapper is incompatible with msysGit installations
439       earlier than Git-1.7.1-preview20100612 due to a bug involving the
440       return value of a git command in cmd/git.cmd. If you use the msysGit
441       version distributed with GitExtensions or an earlier version of
442       msysGit, tests will fail during installation of this module. You can
443       get the latest version of msysGit on the Google Code project page:
444       <http://code.google.com/p/msysgit/downloads>
445

ENVIRONMENT VARIABLES

447       Git::Wrapper normally uses the first 'git' binary in your path. The
448       original override provided to change this was by setting the
449       GIT_WRAPPER_GIT environment variable. Now that object creation accepts
450       an override, you are encouraged to instead pass the binary location
451       (git_binary) to new on object creation.
452

SEE ALSO

454       VCI::VCS::Git is the git implementation for VCI, a generic interface to
455       version-control systems.
456
457       Other Perl Git Wrappers
458       <https://metacpan.org/module/Git::Repository#OTHER-PERL-GIT-WRAPPERS>
459       is a list of other Git interfaces in Perl. If Git::Wrapper doesn't
460       scratch your itch, possibly one of the modules listed there will.
461
462       Git itself is at <http://git.or.cz>.
463

REPORTING BUGS & OTHER WAYS TO CONTRIBUTE

465       The code for this module is maintained on GitHub, at
466       <https://github.com/genehack/Git-Wrapper>. If you have a patch, feel
467       free to fork the repository and submit a pull request. If you find a
468       bug, please open an issue on the project at GitHub. (We also watch the
469       <http://rt.cpan.org> queue for Git::Wrapper, so feel free to use that
470       bug reporting system if you prefer)
471

AUTHORS

473       •   Hans Dieter Pearcey <hdp@cpan.org>
474
475       •   Chris Prather <chris@prather.org>
476
477       •   John SJ Anderson <genehack@genehack.org>
478
480       This software is copyright (c) 2014 by Hans Dieter Pearcey.
481
482       This is free software; you can redistribute it and/or modify it under
483       the same terms as the Perl 5 programming language system itself.
484
485
486
487perl v5.34.0                      2021-07-22                   Git::Wrapper(3)
Impressum