=encoding UTF-8

=head1 Name

sqitchchanges - Specifying changes for Sqitch

=head1 Description

Many Sqitch commands take change parameters as arguments. Depending on the
command, they denote a specific change or, for commands which walk change
history or the change plan (such as L<C<sqitch log>|sqitch-log>), all changes
which can be reached from that change. Most commands search the plan for the
relevant change, though some, such as L<C<sqitch revert>|sqitch-revert> and
L<C<sqitch log>|sqitch-log>, search the database for the change.

=head2 Change Names

A change name, such as that passed to L<C<sqitch add>|sqitch-add> and written
to the plan file, has a few limitations on the characters it may contain. The
rules are:

=over

=item *

Must be at least one character.

=item *

Must contain no blank characters.

=item *

The first character may not be punctuation.

=item *

Last letter may not be punctuation.

=item *

Must not end in "~", "^", "/", "=", or "%" followed by digits.

=item *

All other characters may be any UTF-8 character other than ":", "@", "#",
and "\".

=back

Note that "_" (underscore) is never considered punctuation. Some examples of
valid names:

=over

=item C<foo>

=item C<12>

=item C<t>

=item C<6>

=item C<阱阪阬>

=item C<阱阪阬92>

=item C<foo/bar>

=item C<beta1>

=item C<foo_>

=item C<_foo>

=item C<v1.0-1b>

=item C<v1.2-1>

=item C<v1.2+1>

=item C<v1.2_1>

=back

Some examples of invalid names:

=over

=item C<^foo>

=item C<foo^>

=item C<foo^6>

=item C<foo^666>

=item C<%hi>

=item C<hi!>

=item C<foo@bar>

=item C<foo:bar>

=item C<foo\bar>

=item C<+foo>

=item C<-foo>

=item C<@foo>

=back

=head2 Tag Names

A tag name, such as that passed to L<C<sqitch tag>|sqitch-tag> and written
to the plan file, adhere by the same rules as L</Change Names> with one
additional limitation: tags must not contain a slash character ("/").
Example valid change name but invalid tag name:

=over

=item C<foo/bar>

=back

=head1 Specifying Changes

A change parameter names a change object. It uses what is called an extended
SHA1 syntax. Here are various ways to spell change names:

=over

=item C<< <change_name> >>, e.g., C<users_table>

The name of a change itself, as it was added to the plan via
L<C<sqitch add>|sqitch-add>.

=item C<< @<tag_name> >>, e.g., C<@rc1>

The change as of the named tag. Tags can be added to the plan via
L<C<sqitch tag>|sqitch-tag>.

=item C<< <change_name>@<tag_name> >>, e.g., C<users_table@beta1>

The named change as of a tag, also known as a tag-qualified change name. For
change iteration commands (such as L<C<sqitch log>|sqitch-log>), this means
the instance of a change with that name before the specified tag. For
dependency parameters (such as in L<C<sqitch add>|sqitch-add>), this means any
instance of a change just before that tag, or at any time after the tag.

=item C<< <sha1> >>, e.g., C<40763784148fa190d75bad036730ef44d1c2eac6>

The change full SHA1 ID (40-byte hexadecimal string). In some cases, such as
L<C<sqitch add>|sqitch-add>, the ID may refer to a change in another Sqitch
project.

=item C<< <project>:<change_name> >>, e.g., C<mybase:users_table>

The name of a change in a specific project. Non-SHA1 change parameters without
a project prefix are assumed to belong to the current project. Most useful for
declaring a dependency on a change from another project in
L<C<sqitch add>|sqitch-add>.

=item C<< <project>:@<tag_name> >>, e.g., C<mybase:@rc1>

The name of a tag in an the named project.

=item C<< <project>:<change_name>@<tag_name> >>, e.g., C<project:users_table@beta1>

A tag-qualified named change in the named project.

=item C<< <project>:<sha1> >>, e.g., C<mybase:40763784148fa190d75bad036730ef44d1c2eac6>

The full SHA1 ID from another project. Probably redundant, since the SHA1 I
should itself be sufficient. But useful for declaring dependencies in the
current project so that L<C<sqitch add>|sqitch-add> or
L<C<sqitch rework>|sqitch-rework> will validate that the specified change is in
the current project.

=item C<@HEAD>

=item C<HEAD>

Special symbolic name for the last change in the plan.

=item C<@ROOT>

=item C<ROOT>

Special symbolic name for the first change in the plan.

=item C<< <change>^ >>, e.g., C<@HEAD^^>, C<@HEAD^3>, C<@beta^2>

A suffix C<^> to a symbolic or actual name means the change I<prior> to that
change. Two C<^>s indicate the second prior change. Additional prior changes
can be specified as C<< ^<n> >>, where C<< <n> >> represents the number of
changes to go back.

=item C<< <change>~ >>, e.g., C<@ROOT~>, C<@ROOT~~>, C<@bar~4>

A suffix C<~> to a symbolic or actual name means the change I<after> that
change. Two C<~>s indicate the second following change. Additional following
changes can be specified as C<< ~<n> >>, where C<< <n> >> represents the
number of changes to go forward.

=back

=head1 Sqitch

Part of the L<sqitch> suite.
