1Git::Repository::TutoriUasle(r3)Contributed Perl DocumenGtiatt:i:oRnepository::Tutorial(3)
2
6 Git::Repository::Tutorial - Control git from Perl using Git::Repository
7
9 use Git::Repository;
10 # do cool stuff with Git, using the following advice
12
14 A Git::Repository object represents an actual Git repository, against
15 which you can run commands.
16 Obtain a Git::Repository object from an existing repository
18 If your script is expected to run against a repository in the current
19 directory (like most Git commands), let Git::Repository handle the
20 magic:
21 $r = Git::Repository->new();
23 If the repository has a working copy (work tree):
25 $r = Git::Repository->new( work_tree => $dir );
27 If the repository is a bare repository, or you prefer to provide the
29 .git directory location:
30 $r = Git::Repository->new( git_dir => $gitdir );
32 If the work tree and the git directory are in unrelated locations, you
34 can also provide both:
35 $r = Git::Repository->new( work_tree => $dir, git_dir => $gitdir );
37 The constructor also accepts an option hash. The various options are
39 detailed in the manual page for Git::Repository::Command.
40 Run any git command
42 Git commands can be run against an existing Git::Repository object, or
43 against the class itself (in which case, git will try to deduce its
44 context from the current directory and the environment).
45 The pattern for running commands is always the same:
47 $r->run( $command => @arguments, \%options );
49 The $command and @arguments are identical to those you'd pass to the
51 "git" command-line tool. The options hash contains options, as
52 described in the manual page for Git::Repository::Command.
53 Create a new repository
55 Sometime, you'll need to create the Git repository from scratch:
56 # git version 1.6.5 and above
58 Git::Repository->run( init => $dir );
59 $r = Git::Repository->new( work_tree => $dir );
60 Any git older than 1.6.5 requires the command to be run in the work
62 tree, so we use the "cwd" option:
63 # git version 1.5.0.rc1 and above
65 Git::Repository->run( init => { cwd => $dir } );
66 $r = Git::Repository->new( work_tree => $dir );
67 # older git versions
69 Git::Repository->run( 'init-db' => { cwd => $dir } );
70 $r = Git::Repository->new( work_tree => $dir );
71 Note that the old "create()" method is obsolete (as of Git::Repository
73 1.18, from April 16, 2011) and has been removed (as of Git::Repository
74 1.301, January 21, 2013).
75 Clone a repository
77 Cloning works the same way:
78 Git::Repository->run( clone => $url => $dir );
80 $r = Git::Repository->new( work_tree => $dir );
81 Run a simple command
83 When you don't really care about the output of the command, just call
84 it:
85 $r->run( add => '.' );
87 $r->run( commit => '-m', 'my commit message' );
88 In case of an error or warning, Git::Repository will "croak()" or
90 "carp()" appropriately.
91 Properly quote options
93 It's common to work out the proper string of Git commands needed to
94 achieve your goal in the shell, before actually turning them into calls
95 to "Git::Repository->run".
96 Some options might require quoting, to properly get the arguments to
98 Git through the shell:
99 # shell
101 $ git log --since='Fri Jul 26 19:34:15 2013 +0200' --grep='report ticket'
102 Such quoting is of course not needed with Git::Repository:
104 $since = 'Fri Jul 26 19:34:15 2013 +0200';
106 $grep = 'report ticket';
107 my $cmd = $r->command( log => "--since=$since", "--grep=$grep" );
108 Be careful with spaces in options
110 For the same reasons as above (individual arguments to "run" or
111 "command" are turned into individual "argv" elements for git,
112 whitespace included), some command-line usages of git need to be
113 slightly reformatted to make them suitable for "run()".
114 For example, these two commands have the same effect when run from the
116 shell:
117 shell> git checkout -b sometopic
119 shell> git checkout -bsometopic
120 In the first case, git receives three arguments in "argv": "checkout",
122 "-b" and "sometopic". In the second case, it receives two arguments:
123 "checkout" and "-bsometopic", and then git recognizes the beginning of
124 the -b option and splits "sometopic" out of the second argument.
125 So, in a call such as:
127 $command = $repo->run( checkout => "-b$branch_name", { quiet => 0 } );
129 If $branch_name contains an initial space character, the call will be
131 equivalent the following shell command:
132 shell> git checkout -b\ sometopic
134 and git will receive two arguments: "checkout" and "-b sometopic", from
136 which it will split out " sometopic" (note the initial space).
137 The space after -b must be removed, as otherwise the code attempts to
139 create a branch called " sometopic", which git rejects.
140 Silence warnings for some Git commands
142 Some Git porcelain commands provide additional information on "STDERR".
143 One typical example is "git checkout":
144 $ git checkout mybranch
146 Switched to branch 'mybranch'
147 The "run()" method of Git::Repository treats all output on "STDERR" as
149 a warning. Therefore, the following code:
150 $r->run( checkout => 'mybranch' );
152 will output a warning like this one:
154 Switched to branch 'mybranch' at myscript.pl line 10.
156 In such a case, you can use the "quiet" option to silence the warning
158 for a single command:
159 $r->run( checkout => 'mybranch', { quiet => 1 } );
161 To silence all warnings, you can pass the "quiet" option during the
163 creation of the original repository object:
164 my $r = Git::Repository->new( { quiet => 1 } );
166 This is not recommended, as it might hide important information from
168 you.
169 Process normal and error output
171 The "run()" command doesn't capture "STDERR": it only warns (or dies)
172 if something was printed on it. To be able to actually capture error
173 output, "command()" must be used.
174 my $cmd = $r->command( @cmd );
176 my @errput = $cmd->stderr->getlines();
177 $cmd->close;
178 "run()" also captures all output at once, which can lead to unnecessary
180 memory consumption when capturing the output of some really verbose
181 commands.
182 my $cmd = $r->command( log => '--pretty=oneline', '--all' );
184 my $log = $cmd->stdout;
185 while (<$log>) {
186 ...;
187 }
188 $cmd->close;
189 Of course, as soon as one starts reading and writing to an external
191 process' communication handles, a risk of blocking exists. Caveat
192 emptor.
193 Provide input on standard input
195 Use the "input" option:
196 my $commit = $r->run( 'commit-tree', $tree, '-p', $parent,
198 { input => $message } );
199 Change the environment of a command
201 Use the "env" option:
202 $r->run(
204 'commit', '-m', 'log message',
205 { env => {
206 GIT_COMMITTER_NAME => 'Git::Repository',
207 GIT_COMMITTER_EMAIL => 'book@cpan.org',
208 },
209 },
210 );
211 Note that Git::Repository::Command does small changes to the
213 environment a command before running it. Specifically, it:
214 · deletes "GIT_DIR" and "GIT_WORK_TREE", and sets them to the
216 corresponding values from the current Git::Repository object
217 · deletes "TERM"
219 · replaces "PATH" with the value of the "env->{PATH}" option
221 The easiest way to preserve en environment variable is to pass it with
223 the "env" option, for example:
224 $r->run( qw( config --get-colorbool githooks.color true ),
226 { env => { TERM => $ENV{TERM} } } );
227 See Git::Repository::Command and System::Command for other available
229 options.
230 Ignore the system and global configuration files
232 Git has three levels of configuration files that can change the output
233 of porcelain commands: system ($(prefix)/etc/gitconfig), global
234 ($HOME/.gitconfig and $XDG_CONFIG_HOME/git/config) and local
235 (.git/config inside the repository).
236 To ensure the system and global configuration files will be ignored and
238 won't interfere with the expected output of your Git commands, you can
239 add the following keys to the "env" option:
240 GIT_CONFIG_NOSYSTEM => 1,
242 XDG_CONFIG_HOME => undef,
243 HOME => undef,
244 Ensure the output from Git commands is not localized
246 Since version 1.7.9, Git translates its most common interface messages
247 into the user's language if translations are available and the locale
248 is appropriately set.
249 This means that naively parsing the output "porcelain" commands might
251 fail if the program is unexpectedly run under an unexpected locale.
252 The easiest way to ensure your Git commands will be run in a "locale-
254 safe" environment, is to set the "LC_ALL" environment variable to "C".
255 The brutal way:
257 $ENV{LC_ALL} = 'C';
259 The temporary way:
261 local $ENV{LC_ALL} = 'C';
263 The subtle way (restricted to the commands run on a given
265 Git::Repository instance):
266 my $r = Git::Repository->new( { env => { LC_ALL => 'C' } } );
268 The stealthiest way (restricted to a single command):
270 $r->run( ..., { env => { LC_ALL => 'C' } } );
272 Ensure the Git commands are run from the current working directory
274 By default, Git::Repository::Command will "chdir()" to the root of the
275 work tree before launching the requested Git command.
276 This means that no matter where your program "chdir()" to, commands on
278 the Git::Repository instance will by default be run from the root of
279 the work tree. So, commands such as "add" need to use the "full" path
280 (relative to "GIT_WORK_TREE") of the files to be added.
281 The "cwd" option can be used to define where Git::Repository::Command
283 will "chdir()" to. To instruct Git::Repository::Command to not
284 "chdir()" (and therefore run the Git command from the current working
285 directory), set the option to "undef":
286 # run from cwd for this command only
288 $r->run( ..., { cwd => undef } );
289 # always run git from cwd
291 my $r = Git::Repository->new( { cwd => undef } );
292 Finely control when "run()" dies
294 By default, "Git::Repository->run( ... )" dies if the Git command
295 exited with a status code of 128 (fatal error) or 129 (usage message).
296 Some commands will throw an error and exit with a status different from
298 the previous two:
299 $r->run( checkout => 'does-not-exist' ); # exit status: 1
301 The above "run()" call does not die, and output the following warning:
303 error: pathspec 'does-not-exist' did not match any file(s) known to git.
305 The exit status (as given by "$? >> 8") is 1.
307 To force "run()" to die when the Git command exits with status 1, use
309 the "fatal" option (added in version 1.304, May 25, 2013):
310 $r->run( checkout => 'does-not-exist', { fatal => 1 } );
312 By default, 128 and 129 remain in the list of fatal codes.
314 Here are a few examples:
316 # set the fatal codes for all call to run() on this object
318 $r = Git::Repository->new( { fatal => [ 1 .. 255 ] } );
319 As usual, setting the option to the Git::Repository object will set it
321 for all commands run for it:
322 # "!0" is a shortcut for 1 .. 255
324 $r = Git::Repository->new( { fatal => [ "!0" ] } );
325 Using negative codes will make these values non-fatal:
327 # the above call to new() makes all exit codes fatal
329 # but 3 and 7 won't be fatal for this specific run
330 $r->run( ..., { fatal => [ -3, -7 ] } );
331 When the list contains a single item, there is no need to use an array
333 reference:
334 # same as [ "!0" ]
336 $r = Git::Repository->new( { fatal => "!0" } );
337 # remove 17 from the list of fatal exit codes for this run only
339 $r->run( ..., { fatal => -17 } );
340 See Git::Repository::Command for other available options.
342 Process the output of git log
344 When creating a tool that needs to process the output of git log, you
345 should always define precisely the expected format using the --pretty
346 option, and choose a format that is easy to parse.
347 Assuming git log will output the default format will eventually lead to
349 problems, for example when the user's git configuration defines
350 "format.pretty" to be something else than the default of "medium".
351 See also Git::Repository::Plugin::Log for adding to your
353 Git::Repository objects a "log()" method that will parse the log output
354 for you.
355 Understanding the various options for git log can make it very simple
357 to obtain a lot of information.
358 For example:
360 # all tags reachable from $committish
362 my @tags = map {
363 s/^ \((.*)\)/$1/;
364 ( map +( split /: / )[1], grep /^tag: /, split /, / )
365 }
366 $_->run( qw( log --simplify-by-decoration --pretty=%d ), $committish );
367 Process the output of git shortlog
369 git shortlog behaves differently when it detects it's not attached to a
370 terminal. In that case, it just tries to read some git log output from
371 its standard input.
372 So this oneliner will hang, because git shortlog is waiting for some
374 data from the program connected to its standard input (the oneliner):
375 perl -MGit::Repository -le 'print scalar Git::Repository->run( shortlog => -5 )'
377 Whereas this one will "work" (as in "immediately return with no
379 output"):
380 perl -MGit::Repository -le 'print scalar Git::Repository->run( shortlog => -5, { input => "" } )'
382 So, you need to give git shortlog some input (from git log):
384 perl -MGit::Repository -le 'print scalar Git::Repository->run( shortlog => { input => scalar Git::Repository->run( log => -5 ) } )'
386 If the log output is large, you'll probably be better off with
388 something like the following:
389 use Git::Repository;
391 # start both git commands
393 my $log = Git::Repository->command('log')->stdout;
394 my $cmd = Git::Repository->command( shortlog => -ens );
395 # feed one with the output of the other
397 my $in = $cmd->stdin;
398 print {$in} $_ while <$log>;
399 close $in;
400 # and do something with the output
402 print $cmd->stdout->getlines;
403 Wrap git in a sudo call
405 If for a given repository you want to wrap all calls to git in a "sudo"
406 call, you can use the "git" option with an array ref:
407 my $r = Git::Repository->new( { git => [qw( sudo -u nobody git )] } );
409 In this case, every call to git from $r will actually call "sudo -u
411 nobody git".
412 Use submodules
414 Because Git::Repository automatically sets the "GIT_DIR" and
415 "GIT_WORK_TREE" environment variables, some "submodule" sub-commands
416 may fail. For example:
417 $r->run( submodule => add => $repository => 'sub' );
419 will give the following error:
421 error: pathspec 'sub' did not match any file(s) known to git.
423 To avoid this error, you should enforce the removal of the
425 "GIT_WORK_TREE" variable from the environment in which the command is
426 run:
427 $r->run(
429 submodule => add => $repository => 'sub',
430 { env => { GIT_WORK_TREE => undef } }
431 );
432 Note that System::Command version 1.04 is required to be able to remove
434 variables from the environment.
435 Sort git versions
437 Since version 1.318, Git::Repository lets Git::Version::Compare handle
438 all version comparisons.
439 Sorting version numbers is therefore as simple as:
441 use Git::Version::Compare qw( cmp_git );
443 @sort_verson = sort cmp_git @versions;
445 Add specialized methods to your Git::Repository objects
447 Have a look at Git::Repository::Plugin and
448 Git::Repository::Plugin::Log, to learn how to add your own methods to
449 Git::Repository.
450 Run code on the output of a git command through callback
452 Sometimes you need to process the output of a command by running a
453 callback on each line of the output.
454 # code inspiration:
456 # https://github.com/dolmen/github-keygen/blob/24c501072ba7d890810de3008434c1fe1f757286/release.pl#L178
457 my %tree;
459 $r->run( 'ls-tree' => $commit, sub {
460 my ($mode, $type, $object, $file) = split;
461 $tree{$file} = [ $mode, $type, $object ];
462 } );
463 Note that the value returned by the callback will be returned as part
465 of the "run()" output, instead of the original line.
466 Initialize a test repository with a bundle
468 Instead of creating a test repository using a series of file editions
469 and commits, one can simply import data into the test repository using
470 a bundle. Bundles are created with the "git bundle create" command (see
471 the Git documentation for details).
472 First create a temporary repository with the help of Test::Git:
474 use Test::Git;
476 my $r = test_repository();
477 then import the bundle data in your repository, and collect the
479 references:
480 my @refs = $r->run( bundle => 'unbundle', $bundle_file );
482 and finally update the references:
484 for my $line (@refs) {
486 my ( $sha1, $ref ) = split / /, $line;
487 $r->run( 'update-ref', $ref => $sha1 );
488 }
489 Since Git version 1.6.5, it's also possible to clone directly from a
491 bundle (this creates an "origin" remote pointing to the bundle file):
492 my $r = test_repository( clone => [ $bundle_file ] );
494 A bundle from a recipient repository's point of view is just like a
496 regular remote repository. See the documentation of git bundle for
497 details of what's possible (e.g. incremental bundles).
498
500 Philippe Bruhat (BooK) <book@cpan.org>
501
503 Copyright 2010-2016 Philippe Bruhat (BooK), all rights reserved.
504
506 This program is free software; you can redistribute it and/or modify it
507 under the same terms as Perl itself.
508perl v5.28.1 2018-11-22 Git::Repository::Tutorial(3)