The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.

Name

sqitch-tag - Create or list tag objects

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

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 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 sqitchchanges.

By default, the 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 --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 --tag and --change to disambiguate the tag and change names from the other parameters if necessary (or preferable). See "Examples" for examples.

Options

-t
--tag
--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.

-c
--change
--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.

-a
--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 tag.all configuration; use --no-all to override a true tag.all configuration.

-n
--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, -m also works.

Configuration Variables

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 --all, --no-all, or target, engine, and plan file name arguments.

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 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 users in the default plan:

  sqitch tag --tag alpha3 --change users

Tag the latest change change in the project plan used by the 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.'

Configuration Variables

None currently.

Sqitch

Part of the sqitch suite.