NAME

VCI::Abstract::Commit - Represents a single atomic commit to the repository.

DESCRIPTION

Usually, when you modify a repository in version control, you modify many files simultaneously in a single "commit" (also called a "checkin").

This object represents one of those commits in the history of a project.

Some version-control systems don't actually understand the idea of an "atomic commit" (meaning they don't understand that certain changes were all committed simultaneously), but VCI does its best to figure out what files were committed together and represent them all as one object.

A VCI::Abstract::Commit implements VCI::Abstract::FileContainer, so all of FileContainer's methods are also available here.

Note: Depending on how this object was constructed, it may or may not actually contain information on all of the files that were committed in this change. For example, when you use "history" in VCI::Abstract::File, Commit objects might only contain information about that single file. This is due to the limits of various version-control systems.

METHODS

Accessors

These are all read-only.

time

A datetime representing the date and time of this commit.

On VCSes that don't understand atomic commits, this will be the time of the earliest commited file in this set.

committer

A string identifying who committed this revision. That is, the username of the committer, or their real name and email address (or something similar). The format of this string is not guaranteed.

contents

All of the items added, removed, or modified in this commit, as an arrayref of VCI::Abstract::Committable objects.

added

Just the items that were added in this commit, as an arrayref of VCI::Abstract::Committable objects.

removed

Just the items that were deleted in this commit, as an arrayref of VCI::Abstract::Committable objects.

modified

The items that were modified (not added or removed, just changed) in this commit, as an arrayref of VCI::Abstract::Committable objects.

Any files that were "moved" will have their new names, not their old names.

moved

Some version-control systems understand the idea that a file can be renamed or moved, not just removed and then added.

If a file was moved or renamed, it will show up in this accessor, which is a hashref where the keys are the new path and the value is the old path, as strings. (That might seem backwards until you realize that the new name is what shows up in "modified", so having keys on the new name is much more useful.)

The file will show up in "modified" if it also had modifications during this commit. (However, if there were no changes to the file other than that it was moved, it won't show up in "modified".)

copied

A hashref of objects that were copied from another file/directory, preserving their history. The place we were copied from could have been in some other Project (and in rare cases, a completely different Repository, though VCI might not track that it was copied in that case).

The keys are the name of the file as it is now, and the value is a VCI::Abstract::Committable that represents the object it was copied from.

Any item in copied will also show up in modified if it was changed during this commit, and added otherwise.

revision

A string representing the unique identifier of this commit, according to the version-control system.

For version-controls systems that don't understand atomic commits, this will be some unique identifier generated by VCI. This identifier is guaranteed to be stable--that is, you can use it to retrieve this commit object from "get_commit" in VCI::Abstract::Project.

Individual VCI::VCS implementations will specify the format of their revision IDs, if they are a VCS that doesn't have unique identifiers for commits, or if there is any ambiguity about what exactly "revision id" means for that VCS.

message

The message that was entered by the committer, describing this commit.

as_diff

Returns a representation of the changes made to files in this commit, as a VCI::Abstract::Diff object.

If the VCS provides a diff format that tracks renames and copies, the diff will be in that format. In other words, it will represent the changes in the same way the Commit represents them. For example, if a file has been moved and then modified, in a normal diff you'd see one entire file removed and then another added. In this diff you will only see that a file was modified, and that file will have the new name.

CLASS METHODS

Constructors

Usually you won't construct an instance of this class directly, but instead, use various methods of VCI::Abstract::Project to get Commits out of the Project's History.

new

Takes all "Accessors" as named parameters. The following fields are required: "time", "revision", and project.

If "committer" and "message" aren't specified, they default to an empty string.