NAME

VCI::Abstract::Project - A particular project in the Repository

SYNOPSIS

my $project = $repository->get_project(name => 'Foo');

# Getting information about individual files/directories.

my $file = $project->get_file(path => 'path/to/file.c');
my $directory = $project->get_directory(path => 'path/to/directory/');

my $file = $project->get_path(path => 'path/to/file.c');
my $directory = $project->get_path(path => 'path/to/directory/');

# Commits

my $commit = $project->get_commit(revision => '123');
my $commit = $project->get_commit(time => 'July 7, 2007 12:01:22 UTC');
my $commit = $project->get_commit(at_or_before => 'July 7, 2007 13:00:00 UTC');
my $commits = $project->get_history_by_time(start => 'January 1, 1970',
                                            end   => '2007-01-01');
# Other information

my $root_directory = $project->root_directory;
my $history = $project->history;
my $name = $project->name;

$repository == $project->repository # True

DESCRIPTION

This represents a Project, something that could be checked out of a Repository.

For example, the Mozilla CVS Repository contains Firefox and Thunderbird as Projects.

METHODS

Accessors

All of these accessors are read-only.

name

The name of the Project, as a string. This is something that you could pass to "get_project" in VCI::Abstract::Repository to get this Project. Usually this is just the path to the Project's directory, relative to the root of the Repository.

repository

The VCI::Abstract::Repository that this Project is in.

history

The VCI::Abstract::History of this whole Project.

root_directory

The root VCI::Abstract::Directory, containing this project's files and directories.

head_revision

The revision ID that identifies the current "head" of this Project. Usually this will be the ID of the very latest revision.

Files and Directories

Methods to get information about specific files and directories.

Note that paths are case-sensitive in the default implementation of VCI, but particular drivers may be case-insensitive (for example, for version-control systems that are on Windows servers). However, it is best not to rely on case-insensitivity, and always specify your file names assuming that VCI will be case-sensitive.

get_path

Description

When you have a path but you don't know if it's a file or a directory, use this function to get it as an object.

If you know that you want a file, or know that you want a directory, it is recommended that you use "get_file" or "get_directory" instead.

Parameters

Takes one named parameter:

path

A Path to the file or directory that you want, relative to the base of the project.

Absolute paths will be interpreted as relative to the base of the project.

If you pass an empty string or "/", you will get the root directory of the Project.

Returns

An object that implements VCI::Abstract::Committable, either a file or a directory.

If there is no object with that path, will return undef. However, if you specify a parent directory that doesn't exist, we will die.

So, for example, if you ask for /path/to/file.c and /path/to/ is a valid directory but doesn't contain file.c, we will return undef. But if /path/to/ is not a valid directory, we will die. Also, if /path is not a valid directory, we will die.

get_directory

Description

Gets a directory from the repository.

Parameters

Takes one named parameter:

path

A Path to the directory that you want, relative to the base of the project.

Absolute paths will be interpreted as relative to the base of the project.

If you pass an empty string or "/", you will get the root directory of the Project.

Returns

A VCI::Abstract::Directory, or undef if there is no directory with that name. (Even if there's a file with that name, if it's not a directory, we will still return undef.)

Also, if any of the parent directories don't exist, we return undef.

get_file

Description

Gets a file from the repository.

Parameters

Takes the following named parameters:

path Required

A Path to the file that you want, relative to the base of the project.

Absolute paths will be interpreted as relative to the base of the project.

This method will throw an error if you pass in an empty string or just "/".

revision

The exact revision that you want of the file. On VCSes where the File revision IDs differ from the Commit revision IDs (like CVS), you should specify the File revision ID here, not the Commit revision ID.

If you specify a valid revision ID but that revision didn't include adding, removing, or modifying this file in any way, you will get undef.

If you don't specify this parameter, you will get the latest revision of the file.

Returns

A VCI::Abstract::File, or undef if there is no file with that name and revision. (Even if there's something with that name, if it's not a file, we will still return undef.)

If the parent directory doesn't exist, or any of the parent directories don't exist, this will throw an error (identically to how "get_path" works).

Commits to the Project

get_commit

Description

Gets a particular commit from the Project by its unique identifier.

Parameters

Takes one (and only one) of the following named parameters:

revision

The unique identifier of the commit that you want, as a string.

See "revision" in VCI::Abstract::Commit for a discussion of exactly what a revision identifier is.

time

A datetime.

Specifies that you want the commit that happened at an exact moment in time. Note that some VCSes may track commits down to the microsecond, and in this case, your time must be accurate down to the same microsecond.

(If you want to be less accurate, use "get_history_by_time" or the "at_or_before" argument instead.)

In extremely rare cases, VCSes may have two commits that happen at the exact same time. In this case VCI will print a warning and you will get the commit that the VCS considers to have happened "first" (that is, it will have the lower revision number or come "logically" before the other commit).

at_or_before

A datetime.

Specifies that you want the commit right before or exactly at this time.

Note that if the earliest commit is after this time, you will get undef.

Returns

The VCI::Abstract::Commit that you asked for, or undef if there is no commit with that ID in this Project.

get_history_by_time

Description

Get a section of the Project's history based on times.

Parameters

Takes the following named parameters. At least one of them must be specified.

start

A datetime.

The earliest revision you want returned. (Search is "inclusive", so if the time of the commit matches start exactly, it will be returned.)

If you specify start without end, we search from start to the most recent commit.

end

A datetime.

The latest revision you want returned. (Search is "inclusive", so if the time of the commit matches end exactly, it will be returned.)

If you specify end without start, we search from the beginning of time to end.

Returns

A VCI::Abstract::History for the project representing the times that you asked for. If there were no commits matching your criteria, the History's "commits" will be an empty arrayref.

CLASS METHODS

Constructors

Usually you won't construct an instance of this class directly, but instead, use "get_project" in VCI::Abstract::Repository or "projects" in VCI::Abstract::Repository.

new

Takes all "Accessors" of this class as named parameters. The following fields are required: "name" and "repository".