@git-lazy/diff-staged

Git staged area diff utilities — Retrieve lists of staged files, directories, and changed file paths from Git repositories

Installation

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

Usage

import gitDiffStagedFile, { gitDiffStaged, gitDiffStagedDir, gitDiffStagedFile as named } from '@git-lazy/diff-staged';

// 取得已暫存的檔案清單
const stagedFiles = gitDiffStaged('/path/to/repo');
console.log(stagedFiles);
// ['src/index.ts', 'README.md']

// 取得有檔案被暫存的目錄清單
const stagedDirs = gitDiffStagedDir('/path/to/repo');
console.log(stagedDirs);
// ['src/', 'docs/', 'tests/']

// 取得所有已變更檔案（含暫存與未暫存）的相對路徑
const changedFiles = gitDiffStagedFile('/path/to/repo');
console.log(changedFiles);
// ['src/index.ts', 'src/utils.ts', 'README.md']

// 使用自訂 git 執行檔路徑
const stagedFilesCustom = gitDiffStaged('/path/to/repo', {
  bin: '/usr/local/bin/git'
});

API

IOptions

Git 差異比對選項 / Git diff options

Properties:

• bin (string, optional) - Git 執行檔路徑，預設為 'git' / Git binary path, defaults to 'git'

gitDiffStaged(git_root, options?)

取得暫存區中已暫存的檔案路徑清單 / Get list of staged file paths from the staging area

使用 git diff --cached --name-only 指令取得已暫存（staged）的檔案名稱。僅回傳暫存區中的檔案，不包含工作目錄中未暫存的變更。

Parameters:

• git_root (string) - Git 儲存庫根目錄路徑 / Git repository root directory path
• options (IOptions, optional) - 可選設定物件 / Optional configuration object

Returns: string[] - 已暫存檔案路徑陣列 / Array of staged file paths

Example:

import { gitDiffStaged } from '@git-lazy/diff-staged';

// 取得指定 Git 儲存庫中已暫存的檔案清單
const stagedFiles = gitDiffStaged('/path/to/repo');
console.log(stagedFiles);
// ['src/index.ts', 'README.md']

// 使用自訂 git 執行檔路徑
const stagedFiles = gitDiffStaged('/path/to/repo', {
  bin: '/usr/local/bin/git'
});

gitDiffStagedDir(git_root, options?)

取得暫存區中已暫存檔案所屬的目錄清單 / Get list of directories containing staged files

結合 --cached（暫存區）與非 --cached（工作目錄）的目錄統計資訊，使用 --dirstat=files,0 參數取得每個目錄的變更統計，並透過正則表達式移除百分比前綴，僅保留目錄路徑。

Parameters:

• git_root (string) - Git 儲存庫根目錄路徑 / Git repository root directory path
• options (IOptions, optional) - 可選設定物件 / Optional configuration object

Returns: string[] - 包含已暫存檔案的目錄路徑陣列 / Array of directory paths containing staged files

Example:

import { gitDiffStagedDir } from '@git-lazy/diff-staged';

// 取得有檔案被暫存的目錄清單
const stagedDirs = gitDiffStagedDir('/path/to/repo');
console.log(stagedDirs);
// ['src/', 'docs/', 'tests/']

gitDiffStagedFile(git_root, options?)

取得暫存區與工作目錄中已變更檔案的相對路徑清單 / Get list of relative paths for changed files in both staging area and working directory

結合 --cached（暫存區）與非 --cached（工作目錄）的檔案清單，使用 --relative 確保路徑相對於當前工作目錄。適用於需要同時追蹤已暫存與未暫存變更的場景。此函式也是模組的預設匯出。

Parameters:

• git_root (string) - Git 儲存庫根目錄路徑 / Git repository root directory path
• options (IOptions, optional) - 可選設定物件 / Optional configuration object

Returns: string[] - 已變更檔案的相對路徑陣列 / Array of relative paths for changed files

Example:

import { gitDiffStagedFile } from '@git-lazy/diff-staged';

// 取得所有已變更檔案（含暫存與未暫存）的相對路徑
const changedFiles = gitDiffStagedFile('/path/to/repo');
console.log(changedFiles);
// ['src/index.ts', 'src/utils.ts', 'README.md']

// 此函式也是模組的預設匯出
import gitDiffStagedFile from '@git-lazy/diff-staged';

const files = gitDiffStagedFile(process.cwd());

Dependencies

• @git-lazy/root - ^1.0.39
• @git-lazy/spawn - ^1.0.41
• tslib - ^2.8.1

License

ISC