=head1 NAME

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

=head1 SYNOPSIS

    use Git::Repository;

    # do cool stuff with Git, using the following advice

=head1 HOW-TO

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

=head2 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 L<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 );

In this case, the git dir is computed as the output of
C<git rev-parse --git-dir>, and the the work tree is normalized using
C<git rev-parse --show-cdup>. To force the use of a different work tree,
set the C<GIT_WORK_TREE> environment variable in the option hash.

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

    $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 L<Git::Repository::Command>.

=head2 Run any git command

Git commands can be run against an existing L<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 C<$command> and C<@arguments> are identical to those you'd pass to
the C<git> command-line tool. The options hash contains options, as
described in the manual page for L<Git::Repository::Command>.

=head2 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 git older than 1.6.5 requires the command to be run in the work tree,
so we use the C<cwd> option:

    # git version 1.5.0.rc1 and above
    Git::Repository->run( init => { cwd => $dir } );
    $r = Git::Repository->new( work_tree => $dir );

    # older git versions
    Git::Repository->run( 'init-db' => { cwd => $dir } );
    $r = Git::Repository->new( work_tree => $dir );

Note that the old C<create()> method
is obsolete (as of L<Git::Repository> 1.18, from April 16, 2011)
and has been removed (as of L<Git::Repository> 1.301, January 21, 2013).

=head2 Clone a repository

Cloning works the same way:

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

=head2 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, L<Git::Repository> will C<croak()> or
C<carp()> appropriately.

=head2 Properly quote options

It's common to work out the proper string of Git commands needed to
achieve your goal in the shell, before actually turning them into calls
to C<< Git::Repository->run >>.

Some options might require quoting, to properly get the arguments to
Git through the shell:

    # shell
    $ git log --since='Fri Jul 26 19:34:15 2013 +0200' --grep='report ticket'

Such quoting is of course not needed with L<Git::Repository>:

    $since = 'Fri Jul 26 19:34:15 2013 +0200';
    $grep  = 'report ticket';
    my $cmd = $r->command( log => "--since=$since", "--grep=$grep" );

=head2 Be careful with spaces in options

For the same reasons as above (individual arguments to C<run> or
C<command> are turned into individual C<argv> elements for B<git>,
whitespace included),
some command-line usages of B<git> need to be slightly reformatted to
make them suitable for C<run()>.

For example, these two commands have the same effect when run from the shell:

	shell> git checkout -b sometopic
	shell> git checkout -bsometopic

In the first case, B<git> receives three arguments in C<argv>: C<checkout>,
C<-b> and C<sometopic>. In the second case, it receives two arguments:
C<checkout> and C<-bsometopic>, and then B<git> recognizes the beginning
of the I<-b> option and splits C<sometopic> out of the second argument.

So, in a call such as:

    $command = $repo->run( checkout => "-b$branch_name", { quiet => 0 } );

If C<$branch_name> contains an initial space character, the call will be
equivalent the following shell command:

	shell> git checkout -b\ sometopic

and B<git> will receive two arguments: C<checkout> and C<-b sometopic>, from
which it will split out C< sometopic> (note the initial space).

The space after I<-b> must be removed, as otherwise the code attempts to
create a branch called C< sometopic>, which git rejects.

=head2 Silence warnings for some Git commands

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

    $ git checkout mybranch
    Switched to branch 'mybranch'

The C<run()> method of L<Git::Repository> treats all output on C<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 C<quiet> option to silence the warning
for a single command:

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

To silence I<all> warnings, you can pass the C<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.

=head2 Process normal and error output

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

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

C<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.
I<Caveat emptor>.

=head2 Provide input on standard input

Use the C<input> option:

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

=head2 Change the environment of a command

Use the C<env> option:

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

Note that L<Git::Repository::Command> does small changes to the
environment a command before running it. Specifically, it:

=over 4

=item *

deletes C<GIT_DIR> and C<GIT_WORK_TREE>, and sets them to the
corresponding values from the current L<Git::Repository> object

=item *

deletes C<TERM>

=item *

replaces C<PATH> with the value of the C<< env->{PATH} >> option

=back

The easiest way to preserve en environment variable is to pass it with
the C<env> option, for example:

    $r->run( qw( config --get-colorbool githooks.color true ),
        { env => { TERM => $ENV{TERM} } } );

