@git-lazy/tag

Create git tags programmatically with support for annotated, signed, and force-overwrite options

Installation

npm install @git-lazy/tag
# or
pnpm add @git-lazy/tag
# or
yarn add @git-lazy/tag

Usage

import { gitTag, gitTagSync, buildCmd } from '@git-lazy/tag';

// 建立基本標籤 / Create a basic tag
await gitTag('v1.0.0');

// 建立附註標籤 / Create an annotated tag
await gitTag('v1.0.0', {
  annotated: true,
  message: 'Release v1.0.0',
  cwd: '/path/to/repo',
});

// 同步建立標籤 / Synchronously create a tag
const result = gitTagSync('v1.0.0');

// 建立強制覆蓋的簽章標籤 / Create a force-overwrite signed tag
gitTagSync('v2.0.0', {
  forceGitTag: true,
  signGitTag: true,
  message: 'Major release v2.0.0',
});

API

gitTag(tag, options, spawnOptions)

非同步執行 git tag 命令 / Asynchronously execute git tag command

使用 cross-spawn 以非同步方式執行 git tag，適合需要等待完成但不阻塞主執行緒的場景 Executes git tag asynchronously using cross-spawn, suitable for scenarios that need to wait for completion without blocking the main thread

Parameters:

• tag (string) - 標籤名稱 / Tag name
• options (IOptions) - 標籤選項 / Tag options
  • cwd (string) - 工作目錄路徑 / Working directory path
  • message (string) - 標籤訊息 / Tag message
  • forceGitTag (boolean) - 是否強制覆蓋已存在的標籤 / Whether to force overwrite existing tags
  • signGitTag (boolean) - 是否對標籤進行 GPG 簽章 / Whether to GPG sign the tag
  • annotated (boolean) - 是否建立附註標籤 / Whether to create an annotated tag
  • target (string) - 目標物件（Commit SHA、Branch 等）/ Target object (Commit SHA, Branch, etc.)
• spawnOptions (ISpawnGitAsyncOptions) - 程序產生選項 / Spawn process options

Returns: Promise - 非同步程序執行結果 / Async process execution result

Example:

import { gitTag } from '@git-lazy/tag';

// 建立基本標籤 / Create a basic tag
await gitTag('v1.0.0');

// 建立附註標籤並指定工作目錄 / Create an annotated tag with working directory
await gitTag('v1.0.0', {
  annotated: true,
  message: 'Release v1.0.0',
  cwd: '/path/to/repo',
});

gitTagSync(tag, options, spawnOptions)

同步執行 git tag 命令 / Synchronously execute git tag command

使用 cross-spawn 以同步方式執行 git tag，適合需要立即確認結果的場景 Executes git tag synchronously using cross-spawn, suitable for scenarios that need immediate result confirmation

Parameters:

• tag (string) - 標籤名稱 / Tag name
• options (IOptions) - 標籤選項 / Tag options
  • cwd (string) - 工作目錄路徑 / Working directory path
  • message (string) - 標籤訊息 / Tag message
  • forceGitTag (boolean) - 是否強制覆蓋已存在的標籤 / Whether to force overwrite existing tags
  • signGitTag (boolean) - 是否對標籤進行 GPG 簽章 / Whether to GPG sign the tag
  • annotated (boolean) - 是否建立附註標籤 / Whether to create an annotated tag
  • target (string) - 目標物件（Commit SHA、Branch 等）/ Target object (Commit SHA, Branch, etc.)
• spawnOptions (ISpawnGitSyncOptions) - 程序產生選項 / Spawn process options

Returns: ISpawnSyncResult - 同步程序執行結果 / Sync process execution result

Example:

import { gitTagSync } from '@git-lazy/tag';

// 同步建立標籤 / Synchronously create a tag
const result = gitTagSync('v1.0.0');
console.log(result.status); // 0 表示成功 / 0 indicates success

// 建立強制覆蓋的簽章標籤 / Create a force-overwrite signed tag
gitTagSync('v2.0.0', {
  forceGitTag: true,
  signGitTag: true,
  message: 'Major release v2.0.0',
});

buildCmd(tag, options)

建立 git tag 命令參數陣列 / Build git tag command arguments array

根據提供的標籤名稱與選項，生成對應的 git tag 命令參數 Generates corresponding git tag command arguments based on the provided tag name and options

Parameters:

• tag (string) - 標籤名稱 / Tag name
• options (IOptions) - 標籤選項 / Tag options

Returns: string[] - 過濾後的命令參數陣列 / Filtered command arguments array

Example:

import { buildCmd } from '@git-lazy/tag';

// 建立基本標籤 / Create a basic tag
buildCmd('v1.0.0');
// Returns: ['tag', 'v1.0.0']

// 建立附註標籤並包含訊息 / Create an annotated tag with message
buildCmd('v1.0.0', { annotated: true, message: 'Release v1.0.0' });
// Returns: ['tag', '-a', 'v1.0.0', '-m', 'Release v1.0.0']

// 建立強制覆蓋的簽章標籤 / Create a force-overwrite signed tag
buildCmd('v2.0.0', { forceGitTag: true, signGitTag: true });
// Returns: ['tag', 'v2.0.0', '--force', '--sign']

Types

IOptions

Git Tag 操作選項 / Git Tag operation options

| Property | Type | Description | |----------|------|-------------| | cwd | string | 工作目錄路徑 / Working directory path | | message | string | 標籤訊息 / Tag message | | forceGitTag | boolean | 是否強制覆蓋已存在的標籤 / Whether to force overwrite existing tags | | signGitTag | boolean | 是否對標籤進行 GPG 簽章 / Whether to GPG sign the tag | | annotated | boolean | 是否建立附註標籤 / Whether to create an annotated tag | | target | string | 目標物件（Commit SHA、Branch 等）/ Target object |

License

ISC