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 <sven.kirmess@kzone.ch>

COPYRIGHT AND LICENSE

    This software is Copyright (c) 2021-2022 by Sven Kirmess.

    This is free software, licensed under:

      The (two-clause) FreeBSD License