/ 
Git-Repository-1.306
River stage two • 57 direct dependents • 85 total dependents
/ Git::Repository::Tutorial

NAME

Git::Repository::Tutorial - Control git from Perl using Git::Repository

VERSION

version 1.306

SYNOPSIS

use Git::Repository;

# do cool stuff with Git, using the following advice

HOW-TO

A Git::Repository object represents an actual Git repository, against which you can run commands.

Obtain a Git::Repository object from an existing repository

If your script is expected to run against a repository in the current directory (like most Git commands), let Git::Repository handle the magic:

$r = Git::Repository->new();

If the repository has a working copy (work tree):

$r = Git::Repository->new( work_tree => $dir );

If the repository is a bare repository, or you prefer to provide the .git directory location:

$r = Git::Repository->new( git_dir => $gitdir );

If the work tree and the git directory are in unrelated locations, you can also provide both:

$r = Git::Repository->new( work_tree => $dir, git_dir => $gitdir );

The constructor also accepts an option hash. The various options are detailed in the manual page for Git::Repository::Command.

Run any git command

Git commands can be run against an existing Git::Repository object, or against the class itself (in which case, git will try to deduce its context from the current directory and the environment).

The pattern for running commands is always the same:

$r->run( $command => @arguments, \%options );

The $command and @arguments are identical to those you'd pass to the git command-line tool. The options hash contains options, as described in the manual page for Git::Repository::Command.

Create a new repository

Sometime, you'll need to create the Git repository from scratch:

# git version 1.6.5 and above
Git::Repository->run( init => $dir );
$r = Git::Repository->new( work_tree => $dir );

# any older git requires the command to be run in the work tree,
# so we use the cwd option
Git::Repository->run( init => { cwd => $dir } );
$r = Git::Repository->new( work_tree => $dir );

Note that the old create() method is obsolete and has been removed.

Clone a repository

Cloning works the same way:

Git::Repository->run( clone => $url => $dir );
$r = Git::Repository->new( $dir );

Run a simple command

When you don't really care about the output of the command, just call it:

$r->run( add => '.' );
$r->run( commit => '-m', 'my commit message' );

In case of an error or warning, Git::Repository will croak() or carp() appropriately.

Silence warnings for some Git commands

Some Git porcelain commands provide additional information on STDERR. One typical example is git checkout:

$ git checkout mybranch
Switched to branch 'mybranch'

The run() method of Git::Repository treats all output on STDERR as a warning. Therefore, the following code:

$r->run( checkout => 'mybranch' );

will output a warning like this one:

Switched to branch 'mybranch' at myscript.pl line 10.

In such a case, you can use the quiet option to silence the warning for a single command:

$r->run( checkout => 'mybranch', { quiet => 1 } );

To silence all warnings, you can pass the quiet option during the creation of the original repository object:

my $r = Git::Repository->new( { quiet => 1 } );

This is not recommended, as it might hide important information from you.

Process normal and error output

The run() command doesn't capture STDERR: it only warns (or dies) if something was printed on it. To be able to actually capture error output, command() must be used.

my $cmd = $r->command( @cmd );
my @errput = $cmd->stderr->getlines();
$cmd->close;

run() also captures all output at once, which can lead to unnecessary memory consumption when capturing the output of some really verbose commands.

my $cmd = $r->command( log => '--pretty=oneline', '--all' );
my $log = $cmd->stdout;
while (<$log>) {
    ...;
}
$cmd->close;

Of course, as soon as one starts reading and writing to an external process' communication handles, a risk of blocking exists. Caveat emptor.

Provide input on standard input

Use the input option:

my $commit = $r->run( 'commit-tree', $tree, '-p', $parent,
    { input => $message } );

Change the environment of a command

Use the env option:

$r->run(
    'commit', '-m', 'log message',
    {   env => {
            GIT_COMMITTER_NAME  => 'Git::Repository',
            GIT_COMMITTER_EMAIL => 'book@cpan.org',
        },
    },
);

See Git::Repository::Command for other available options.

Ensure the output from Git commands is not localized

Since version 1.7.9, Git translates its most common interface messages into the user's language if translations are available and the locale is appropriately set.

This means that naively parsing the output "porcelain" commands might fail if the program is unexpectedly run under an unexpected locale.

The easiest way to ensure your Git commands will be run in a "locale-safe" environment, is to set the LC_ALL environment variable to C.

The brutal way:

$ENV{LC_ALL} = 'C';

The temporary way:

local $ENV{LC_ALL} = 'C';

The subtle way (restricted to the commands run on a given Git::Repository instance):

my $r = Git::Repository->new( { env => { LC_ALL => 'C' } } );

The stealthiest way (restricted to a single command):

$r->run( ..., { env => { LC_ALL => 'C' } } );

Ensure the Git commands are run from the current workding directory

By default, Git::Repository::Command will chdir() to the root of the work tree before launching the requested Git command.

This means that no matter where your program chdir() to, commands on the Git::Repository instance will by default be run from the root of the work tree. So, commands such as add need to use the "full" path (relative to GIT_WORK_TREE) of the files to be added.

