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.