/ 
Git-Background-0.007
River stage one • 3 direct dependents • 3 total dependents
/ Git::Background

NAME

Git::Background - use Git commands with Future

VERSION

Version 0.007

SYNOPSIS

use Git::Background 0.002;

my $git = Git::Background->new($dir);
my $future = $git->run('status', '-s');
my @status = $future->stdout;

my $future = Git::Background->run('status', '-s', { dir => $dir });
my @status = $future->stdout;

USAGE

new( [DIR], [ARGS] )

Creates and returns a new Git::Background object. If you specify the dir positional argument, or use the dir argument in the args hash the directory is passed as cwd option to Proc::Background causing it to change into that directory before running the Git command.

Both, the dir positional argument and the args hash are optional. An exception is thrown if you specify both.

my $git = Git::Background->new;
my $git = Git::Background->new($dir);
my $git = Git::Background->new( { dir => $dir, fatal => 0 } );
my $git = Git::Background->new( $dir, { fatal => 0 } );

new either returns a valid Git::Background object or throws an exception.

The following options can be passed in the args hash to new. They are used as defaults for calls to run.

dir

This will be passed as cwd argument to Proc::Background whenever you call run. If you don't specify a dir all Git commands are executed in whatever the current working directory is when you call run.

fatal

Enabled by default. The fatal option controls if "await" in Git::Background::Future returns a failed Future when Git returns a non-zero return code.

Please not that "await" in Git::Background::Future always returns a failed Future if Git returns 128 (fatal Git error) or 129 (Git usage error) regardless of fatal. And a failed Future is returned if another error happens, e.g. if the output from Git cannot be read.

git

The Git command used to run. This defaults to git and lets Proc::Background work its magic to find the binary on your platform.

This can be either a string,

my $git = Git::Background->new( { git => '/opt/git/bin/git' } );

or an array ref.

my $git = Git::Background->new({
    git => [ qw( /usr/bin/sudo -u nobody git ) ],
});

run( @CMD, [ARGS] )

This runs the specified Git command in the background by passing it on to Git::Background. The last argument can be an argument hash that takes the same arguments as new.

my $git = Git::Background->new($dir);
my $future = $git->run('status', '-s', { fatal => 0 } );

if ( $future->await->is_failed ) {
    say q{Unable to run 'git status -s'};
}
else {
    my @status = $future->stdout;
}

The call returns a Git::Background::Future and the Git command runs in its own process. All output produced by Git is redirected to a File::Temp temporary file.

Proc::Background is run with autoterminate set, which will kill the Git process if the future is destroyed.

Since version 0.004 run croaks if it gets called in void context.

version( [ARGS] )

Returns the version of the used Git binary or undef if no Git command was found. This call uses the same, optional, argument hash as run. The call is wrapped in an eval which ensures that this method never throws an error and can be used to check if a Git is available.

my $version = Git::Background->version;
if ( !defined $version ) {
    say "No Git binary found.";
}
else {
    say "You have Git version $version";
}

EXAMPLES

Example 1 Clone a repository

Cloning a repository is a bit special as it's the only Git command that cannot be run in a workspace and the target directory must not exist.

There are two ways to use a Git::Background object without the workspace directory:

my $future = Git::Background->run('clone', $url, $dir);
$future->get;

# later, use a new object for working with the cloned repository
my $git = Git::Background->new($dir);
my $future = $git->run('status', '-s');
my @stdout = $future->stdout;

Alternatively you can overwrite the directory for the call to clone:

my $git = Git::Background->new($dir);
my $future = $git->run('clone', $url, $dir, { dir => undef });
$future->get;

# then use the same object for working with the cloned repository
my $future = $git->run('status', '-s');
my @dstdout = $future->stdout;

SEE ALSO

Git::Repository, Git::Wrapper, Future, Git::Version::Compare

SUPPORT

Bugs / Feature Requests

Please report any bugs or feature requests through the issue tracker at https://github.com/skirmess/Git-Background/issues. You will be notified automatically of any progress on your issue.

Source Code

This is open source software. The code repository is available for public review and contribution under the terms of the license.

https://github.com/skirmess/Git-Background

git clone https://github.com/skirmess/Git-Background.git

AUTHOR

Sven Kirmess <sven.kirmess@kzone.ch>