/ 
Doit-0.024_51
River stage zero No dependents
/ 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).