The cwd option can be used to define where Git::Repository::Command will chdir() to. To instruct Git::Repository::Command to not chdir() (and therefore run the Git command from the current working directory), set the option to undef:

# run from cwd for this command only
$r->run( ..., { cwd => undef } );

# always run git from cwd
my $r = Git::Repository->new( { cwd => undef } );

Finely control when run() dies

By default, Git::Repository->run( ... ) dies if the Git command exited with a status code of 128 (fatal error) or 129 (usage message).

Some commands will throw an error and exit with a status different from the previous two:

$r->run( checkout => 'does-not-exist' );    # exit status: 1

The above run() call does not die, and output the following warning:

error: pathspec 'does-not-exist' did not match any file(s) known to git.

The exit status (as given by $? >> 8) is 1.

To force run() to die when the Git command exits with status 1, use the fatal option (added in version 1.304):

$r->run( checkout => 'does-not-exist', { fatal => 1 } );

By default, 128 and 129 remain in the list of fatal codes.

Here are a few examples:

# set the fatal codes for all call to run() on this object
$r = Git::Repository->new( { fatal => [ 1 .. 255 ] } );

As usual, setting the option to the Git::Repository object will set it for all commands run for it:

# "!0" is a shortcut for 1 .. 255
$r = Git::Repository->new( { fatal => [ "!0" ] } );

Using negative codes will make these values non-fatal:

# all exit codes are fatal, except 3 and 7
$r->run( ..., { fatal => [ -3, -7 ] } );

When the list contains a single item, there is no need to use an array reference:

# same as [ "!0" ]
$r = Git::Repository->new( { fatal => "!0" } );

# only 17 is fatal
$r->run( ..., { fatal => -17 } );

See Git::Repository::Command for other available options.

Process the output of git log

When creating a tool that needs to process the output of git log, you should always define precisely the expected format using the --pretty option, and choose a format that is easy to parse.

Assuming git log will output the default format will eventually lead to problems, for example when the user's git configuration defines format.pretty to be something else than the default of medium.

See also Git::Repository::Plugin::Log for adding to your Git::Repository objects a log() method that will parse the log output for you.

Process the output of git shortlog

git shortlog behaves differently when it detects it's not attached to a terminal. In that case, it just tries to read some git log output from its standard input.

So this oneliner will hang, because git shortlog is waiting for some data from the program connected to its standard input (the oneliner):

perl -MGit::Repository -le 'print scalar Git::Repository->run( shortlog => -5 )'

Whereas this one will "work" (as in "immediately return with no output"):

perl -MGit::Repository -le 'print scalar Git::Repository->run( shortlog => -5, { input => "" } )'

So, you need to give git shortlog some input (from git log):

perl -MGit::Repository -le 'print scalar Git::Repository->run( shortlog => { input => scalar Git::Repository->run( log => -5 ) } )'

If the log output is large, you'll probably be better off with something like the following:

use Git::Repository;

# start both git commands
my $log = Git::Repository->command('log')->stdout;
my $cmd = Git::Repository->command( shortlog => -ens );

# feed one with the output of the other
my $in = $cmd->stdin;
print {$in} $_ while <$log>;
close $in;

# and do something with the output
print $cmd->stdout->getlines;

Wrap git in a sudo call

If for a given repository you want to wrap all calls to git in a sudo call, you can use the git option with an array ref:

my $r = Git::Repository->new( { git => [qw( sudo -u nobody git )] } );

In this case, every call to git from $r will actually call sudo -u nobody git.

Use submodules

Because Git::Repository automatically sets the GIT_DIR and GIT_WORK_TREE environment variables, some submodule sub-commands may fail. For example:

$r->run( submodule => add => $repository => 'sub' );

will give the following error:

error: pathspec 'sub' did not match any file(s) known to git.

To avoid this error, you should enforce the removal of the GIT_WORK_TREE variable from the environment in which the command is run:

$r->run(
    submodule => add => $repository => 'sub',
    { env => { GIT_WORK_TREE => undef } }
);

Note that System::Command version 1.04 is required to be able to remove variables from the environment.

Sort git versions

Basically, you need to recreate the cmp operator for Git versions, using the private _version_gt() method (which accepts two parameters):

@sorted_versions = sort {
    Git::Repository::_version_gt( $a, $b )
        || -Git::Repository::_version_gt( $b, $a )
} @versions;

Add specialized methods to your Git::Repository objects

Have a look at Git::Repository::Plugin and Git::Repository::Plugin::Log, to learn how to add your own methods to Git::Repository.

BUGS

Please report any bugs or feature requests on the bugtracker website http://rt.cpan.org/NoAuth/Bugs.html?Dist=Git-Repository or by email to bug-git-repository@rt.cpan.org.

When submitting a bug or request, please include a test-file or a patch to an existing test-file that illustrates the bug or desired feature.

AUTHOR

Philippe Bruhat (BooK) <book@cpan.org>

COPYRIGHT

Copyright 2010-2013 Philippe Bruhat (BooK), all rights reserved.

LICENSE

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.