The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Doit-0.025_50
River stage zero No dependents
5 ++
/ Doit::Git

NAME

Doit::Git - commands for dealing with the git revision control system

SYNOPSIS

    use Doit;
    my $doit = Doit->init;
    $doit->add_component('git');

    $doit->git_repo_update(
        repository => 'https://github.com/eserte/Doit.git',
        directory  => '/path/to/workdir',
    );

    my $status = $doit->git_short_status(
        directory       => '/path/to/workdir',
        untracked_files => 'no',
    );

    my $directory = $doit->get_root;
    my $sha1      = $doit->git_get_commit_hash;
    my @files     = $doit->git_get_commit_files;
    my @files     = $doit->git_get_changed_files;
    my $boolean   = $doit->git_is_shallow;
    my $branch    = $doit->git_current_branch;

    $self->git_config(
        key       => 'user.email',
    );
    $self->git_config(
        key       => 'user.email',
        val       => 'somebody@example.com',
    );
    $self->git_config(
        key       => 'branch.master.rebase',
        unset     => '1,
    );

DESCRIPTION

Doit::Git is a Doit component providing commands for dealing with the git revision control system. It has to be added to a script using Doit's add_component:

    $doit->add_component('git');

DOIT COMMANDS

The following commands are added to the Doit runner object:

git_repo_update

    $doit->git_repo_update(
        repository              => $git_url,
        directory               => $local_directory,
        repository_aliases      => [$git_url ...],
        allow_remote_url_change => $boolean,
        origin                  => $nickname,
        refresh                 => 'always', # or 'never'
        clone_opts              => [...],
        quiet                   => $boolean,
    );

Make sure that the given git repository $git_url is checked out (or refreshed) in the local directory $local_directory. This is done either by git-clone(1) a non-existent local repository, or by using git-fetch(1) resp. git-pull(1) for an existent local repository. Only repository and directory are mandatory options.

For existing repositories the list in repository_aliases is accepted as equivalent URLs (say, a https://... and an equivalent git://... URL). If none matches, then an exception will be thrown, unless allow_remote_url_change is set to a true value — in this case the remote URL will be adapted.

The default remote name origin may be changed by using the origin option.

If refresh is set to never, then only git-clone will be done for non-existent local repositories. The default is always, which means that an existing repository will be updated using git-fetch and git-pull.

clone_opts is an array ref with options which will be passed to git-clone. For existing repositories this does nothing.

If quiet is set to a true value, then some operations are quiet (currently the git-fetch command).

Return 1 if there were some changes done (git-clone or git-pull was executed), otherwise 0.

git_config

    my $changed = $doit->git_config(
        directory => $directory,
        key       => $key,
        val       => $val,
    );
    my $changed = $doit->git_config(
        directory => $directory,
        key       => $key,
        unset     => 1,
    );

If $val is defined, then make sure that the git config $key has the specified value $val.

If unset is set to a true value, then make sure that the git config $key is unset (absent).

If neither of both is specified, then git_config turns into an informational command (see below).

In all cases directory may be set to a $directory, otherwise the current working directory is used. The command fails if the specified directory is not a git directory.

Note that git_config handles only simple (but common) cases. See git-config(1) for the complete possibilities of git's configuration system.

DOIT INFORMATIONAL COMMANDS

The informational commands listed below are added to the Doit runner object. Informational commands also run in dry-run mode. All commands fail if operating on a non-git directory.

git_short_status

    my $status = $doit->git_short_status(
        directory       => $directory,
        untracked_files => 'normal', # or 'no'
    );

Return an indicator about the git working directory status of the given $directory, or the current working directory if directory is not set. $status may have the following values:

<<

Changed tracked files exist in the working directory (i.e. git-add(1) calls are missing).

<

Local repository is newer than remote (i.e. a git-push(1) call is missing).

(the empty string)

Local and remote are in sync (but maybe a git-fetch(1) call has to be done to refresh the remote status).

>

Remote is newer than local (i.e. a git-pull(1) or git-merge(1) resp. git-rebase(1) call is missing).

<>

Remote and local diverged.

Additionally, if untracked_files is set to normal (which is the default), then the presence of * in the string (located between < and >) indicates that there are untracked files. If untracked_files is set to no, then * will not appear in the status string. Examples:

    <<*  uncommitted and untracked files
    <*>  remote and local diverged, and there are untracked files

There's support for git-svn(1) repositories (but there's currently no test for this).

git_root

    my $directory = $doit->git_root(
        directory => $directory,
    );

Return the top directory of the git checkout for the given directory $directory, or the current working directory if directory is not given.

git_get_commit_hash

    my $sha1 = $doit->git_get_commit_hash(
        directory => $directory,
    );

Return the SHA1 of the git checkout for the given directory $directory, or the current working directory if directory is not given.

git_get_commit_files

    my @files = $doit->git_get_commit_files(
        directory => $directory,
        commit    => $committish,
    );

Return the list of changed files of the named commit (or HEAD, if not specified) for the given directory $directory (or the current working directory if not specified).

git_get_changed_files

    my @files = $doit->git_get_changed_files(
        directory => $directory,
    );

Return the list of changed files (uncommitted or untracked) in the given directory $directory (or the current working directory if not specified).

git_is_shallow

    my @files = $doit->git_is_shallow(
        directory => $directory,
    );

Return 1 if the given directory $directory (or the current working directory if not specified) is a "shallow" directory, otherwise return 0.

Implementation note: then existence of the file .git/shallow is checked.

git_current_branch

    my @files = $doit->git_current_branch(
        directory => $directory,
    );

Return the current branch in the given directory $directory (or the current working directory if not specified).

git_config (informational command)

    my $val = $doit->git_config(
        directory => $directory,
        key       => $key,
    );

Return the current value of $key, or undef if $key does not exist.

directory may be set to a $directory, otherwise the current working directory is used for running git-config(1).

Note that git_config handles only simple (but common) cases. See git-config(1) for the complete possibilities of git's configuration system.

AUTHOR

Slaven Rezic <srezic@cpan.org>

COPYRIGHT

Copyright (c) 2017 Slaven Rezic. All rights reserved. This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

SEE ALSO

Doit, git(1).