Managing Tags

function createTag(
  tagName: string,
  opts?: CreateTagOptions
): Promise<string>

await createTag("v1.0.0")
// Same as: git tag v1.0.0

createTag("hotfix-1")
  .then(output => console.log(output))
  .catch(error => console.error(error))

await createTag("v1.0.0", { force: true })
// Same as: git tag -f v1.0.0

function createAnnotatedTag(
  tagName: string,
  message: string,
  opts?: CreateTagOptions
): Promise<string>

await createAnnotatedTag("v1.0.0", "Initial stable release")
// Same as: git tag -m "Initial stable release" v1.0.0

createAnnotatedTag("release-2024", "Production release for 2024")
  .then(output => console.log(output))
  .catch(error => console.error(error))

await createAnnotatedTag(
  "v1.0.0",
  "Re-tagged after hotfix",
  { force: true }
)
// Same as: git tag -f -m "Re-tagged after hotfix" v1.0.0

function deleteTag(tagName: string): Promise<string>

await deleteTag("v1.0.0")
// Deletes the local tag `v1.0.0`
// Same as: git tag --delete v1.0.0

deleteTag("release-2024")
  .then(output => console.log(output))
  .catch(error => console.error(error))

function getTags(
  prefixes?: string[],
  to?: string
): Promise<string[]>

const tags = await getTags()
console.log(tags)
// ['v0.1.0', 'v0.2.0', 'v0.3.0']

const tags = await getTags(['v'], 'version-')
console.log(tags)
// ['version-0.1.0', 'version-0.2.0']

function hasTag(tagName: string): Promise<boolean>

const exists = await hasTag("v0.3.0")
console.log(exists) // true

const missing = await hasTag("v9.9.9")
console.log(missing) // false

if (!await hasTag("v1.0.0")) {
  await createTag("v1.0.0")
  console.log("Tag created")
} else {
  console.log("Tag already exists")
}

function isValidTagName(name: string): boolean

isValidTagName("v1.0.0")     // true
isValidTagName("release-1")  // true
isValidTagName("feature/v2") // true

isValidTagName("v 1.0.0")    // false (contains space)
isValidTagName("../v1")      // false (parent directory reference)
isValidTagName("@")          // false (reserved name)
isValidTagName("tag.lock")   // false (ends with .lock)
isValidTagName("feature//x") // false (consecutive slashes)

const tags = [
  "v1.0.0",
  "release-2025",
  "feature/v2",
  "@",
  "../v1",
  "tag.lock",
  "v 1.0.0",
  "/start",
  "end/",
  "feature//x",
]

for (const tag of tags) {
  console.log(`${tag.padEnd(15)} →`, isValidTagName(tag))
}

// Output:
// v1.0.0         → true
// release-2025   → true
// feature/v2     → true
// @              → false
// ../v1          → false
// tag.lock       → false
// v 1.0.0        → false
// /start         → false
// end/           → false
// feature//x     → false