=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|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|sqitch-revert> and L|sqitch-log>, search the database for the change. =head2 Change Names A change name, such as that passed to L|sqitch-add> and written to the plan file has a few limitations on the characters it may contain. The same limitations apply to tag names. 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 =item C<12> =item C =item C<6> =item C<阱阪阬> =item C<阱阪阬92> =item C =item C =item C =item C<_foo> =item C =item C =item C =item C =back Some examples of invalid names: =over =item C<^foo> =item C =item C =item C =item C<%hi> =item C =item C =item C =item C<+foo> =item C<-foo> =item C<@foo> =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<< >>, e.g., C The name of a change itself, as it was added to the plan via L|sqitch-add>. =item C<< @ >>, e.g., C<@rc1> The change as of the named tag. Tags can be added to the plan via L|sqitch-tag>. =item C<< @ >>, e.g., C The named change as of a tag, also known as a tag-qualified change name. For change iteration commands (such as L|sqitch-log>), this means the instance of a change with that name before the specified tag. For dependency parameters (such as in L|sqitch-add>), this means any instance of a change just before that tag, or at any time after the tag. =item C<< >>, e.g., C<40763784148fa190d75bad036730ef44d1c2eac6> The change full SHA1 ID (40-byte hexadecimal string). In some cases, such as L|sqitch-add>, the ID may refer to a change in another Sqitch project. =item C<< : >>, e.g., C 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|sqitch-add>. =item C<< :@ >>, e.g., C The name of a tag in an the named project. =item C<< :@ >>, e.g., C A tag-qualified named change in the named project. =item C<< : >>, e.g., C 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|sqitch-add> or L|sqitch-rework> will validate that the specified change is in the current project. =item C<@HEAD> =item C Special symbolic name for the last change in the plan. =item C<@ROOT> =item C Special symbolic name for the first change in the plan. =item C<< ^ >>, e.g., C<@HEAD^^>, C<@HEAD^3>, C<@beta^2> A suffix C<^> to a symbolic or actual name means the change I to that change. Two C<^>s indicate the second prior change. Additional prior changes can be specified as C<< ^ >>, where C<< >> represents the number of changes to go back. =item C<< ~ >>, e.g., C<@ROOT~>, C<@ROOT~~>, C<@bar~4> A suffix C<~> to a symbolic or actual name means the change I that change. Two C<~>s indicate the second following change. Additional following changes can be specified as C<< ~ >>, where C<< >> represents the number of changes to go forward. =back =head1 Sqitch Part of the L suite.