@git-lazy/tag-list

Retrieve and query git tag lists with sorting, filtering, and merged-branch support

Installation

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

Usage

import { gitTagList, gitTagListSync, buildCmd, EnumSort } from '@git-lazy/tag-list';

// 獲取最近 20 個提交的標籤 / Get tags within recent 20 commits
const tags = await gitTagList();
// [['v1.0.0', Date], ['v1.0.1', Date], ...]

// 獲取所有標籤並按建立日期排序 / Get all tags sorted by creation date
const allTags = await gitTagList({ target: null, sort: EnumSort.creatordate });

// 指定工作目錄 / Specify working directory
const tagsInProject = await gitTagList({ cwd: '/path/to/repo' });

// 獲取已合併到 main 分支的標籤 / Get tags merged into main branch
const mergedTags = await gitTagList({ merged: 'main' });

// 同步獲取標籤列表 / Synchronously get tag list
const tagsSync = gitTagListSync();

API

gitTagList(options, spawnOptions)

非同步獲取 Git 標籤列表 / Asynchronously retrieve Git tag list

執行 git tag 命令並解析輸出結果，返回標籤名稱與日期的配對陣列 Executes the git tag command and parses the output, returning an array of tag name and date pairs

Parameters:

• options (IOptions) - 標籤列表選項 / Tag list options
  • cwd (string) - 工作目錄路徑 / Working directory path
  • sort (string | EnumSort) - 排序方式 / Sort mode
  • target (string | null) - 目標參考點（預設 'HEAD~20'）/ Target reference point (default 'HEAD~20')
  • merged (string) - 已合併到指定分支的標籤過濾 / Filter tags merged into specified branch
• spawnOptions (ISpawnGitAsyncOptions) - 子進程選項 / Spawn process options

Returns: Promise<[string, Date][]> - [標籤名稱, 日期] 的陣列 / Array of [tag name, date]

Example:

import { gitTagList, EnumSort } from '@git-lazy/tag-list';

// 獲取最近 20 個提交的標籤 / Get tags within recent 20 commits
const tags = await gitTagList();
// [['v1.0.0', Date], ['v1.0.1', Date], ...]

// 獲取所有標籤並按建立日期排序 / Get all tags sorted by creation date
const allTags = await gitTagList({ target: null, sort: EnumSort.creatordate });

// 指定工作目錄 / Specify working directory
const tagsInProject = await gitTagList({ cwd: '/path/to/repo' });

// 獲取已合併到 main 分支的標籤 / Get tags merged into main branch
const mergedTags = await gitTagList({ merged: 'main' });

gitTagListSync(options, spawnOptions)

同步獲取 Git 標籤列表 / Synchronously retrieve Git tag list

與 gitTagList 功能相同，但採用同步方式執行 Same functionality as gitTagList, but executed synchronously

Parameters:

• options (IOptions) - 標籤列表選項 / Tag list options
  • cwd (string) - 工作目錄路徑 / Working directory path
  • sort (string | EnumSort) - 排序方式 / Sort mode
  • target (string | null) - 目標參考點（預設 'HEAD~20'）/ Target reference point (default 'HEAD~20')
  • merged (string) - 已合併到指定分支的標籤過濾 / Filter tags merged into specified branch
• spawnOptions (ISpawnGitAsyncOptions) - 子進程選項 / Spawn process options

Returns: [string, Date][] - [標籤名稱, 日期] 的陣列 / Array of [tag name, date]

Example:

import { gitTagListSync, EnumSort } from '@git-lazy/tag-list';

// 同步獲取標籤列表 / Synchronously get tag list
const tags = gitTagListSync();
// [['v1.0.0', Date], ['v1.0.1', Date], ...]

// 獲取所有標籤 / Get all tags
const allTags = gitTagListSync({ target: null });

buildCmd(options)

建立 Git 標籤查詢命令參數 / Build Git tag query command arguments

根據選項組建 git tag 命令的參數陣列 Assembles the argument array for the git tag command based on options

Parameters:

• options (IOptions) - 標籤列表選項 / Tag list options

Returns: string[] - Git 命令參數陣列 / Git command argument array

Example:

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

// 預設查詢（HEAD~20 以內的標籤）/ Default query (tags within HEAD~20)
const args = buildCmd();
// ['tag', '--format', ';%(...)', '--contains', 'HEAD~20', '--sort', 'taggerdate']

// 查詢所有標籤並按建立日期排序 / Query all tags sorted by creation date
const allArgs = buildCmd({ target: null, sort: EnumSort.creatordate });

// 查詢已合併到 main 分支的標籤 / Query tags merged into main branch
const mergedArgs = buildCmd({ merged: 'main' });

_handleResult(list)

處理 Git 標籤命令的原始輸出結果 / Process raw output from Git tag command

解析格式化的標籤輸出，提取標籤名稱和日期，並按日期降序排序 Parses formatted tag output, extracts tag names and dates, and sorts by date in descending order

Parameters:

• list (string[]) - 原始輸出字串陣列 / Raw output string array

Returns: [string, Date][] - [標籤名稱, 日期] 的陣列，按日期降序排列 / Array of [tag name, date], sorted by date descending

Example:

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

const rawOutput = [
  ';2024-01-01T00:00:00+00:00\t\t2024-01-01T00:00:00+00:00\t\tv1.0.0',
  ';2024-01-15T00:00:00+00:00\t\t2024-01-15T00:00:00+00:00\t\tv1.1.0',
];

const result = _handleResult(rawOutput);
// [['v1.1.0', Date], ['v1.0.0', Date]] - 按日期降序 / sorted by date descending

Types

IOptions

Git 標籤列表選項介面 / Git tag list options interface

| Property | Type | Description | |----------|------|-------------| | cwd | string | 工作目錄路徑 / Working directory path | | sort | string | EnumSort | 排序方式 / Sort mode | | target | string | null | 目標參考點（預設 'HEAD~20'）/ Target reference point (default 'HEAD~20') | | merged | string | 已合併到指定分支的標籤過濾 / Filter tags merged into specified branch |

EnumSort

Git 標籤排序方式列舉 / Git tag sort mode enumeration

| Value | Description | |-------|-------------| | commiterdate | 提交者日期 / Committer date | | taggerdate | 標籤者日期（用於 annotated tags）/ Tagger date (for annotated tags) | | creatordate | 建立者日期（自動選擇 committerdate 或 taggerdate）/ Creator date (auto-selects committerdate or taggerdate) | | refname | 引用名稱（按字母順序）/ Reference name (alphabetical order) |

License

ISC