=head1 Name

sqitch-tag - Create or list tag objects

=head1 Synopsis

  sqitch [options] tag
  sqitch [options] tag <name>
  sqitch [options] tag <name> change --note <note>
  sqitch [options] tag --tag <name> --change <change>
  sqitch [options] tag <name> --all

=head1 Description

Tags a change or outputs a list of existing tags in one or more project plans.
Tagging is useful for preparing for a release. Tags are also required in order
to rework a change.

To specify a change, use a change specification as documented in
L<sqitchchanges>. If called with a tag name but no change, the most recent
change in each plan will be tagged. If called with no name specified, a list
of the current tags will be output.

Note that the name of the new tag must adhere to the rules as defined in
L<sqitchchanges>.

By default, the C<tag> command will add a new tag to the project's default
plan, as defined by the core configuration and command-line options. Pass the
C<--all> option to have it iterate over all known targets and list tags or add
a tag to all the plans. This works well to keep tags in sync in all plan
files.

To specify which plans to tag, pass the target, engine, or plan file names to
tag as arguments. Use C<--tag> and C<--change> to disambiguate the tag and
change names from the other parameters if necessary (or preferable). See
L</Examples> for examples.

=head1 Options

=over

=item C<-t>

=item C<--tag>

=item C<--tag-name>

The name of the tag to add. The name can be specified with or without this
option, but the option can be useful for disambiguating the tag name from
other arguments.

=item C<-c>

=item C<--change>

=item C<--change-name>

The name of the change to tag. The name can be specified with or without this
option, but the option can be useful for disambiguating the change name from
other arguments.

=item C<-a>

=item C<--all>

List the tags or add the new tag to all the plans in a project. Cannot be
mixed with target, engine, or plan file name arguments; doing so will result
in an error. Useful for multi-plan projects in which tags should be kept in
sync. Overrides the value of the C<tag.all> configuration; use C<--no-all> to
override a true C<tag.all> configuration.

=item C<-n>

=item C<--note>

A brief note describing the tag. The note will be attached to the tag as a
comment. Multiple invocations will be concatenated together as separate
paragraphs.

For you Git folks out there, C<-m> also works.

=back

=head1 Configuration Variables

=over

=item C<tag.all>

List the tags or add the new tag to all the plans in a project. Useful for
multi-plan projects in which tags should be kept in sync. May be overridden by
C<--all>, C<--no-all>, or target, engine, and plan file name arguments.

=back

=head1 Examples

Get a list of tags in the default project plan:

  sqitch tag

Get a list of all tags in the project:

  sqitch tag --all

Get a list of the tags in the plan used by the C<pg> engine:

  sqitch tag pg

Get a list of the tags in two specific plans:

  sqitch tag sqlite.plan pg.plan

Tag the latest change in the default project plan and be prompted for a note.

  sqitch tag alpha1

Tag the latest change in all project plans and be prompted for a note.

  sqitch tag alpha1 --all

Tag the latest change in the default project plan and and specify the note.

  sqitch tag alpha2 -n 'Tag @alpha2.'

Tag change C<users> in the default plan:

  sqitch tag --tag alpha3 --change users

Tag the latest change change in the project plan used by the C<vertica>
engine:

  sqitch tag --tag beta1 vertica -n 'Tag the Vertica with @beta1.'

Tag the latest change in two plans in a project:

  sqitch tag -t v1.0.1 sqlite.plan pg.plan -n 'Tag @v1.0.1.'

=head1 Configuration Variables

None currently.

=head1 Sqitch

Part of the L<sqitch> suite.