1Git::Wrapper(3) User Contributed Perl Documentation Git::Wrapper(3)
2
6 Git::Wrapper - Wrap git(7) command-line interface
7
9 version 0.048
10
12 my $git = Git::Wrapper->new('/var/foo');
13 $git->commit(...)
15 print $_->message for $git->log;
16 # 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
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
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 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 $git->commit({ message => "stuff" , all => 1 });
42 may produce this shell command:
44 git commit --all --message="stuff"
46 This code, however:
48 $git->commit(qw/ --message "stuff" / , { all => 1 });
50 will always produce this shell command:
52 git commit --message "stuff" --all
54 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 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 $git->command({ -foo => 1 , bar => 2 });
67 invokes the command line
69 git --foo=1 command --bar=2
71 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 $git->describe({ abbrev => ' 0' };
78 To pass content via STDIN, use the -STDIN option:
80 $git->hash_object({ stdin => 1, -STDIN => 'content to hash' });
82 Output is available as an array of lines, each chomped.
84 @sha1s_and_titles = $git->rev_list({ all => 1, pretty => 'oneline' });
86 Passing stringify-able objects as arguments
88 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 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 The error object has three useful methods:
103 • error
105 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 • output
112 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 • status
119 Returns the non-zero exit code reported by git on error.
121 Using Try::Tiny
123 Try::Tiny is the recommended way to catch exception objects thrown by
125 Git::Wrapper.
126 use Try::Tiny
128 my $git = Git::Wrapper->new('/path/to/my/repo');
130 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 # print STOUT from git command
140 print $_->output;
141 # print non-zero exist status of git processo
143 print $_->status;
144 # quotes are overloaded, so:
146 print "$_"; # equivalent to $_->error
147 };
148 Using "eval"
150 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 my $git = Git::Wrapper->new('/path/to/my/repo');
156 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 if ($@ and ref $@ eq q{Git::Wrapper::Exception}) {
164 # print STERR from erroneous git command
165 print $@->error;
166 # print STOUT from git command
168 print $@->output;
169 # print non-zero exist status of git processo
171 print $@->status;
172 # quotes are overloaded, so:
174 print "$@"; # equivalent to $@->error
175 }
176
178 new
179 my $git = Git::Wrapper->new($dir);
180 my $git = Git::Wrapper->new({ dir => $dir , git_binary => '/path/to/git' });
181 # To force the git binary location
183 my $git = Git::Wrapper->new($dir, 'git_binary' => '/usr/local/bin/git');
184 # 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 git
190 print $git->git; # /path/to/git/binary/being/used
191 dir
193 print $git->dir; # /var/foo
194 version
196 my $version = $git->version; # 1.6.1.4.8.15.16.23.42
197 branch
199 my @branches = $git->branch;
200 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 log
206 my @logs = $git->log;
207 Instead of giving back an arrayref of lines, the "log" method returns a
209 list of "Git::Wrapper::Log" objects.
210 There are five methods in a "Git::Wrapper::Log" objects:
212 • id
214 • author
216 • date
218 • message
220 • modifications
222 Only populated with when "raw => 1" option is set; see "Raw logs"
224 below.
225 Raw logs
227 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 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 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 Custom log formats
251 "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 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 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 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 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 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 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 my $statuses = $git->status;
292 Git::Wrapper:Statuses has two public methods. First, "is_dirty":
294 my $dirty_flag = $statuses->is_dirty;
296 which returns a true/false value depending on whether the repository
298 has any uncommitted changes.
299 Second, "get":
301 my @status = $statuses->get($group)
303 which returns an array of Git::Wrapper::Status objects, one per file
305 changed.
306 There are four status groups, each of which may contain zero or more
308 changes.
309 • indexed : Changed & added to the index (aka, will be committed)
311 • changed : Changed but not in the index (aka, won't be committed)
313 • unknown : Untracked files
315 • conflict : Merge conflicts
317 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 A Git::Wrapper::Status object has three methods you can call:
324 my $from = $status->from;
326 The file path of the changed file, relative to the repo root. For
328 renames, this is the original path.
329 my $to = $status->to;
331 Renames returns the new path/name for the path. In all other cases
333 returns an empty string.
334 my $mode = $status->mode;
336 Indicates what has changed about the file.
338 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 • modified
344 • added
346 • deleted
348 • renamed
350 • copied
352 • conflict
354 All files in the 'unknown' group will have a mode of 'unknown' (which
356 is redundant but at least consistent).
357 The 'conflict' group instead has the following modes.
359 • 'both deleted' : deleted on both branches
361 • 'both added' : added on both branches
363 • 'both modified' : modified on both branches
365 • 'added by us' : added only on our branch
367 • 'deleted by us' : deleted only on our branch
369 • 'added by them' : added on the branch we are merging in
371 • 'deleted by them' : deleted on the branch we are merging in
373 See git-status man page for more details.
375 Example
377 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 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 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 Example
406 my $git = Git::Wrapper->new( '/path/to/git/repo' );
408 # the 'log' method returns Git::Wrapper::Log objects
410 my @log_objects = $git->log();
411 # while 'RUN('log')' returns an array of chomped lines
413 my @log_lines = $git->RUN('log');
414 # getting the full of commit SHAs via `git log` by using the '--format' option
416 my @log_lines = $git->RUN('log', '--format=%H');
417 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 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 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
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
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
454 VCI::VCS::Git is the git implementation for VCI, a generic interface to
455 version-control systems.
456 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 Git itself is at <http://git.or.cz>.
463
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
473 • Hans Dieter Pearcey <hdp@cpan.org>
474 • Chris Prather <chris@prather.org>
476 • John SJ Anderson <genehack@genehack.org>
478
480 This software is copyright (c) 2014 by Hans Dieter Pearcey.
481 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.
484perl v5.32.1 2021-01-27 Git::Wrapper(3)