See L<Git::Repository::Command> and L<System::Command> for other
available options.

=head2 Ignore the system and global configuration files

Git has three levels of configuration files that can change the output
of porcelain commands: system (F<$(prefix)/etc/gitconfig>), global
(F<$HOME/.gitconfig> and F<$XDG_CONFIG_HOME/git/config>) and local
(F<.git/config> inside the repository).

To ensure the system and global configuration files will be ignored
and won't interfere with the expected output of your Git commands,
you can add the following keys to the C<env> option:

    GIT_CONFIG_NOSYSTEM => 1,
    XDG_CONFIG_HOME     => undef,
    HOME                => undef,

=head2 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 C<LC_ALL> environment variable to C<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 L<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' } } );

=head2 Ensure the Git commands are run from the current working directory

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

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

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

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

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

=head2 Finely control when C<run()> dies

By default, C<< Git::Repository->run( ... ) >> dies if the Git
command exited with a status code of C<128> (fatal error)
or C<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 C<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 C<<< $? >> 8 >>>) is C<1>.


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

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

By default, C<128> and C<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 L<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:

    # the above call to new() makes all exit codes fatal
    # but 3 and 7 won't be fatal for this specific run
    $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" } );

    # remove 17 from the list of fatal exit codes for this run only
    $r->run( ..., { fatal => -17 } );

See L<Git::Repository::Command> for other available options.

=head2 Process the output of B<git log>

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

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

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

Understanding the various options for B<git log> can make it very simple
to obtain a lot of information.

For example:

    # all tags reachable from $committish
    my @tags = map {
        s/^ \((.*)\)/$1/;
        ( map +( split /: / )[1], grep /^tag: /, split /, / )
      }
      $_->run( qw( log --simplify-by-decoration --pretty=%d ), $committish );

=head2 Process the output of B<git shortlog>

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

So this oneliner will hang, because B<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 B<git shortlog> I<some> input (from B<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;

=head2 Wrap git in a sudo call

If for a given repository you want to wrap all calls to git in a C<sudo>
call, you can use the C<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 C<$r> will actually call
C<sudo -u nobody git>.

=head2 Use submodules

Because L<Git::Repository> automatically sets the C<GIT_DIR> and
C<GIT_WORK_TREE> environment variables, some C<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 C<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 L<System::Command> version 1.04 is required to be able to remove
variables from the environment.

=head2 Sort git versions

Since version 1.318, Git::Repository lets L<Git::Version::Compare> handle
all version comparisons.

Sorting version numbers is therefore as simple as:

    use Git::Version::Compare qw( cmp_git );

    @sort_verson = sort cmp_git @versions;

=head2 Add specialized methods to your Git::Repository objects

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

=head2 Run code on the output of a git command through callback

Sometimes you need to process the output of a command by running a
callback on each line of the output.

    # code inspiration:
    # https://github.com/dolmen/github-keygen/blob/24c501072ba7d890810de3008434c1fe1f757286/release.pl#L178

    my %tree;
    $r->run( 'ls-tree' => $commit, sub {
        my ($mode, $type, $object, $file) = split;
        $tree{$file} = [ $mode, $type, $object ];
    } );

Note that the value returned by the callback will be returned as part of
the C<run()> output, instead of the original line.

=head2 Initialize a test repository with a bundle

Instead of creating a test repository using a series of file editions
and commits, one can simply import data into the test repository using
a bundle. Bundles are created with the C<git bundle create> command
(see the Git documentation for details).

First create a temporary repository with the help of L<Test::Git>:

    use Test::Git;
    my $r = test_repository();

then import the bundle data in your repository, and collect the references:

    my @refs = $r->run( bundle => 'unbundle', $bundle_file );

and finally update the references:

    for my $line (@refs) {
        my ( $sha1, $ref ) = split / /, $line;
        $r->run( 'update-ref', $ref => $sha1 );
    }

Since Git version 1.6.5, it's also possible to clone directly from a
bundle (this creates an C<origin> remote pointing to the bundle file):

    my $r = test_repository( clone => [ $bundle_file ] );

A bundle from a recipient repository's point of view is just like a
regular remote repository. See the documentation of B<git bundle> for
details of what's possible (e.g. incremental bundles).

=head1 AUTHOR

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

=head1 COPYRIGHT

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

=head1 LICENSE

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

=cut