@git-lazy/git-dir-path

Search upward from a directory to find the Git repository root, supporting sync and async modes with GIT_DIR environment variable awareness

Installation

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

Usage

import { findGitDir, findGitDirAsync } from '@git-lazy/git-dir-path';

// 同步尋找 / Synchronous find
const gitDir = findGitDir();
// => '/path/to/project/.git'

// 從指定目錄尋找 / Find from specific directory
const gitDir = findGitDir({ cwd: '/some/nested/dir' });

// 非同步尋找 / Asynchronous find
const gitDir = await findGitDirAsync();

// 找不到時拋出錯誤 / Throw error if not found
const gitDir = findGitDir({ throwIfNoEntry: true });

API

findGitDir(options?)

同步尋找 Git 目錄 / Synchronously find the Git directory

從指定的目錄開始向上尋找 .git 目錄（或 GIT_DIR 環境變數指定的名稱）。 Searches upward from the specified directory for the .git directory (or the name specified by the GIT_DIR environment variable).

Parameters:

• options (IOptionsFindGitDir) - 搜尋選項 / Search options
  • cwd (string) - 開始搜尋的目錄路徑，預設為當前工作目錄 / Starting directory path for the search, defaults to current working directory
  • env (Record<string, string>) - 用於覆寫環境變數的物件，主要用於測試 / Environment variables object to override process environment variables, primarily for testing
  • throwIfNoEntry (boolean) - 找不到目標時是否拋出錯誤，預設為 false / Whether to throw an error when the target is not found, defaults to false

Returns: string | undefined - 找到的 Git 目錄路徑，找不到時返回 undefined（除非 throwIfNoEntry: true）/ Found Git directory path, or undefined if not found (unless throwIfNoEntry: true)

Example:

import { findGitDir } from '@git-lazy/git-dir-path';

// 從當前目錄尋找 / Find from current directory
const gitDir = findGitDir();
// => '/path/to/project/.git'

// 從指定目錄尋找 / Find from specific directory
const gitDir = findGitDir({ cwd: '/some/nested/dir' });
// => '/path/to/project/.git'（向上尋找到最近的 .git）

// 覆寫環境變數（用於測試）/ Override environment variable (for testing)
const gitDir = findGitDir({
  cwd: '/path/to/project',
  env: { GIT_DIR: '.custom-git' }
});

findGitDirAsync(options?)

非同步尋找 Git 目錄 / Asynchronously find the Git directory

與 findGitDir 功能相同，但使用非同步方式執行，適合在需要避免阻塞主執行緒的情境中使用。 Same functionality as findGitDir, but executes asynchronously, suitable for scenarios where blocking the main thread should be avoided.

Parameters:

• options (IOptionsFindGitDir) - 搜尋選項 / Search options
  • cwd (string) - 開始搜尋的目錄路徑 / Starting directory path for the search
  • env (Record<string, string>) - 用於覆寫環境變數的物件 / Environment variables object to override process environment variables
  • throwIfNoEntry (boolean) - 找不到目標時是否拋出錯誤 / Whether to throw an error when the target is not found

Returns: Promise<string | undefined> - Promise，解析為找到的 Git 目錄路徑或 undefined / Promise resolving to found Git directory path or undefined

Example:

import { findGitDirAsync } from '@git-lazy/git-dir-path';

async function getProjectRoot() {
  const gitDir = await findGitDirAsync();
  if (gitDir) {
    console.log('Git 目錄位於 / Git directory located at:', gitDir);
  }
}

IOptionsFindGitDir

尋找 Git 目錄的選項介面 / Options interface for finding Git directory

Properties:

• cwd (string) - 開始搜尋的目錄路徑 / Starting directory path for the search
• env (Record<string, string>) - 環境變數物件，用於覆寫程序環境變數 / Environment variables object to override process environment variables
• throwIfNoEntry (boolean) - 找不到目標時是否拋出錯誤 / Whether to throw an error when the target is not found

Dependencies

• @git-lazy/git-env-var - Git 環境變數型別定義與輔助函式
• find-up-paths - 向上尋找檔案或目錄

License

ISC