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-client'

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-client'

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.
   • 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?: SpawnOptionsWithoutStdio): Promise<string>

   • Executes a raw Git command.
   • parameters:
     • cmd: (string) - The Git command to execute.
     • args: (Arg[]) - Arguments for the command.
     • options: (SpawnOptionsWithoutStdio) (optional) - Shell execution options.

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

    • Runs a Git command (lower-level than exec()).
    • parameters:
      • cmd, args, options: Same as exec().
    • returns: (TextStream) - The command's output stream, where each chunk is string.

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.