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.
-
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
$pathis inside the VCS's own directories, where nothing is ever tracked.
Revisions
- $rev = $vcs->resolve($name)
-
The full id of the revision
$namenames. 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
$revstands for, or undef when it is not one. - $revs = $vcs->revisions($base, $head)
-
Arrayref of the revisions in
$headbut 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>) andauthored(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
$fromand$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_pathfor 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_changeslists 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_diffis 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
$numberof a review, as stored in itsiteration.pin. - $vcs->pin($name, $rev)
-
Keep
$revalive 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
AUTHORS
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.