NAME

Review::Helper::VCS - The version control system a review reads its change from.

DESCRIPTION

A Role::Tiny role: the one interface the rest of Review::Helper uses to read a repository, so nothing outside an implementation names a VCS command, ref or option. Review::Helper::VCS::Git is the only implementation. detect picks the implementation for a path; it is where another one would be added.

The terms used below (revision, empty revision, path spec, pin, change id) are defined in the format specification, standards/FORMAT.md in the share directory, "Repository conventions", with their git meaning.

A change is a hashref for one file that differs between two revisions: path, old_path (renames only, else undef), status (A, D, M or R), added, removed, binary and submodule (1 when either side is another repository's entry, which has no content here). Binary files count zero lines.

Paths and text returned are character strings; diffs and file contents are bytes. Diffs are unified diffs in the fixed form the format specification's "Diff convention" gives, so line anchors stay stable.

SYNOPSIS

use Review::Helper::VCS;

my $vcs = Review::Helper::VCS->detect($path);

my $head    = $vcs->resolve('HEAD');
my $revs    = $vcs->revisions($base, $head);
my $changes = $vcs->range_changes($base, $head);

CLASS METHODS

$vcs = Review::Helper::VCS->detect($path)

The repository holding $path, a file or directory, as an object of the implementation that manages it. Croaks when none does.

REQUIRED METHODS

The repository

$vcs = $class->find($path)

The repository holding $path, a file or directory. A file need not exist, but its directory must. Croaks when there is none.

$dir = $vcs->root()

Absolute path of the working tree's top directory.

$who = $vcs->user()

The user's identity in this repository, Name <email>, either part alone, or undef when none is set.

$dir = $vcs->state_dir()

Absolute path of Review::Helper's private directory for this working tree, outside the tracked files. Review files and the journal go here by default. It may not exist yet.

$dir = $vcs->shared_state_dir()

Absolute path of Review::Helper's private directory shared by every working tree of the repository; the registry lives here. It may not exist yet.

$bool = $vcs->is_internal_path($path)

True when the absolute $path is inside the VCS's own directories, where nothing is ever tracked.

Revisions

$rev = $vcs->resolve($name)

The full id of the revision $name names. Croaks when it names none.

$rev = $vcs->empty_revision()

The empty revision's id.

$bool = $vcs->has_revision($rev)

True when the revision is in the repository.

$name = $vcs->revision_name($rev)

The branch or tag name $rev stands for, or undef when it is not one.

$revs = $vcs->revisions($base, $head)

Arrayref of the revisions in $head but not $base, oldest first, each after its parents, as { revision => $id, parents => [@ids] }.

$parents = $vcs->parents($rev)

Arrayref of the revision's parents, first parent first.

$info = $vcs->revision_info($rev)

Hashref with revision (the full id), parent (first parent, undef for none), subject, message, author (Name <email>) and authored (epoch seconds).

$id = $vcs->change_id($rev)

A stable id of the revision's change: equal for the same change rebased elsewhere. Undef when the revision changes nothing.

Changes and diffs

$changes = $vcs->range_changes($from, $to)
$changes = $vcs->range_changes($from, $to, \@path_specs)

Arrayref of the changes (see "DESCRIPTION") between $from and $to, limited to the path specs when given.

$bytes = $vcs->range_diff($from, $to, $path)
$bytes = $vcs->range_diff($from, $to, $path, $old_path)

The unified diff of one file between two revisions, its path taken literally. Pass $old_path for a rename so both sides pair up.

$changes = $vcs->resolution_changes($rev)
$changes = $vcs->resolution_changes($rev, \@path_specs)
$bytes = $vcs->resolution_diff($rev, $path)
$bytes = $vcs->resolution_diff($rev, $path, $old_path)

A merge's own changes: from what the VCS's merge of its parents would make, conflicts included, to what was recorded, so the hand-made conflict resolutions. resolution_changes lists the files (without line counts); it is empty for a clean merge, a revision that is not a merge, or a VCS that cannot tell. resolution_diff is one file's diff.

Files

$bytes = $vcs->file($rev, $path)

The file's content in that revision, or undef when no file is there (nothing at that path, a directory, or another repository's entry).

$id = $vcs->file_id($rev, $path)

An id of the content at that path in that revision, or undef when nothing is there. Equal ids mean identical content.

Pins

$name = $vcs->pin_name($review_id, $number)

The pin name of iteration $number of a review, as stored in its iteration.pin.

$vcs->pin($name, $rev)

Keep $rev alive under $name, creating or moving the pin.

$names = $vcs->pins($review_id)

Arrayref of the names of every pin the review has.

$vcs->unpin($name)

Remove a pin.

SOURCE

The source code repository for Review-Helper can be found at https://github.com/exodist/Review-Helper.

MAINTAINERS

Chad Granum <exodist7@gmail.com>

AUTHORS

Chad Granum <exodist7@gmail.com>

COPYRIGHT

Copyright Chad Granum <exodist7@gmail.com>.

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

See https://dev.perl.org/licenses/