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.