Git toolkit

Git command runner & client for interacting with git repositories.

Description

This package provides a reworked version of @conventional-changelog/git-client without conventional git client logic.

Install

# Using yarn
yarn add @modulify/git-toolkit

# Using npm
npm install @modulify/git-toolkit

---

Requirements

• Node.js: >=20.0.0

Usage

GitCommander:

import { GitCommander } from '@modulify/git-toolkit'

const git = new GitCommander()

await git.add('package.json')
await git.commit({ message: 'chore: release v1.0.0' })
await git.tag({ name: 'v1.0.0' })
await git.push('main')

GitClient:

import { GitClient } from '@modulify/git-toolkit'

const git = new GitClient()

for await (const commit in git.commits()) {
  console.log(commit)
}

for await (const tag in git.tags()) {
  console.log(tag)
}

API

GitCommander

The GitCommander class provides a set of methods to interact with Git functionality programmatically. It wraps basic Git commands with support for advanced options.

Constructor

constructor(options: { cwd?: string, sh?: Runner } = {})

• options (optional):
  • cwd (string): The current working directory for Git operations.
  • sh (Runner): An optional custom shell runner instance. If not provided, a new instance of the Runner class is created.

Properties

• cwd: (string) - Returns the current working directory (cwd) used by the Runner instance.

Methods

1. add(files: string[]): Promise<void>

   • Adds the specified files to the Git index.
   • parameters:
     • files: (string[]) - List of file paths to stage.

2. checkIgnore(file: string): Promise<boolean>

   • Checks if a file is ignored via .gitignore.

   • parameters:

     • file: (string) - The file path to check.

   • returns: (boolean) - true if the file is ignored, otherwise false.

3. commit(options: GitCommitOptions): Promise<void>

   • Commits changes with the specified options.
   • Runs Git hooks by default. Use verify: false to pass --no-verify when operating on repositories where hooks must not run.
   • parameters:
     • options: (GitCommitOptions) - Object with commit options. Includes:
       • message: (string) - Commit message.
       • sign: (boolean) (optional) - Sign the commit.
       • files: (string[]) (optional) - List of file paths to commit.
       • verify: (boolean) (optional, default: true) - Whether to verify the commit.

4. log(options?: GitLogOptions): string

   • Retrieves the Git log with the specified options.

   • parameters:

     • options: (GitLogOptions) (optional) - Object with options such as from, to, since, order, etc.

   • returns: (string) - The git log output.

5. push(branch: string): Promise<void>

   • Pushes changes to the remote repository for the specified branch.
   • parameters:
     • branch: (string) - The branch to push.

6. revParse(rev: string, options?: GitRevParseOptions): Promise<string>

   • Resolves a Git revision to a specific commit ID.
   • parameters:
     • rev: (string) - The revision to parse.
     • options: (GitRevParseOptions) (optional) - Additional options such as abbrevRef and verify.

7. show(rev: string, path: string): Promise<string | undefined>

   • Shows the content of a file in a specific revision.

   • parameters:

     • rev: (string) - The revision to show.
     • path: (string) - The file path.

   • returns: (string | undefined) - The file's content or undefined if it doesn't exist in the revision.

8. tag(options: GitTagOptions): Promise<void>

   • Creates a tag for the current commit.
   • parameters:
     • options: (GitTagOptions) - Tagging options, including name, sign, and message.

9. exec(cmd: string, args: Arg[], options?: RunnerOptions): Promise<string>

   • Executes a raw Git command.
   • shell mode is not supported; commands are executed with argv arrays.
   • parameters:
     • cmd: (string) - The Git command to execute.
     • args: (Arg[]) - Arguments for the command.
     • options: (RunnerOptions) (optional) - Process execution options and output buffer limits.

10. run(cmd: string, args: Arg[], options?: RunnerOptions): TextStream

    • Runs a Git command (lower-level than exec()).
    • shell mode is not supported; commands are executed with argv arrays.
    • parameters:
      • cmd, args, options: Same as exec().
    • returns: (TextStream) - The command's output stream, where each chunk is string.

Security Notes

• High-level Git options are runtime-validated before spawning Git.
• Revision-like values such as from, to, and rev must not start with -.
• Runner rejects shell mode to avoid turning argv arrays into shell commands.
• Full-output helpers enforce configurable buffer limits to avoid unbounded memory use.
• commit() may run Git hooks unless verify: false is used.

GitClient

The GitClient class extends the functionality of the GitCommander and provides additional utilities for working with Git data as streams.

Constructor

constructor(options: { cwd?: string, sh?: Runner } = {})

• options (optional):
  • cwd (string): The current working directory for Git operations.
  • sh (Runner): An optional custom shell runner instance.

Properties

• cmd: (GitCommander) – The GitCommander instance used by the client.

Methods

1. commits<T = string>(options?: GitLogOptions & { ignore?: RegExp, parser?: (raw: string) => T }): AsyncStream<T>

   • Retrieves a stream of Git commits based on the specified options.

   • parameters:

     • options (optional) – extends GitLogOptions with following:
       • ignore: (RegExp) (optional) – A pattern to filter out unwanted commits.
       • parser: (function) (default: returns raw string) – A custom parser for each commit. Provides opportunity to transform raw commits to any form needed.

   • returns: (AsyncStream) – Stream of parsed commit data.

2. tags(): AsyncStream<string>

   • Retrieves a stream of Git tags sorted by date.
   • returns: (AsyncStream) – Stream of Git tags.