NAME Git::Background - use Git commands with Future VERSION Version 0.005 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 COPYRIGHT AND LICENSE This software is Copyright (c) 2021-2022 by Sven Kirmess. This is free software, licensed under: The (two-clause) FreeBSD License