        Creates a TopGit annotated/signed tag or lists the reflog of one.

        A TopGit annotated tag records the current state of one or more TopGit
        branches and their dependencies and may be used to revert to the tagged
        state at any point in the future.

        When reflogs are enabled (the default in a non-bare repository) and
        combined with the `--force` option a single tag name may be used as a
        sort of TopGit branch state stash.  The special branch name `--all`
        may be used to tag the state of all current TopGit branches to
        facilitate this function and has the side-effect of suppressing the
        out-of-date check allowing out-of-date branches to be included.

        As a special feature, `--stash` may be used as the tag name in which
        case `--all` is implied if no branch name is listed (instead of the
        normal default of `HEAD`), `--force` and `--no-edit` (use
        `--edit` to change that) are automatically activated and the tag will
        be saved to `refs/tgstash` instead of `refs/tags/<tagname>`.
        The `--stash` tag name may also be used with the `-g`/`--reflog`
        option.

        The mostly undocumented option `--allow-outdated` will bypass the
        out-of-date check and is implied when `--stash` or `--all` is used.

        A TopGit annotated/signed tag is simply a Git annotated/signed tag with
        a "TOPGIT REFS" section appended to the end of the tag message (and
        preceding the signature for signed tags).  PEM-style begin and end
        lines surround one line per ref where the format of each line is
        full-hash SP ref-name.  A line will be included for each branch given
        on the command line and each ref they depend on either directly or
        indirectly.

        Note that when specifying branch names, if a given name is ambiguous
        but prefixing the branch name with `refs/heads/` successfully
        disambiguates it, then that will be the interpretation used.

        If more than one TopGit branch is given on the command line, a new
        commit will be created that has an empty tree and all of the given
        TopGit branches as parents and that commit will be tagged.  If a single
        TopGit branch is given, then it will be tagged.  If the `--tree`
        option is used then it will be used instead of an empty tree (a new
        commit will be created if necessary to guarantee the specified tree is
        what's in the commit the newly created tag refers to).  The argument to
        the `--tree` option may be any valid treeish.

        If exactly one of the branches to be tagged is prefixed with a tilde
        (`~`) it will be made the first parent of a consolidation commit if
        it is not already the sole commit needing to be tagged.  If `--tree`
        is NOT used, its tree will also be used instead of the empty tree for
        any new consolidation commit if one is created.  Note that if
        `--tree` is given explicitly its tree is always used but that does
        not in any way affect the choice of first parent.  Beware that the
        `~` may need to be quoted to prevent the shell from misinterpreting
        it into something else.

        All the options for creating a tag serve the same purpose as their Git
        equivalents except for two.  The `--refs` option suppresses tag
        creation entirely and emits the "TOPGIT REFS" section that would have
        been included with the tag.  If the `--no-edit` option is given and
        no message is supplied (via the `-m` or `-F` option) then the
        default message created by TopGit will be used without running the
        editor.

        With `-g` or `--reflog` show the reflog for a tag.  With the
        `--reflog-message` option the message from the reflog is shown.
        With the `--commit-message` option the first line of the tag's
        message (if the object is a tag) or the commit message (if the object
        is a commit) falling back to the reflog message for tree and blob
        objects is shown.  The default is `--reflog-message` unless the
        `--stash` (`refs/tgstash`) is being shown in which case the default
        is then `--commit-message`.  Just add either option explicitly to
        override the default.

        When showing reflogs, non-tag entries are annotated with their type
        unless `--no-type` is given.  Custom colors can be set with these
        git config options:

          `color.tgtag`          enable/disable color, default is `color.ui`
          `color.tgtag.commit`   hash color, dflt `color.diff.commit`/yellow
          `color.tgtag.date`     date line color, default is bold blue
          `color.tgtag.meta`     object type "color", default is bold
          `color.tgtag.time`     time info color, default is green

        TopGit tags are created with a reflog if core.logallrefupdates is
        enabled (the default for non-bare repositories).  Unfortunately Git
        is incapable of showing an annotated/signed tag's reflog (using either
        `git log -g` or `git reflog show`).  Git can, however, show
        reflogs for lightweight tags just fine but that's not helpful here.
        Use `tg tag` with the `-g` or `--reflog` option to see the
        reflog for an actual tag object.  This also works on non-TopGit
        annotated/signed tags as well provided they have a reflog.

        Note that the time and date shown for reflog entries by `tg tag -g`
        is the actual time and date recorded in that reflog entry itself which
        usually is the time and date that entry was added to the reflog, *not*
        the time and date of the commit it refers to.  Git itself will only
        ever show the time and date recorded in a reflog entry when given just
        the right arguments to `git log`, but then the reflog entry's time
        and date are always shown *in place of* its index number.

        By contrast, `tg tag -g` always shows the reflog entry's time and
        date *together with* its reflog entry index number.

        The number of entries shown may be limited with the `-n` option.  If
        the tagname is omitted then `--stash` is assumed.

        The `--delete` option is a convenience option that runs the
        `git update-ref --no-deref -d` command on the specified tag removing
        it and its reflog (if it has one).  Note that `HEAD` cannot be removed.

        The `--clear` option clears all but the most recent (the `@{0}`)
        reflog entry from the reflog for the specified tag.  It's equivalent
        to dropping all the higher numbered reflog entries.

        The `--drop` option drops the specified reflog entry and requires the
        given tagname to have an `@{n}` suffix where `n` is the reflog
        entry number to be dropped.   This is really just a convenience option
        that runs the appropriate `git reflog delete` command.  Note that
        even dropping the ...@{0} entry when it's the last entry of a
        non-symbolic ref will NOT delete the ref itself (unless the ref was
        already somehow set to an invalid object hash); but dropping @{0} of
        a non-symbolic ref may have the side effect of removing some stale
        reflog entries that were present in the reflog.

        Note that when combined with `tg revert`, a tag created by `tg tag`
        can be used to transfer TopGit branches.  Simply create the tag, push
        it somewhere and then have the recipient run `tg revert` to recreate
        the TopGit branches.  This may be helpful in situations where it's not
        feasible to push all the refs corresponding to the TopGit-controlled
        branches and their top-bases.

