APIs
@haetae/git

@haetae/git

@haetae/git is a convenient git integration with Haetae.
If you don't use git as a version control system, you don't need this package.

peerDependencies

Note: This might not be exhaustive and lists only Haetae's packages.

Dependents

Installation

💡

Are you developing a library(e.g. plugin) for Haetae?
It might be more suitable to specify @haetae/git as peerDependencies than dependencies.

To automatically install @haetae/git and its peerDependencies

You may want to install @haetae/git and its peerDependencies all at once.
install-peerdeps (opens in a new tab) is a good tool for that.


# As dependencies
npx install-peerdeps @haetae/git
# As devDependencies
npx install-peerdeps --dev @haetae/git

To manually handle installation

You might want to manually deal with installation.
First, install @haetae/git itself.


# As dependencies
npm install @haetae/git
# As devDependencies
npm install --save-dev @haetae/git

Then, check out peerDependencies and manually handle them.
(e.g. Install them as dependencies or set them as peerDependencies)

# This does not install, but just shows peerDependencies.
npm info @haetae/git peerDependencies

API

pkg

Refer to introduction#pkg.

recordDataSpecVersion

A version of the specification of Record Data @haetae/git manages.

Value

1

RecordData

interface RecordData extends Rec {
  '@haetae/git': {
    commit: string
    branch: string
    specVersion: number
  }
}
💡

Record Data Namespace
Record Data can have arbitrary fields. '@haetae/git' is a namespace to avoid collision. Haetae uses a package name as a namespace by convention.

RecordDataOptions

An argument interface for recordData

interface RecordDataOptions {
  commit?: string
  branch?: string
  specVersion?: number
}

recordData

A function to form Record Data @haetae/git manages.

Type

(options?: RecordDataOptions) => Promise<RecordData>

Options?

  • commit? : Commit ID of HEAD. (default: commit())
  • branch? : Current branch. (default: branch())
  • specVersion? : A version of the specification of Record Data @haetae/git manages. (default: recordDataSpecVersion)

InstalledOptions

An argument interface for installed.

interface InstalledOptions {
  rootDir?: string
}

installed

A function to check whether git is installed on the system.

Type

(options?: InstalledOptions) => Promise<boolean>()

Options?

InitializedOptions

An argument interface for initialized.

interface InitializedOptions {
  rootDir?: string
}

initialized

A function to check whether a git repository is initialized (by git init).

Type

(options?: InitializedOptions) => Promise<boolean>

Options?

BranchOptions

An argument interface for branch.

interface BranchOptions {
  rootDir?: string
}

branch

A function to get the current branch name.

Type

(options?: BranchOptions) => Promise<string>

Options?

CommitOptions

An argument interface for commit.

interface CommitOptions {
  rootDir?: string
}

commit

A function to get the commit ID of HEAD.
The return value would be the full 40-character commit hash. (e.g. '63a5812b39c4d01031024f98c8890bc90830cf1b')

Type

(options?: CommitOptions) => Promise<string>

Options?

UntrackedFilesOptions

An argument interface for untrackedFiles.

interface InstalledOptions {
  rootDir?: string
}

untrackedFiles


Path Principles

A function to get a list of untracked files (opens in a new tab).
git ls-files --others --exclude-standard is executed.

Type

(options?: UntrackedFilesOptions) => Promise<string[]>

Options?

IgnoredFilesOptions

An argument interface for ignoredFiles.

interface IgnoredFilesOptions {
  rootDir?: string
}

ignoredFiles


Path Principles

A function to get a list of ignored (by .gitignore) files.
git ls-files --others --exclude-standard --ignored is executed.

Type

(options?: IgnoredFilesOptions) => Promise<string[]>

Options?

ChangedFilesOptions

An argument interface for changedFiles.

interface ChangedFilesOptions  {
  from?: string
  to?: string
  rootDir?: string
  includeUntracked?: boolean
  includeIgnored?: boolean
  filterByExistence?: boolean
  reserveRecordData?: boolean | typeof core.reserveRecordData
}

changedFiles


Memoized Path Principles

A function to get a list of changed files.

Type

(options?: ChangedFilesOptions) => Promise<string[]>

Options?

  • from? : A commit ID as a starting point of comparison. (default: Previous record's commit. undefined if there's no previous record's commit.)
  • to? : A commit ID as an ending point of comparision. (default: undefined)
  • rootDir? : A directory to execute git. (default: core.getConfigDirname())
  • includeUntracked? : Whether to include untracked (opens in a new tab) files in the result. If true, untrackedFiles() is added to the result. (default: true)
  • includeIgnored? : Whether to include ignored (by .gitignore) files in the result. If true, ignoredFiles() is added to the result. (default: false)
  • filterByExistence? : Whether to filter out non-existent files from the result. If you want to get removed files as well, set it false. (default: true)
  • reserveRecordData? : Whether to reserve Record Data. If true, core.reserveRecordData is called internally. If a function, not a boolean, is given, the function is called instead of core.reserveRecordData. (default: true)

Note that untracked files (usually newly added files not commited yet) and ignored files are different. They don't have any intersections. A file is either untracked or ignored or tracked.

When both from and to are string (NOT undefined)

All changed files between the two commits are included.
git diff --name-only <from> <to> is executed under the hood.

When only from is string (NOT undefined)

All changed files since the commit ID from are included.
git diff --name-only <from> is executed under the hood.
(Note: This also contains modified or deleted files which're not commited yet as long as they're tracked, no matter whether staged (opens in a new tab) or not, unless filterByExistence is true.)

When only to is string (NOT undefined)

All tracked (opens in a new tab) files since git initialization until the commit ID to are included.
git ls-tree --full-tree --name-only -r <to> is executed under the hood.
(Note: This does NOT contain files deleted in past commits because they became untracked and non-existent.)

When both from and to are NOT string (undefined)

All tracked (opens in a new tab) files since git initialization until HEAD are included.
git ls-tree --full-tree --name-only -r HEAD is executed under the hood.
(Note: This does NOT contain files deleted in past commits because they became untracked and non-existent.)

Usage With js.dependsOn

If your project is based on javascript ecosystem, it is a good practice to use changedFiles with js.dependsOn of @haetae/javascript.

💡

Usage with dependsOn
Using with js.dependsOn is just an example. You can use it with others, like utils.dependsOn.

haetae.config.js
import { $, core, utils, git, js } from 'haetae'
 
export default core.configure({
  // Other options are omitted for brevity.
  commands: {
    myTest: {
      run: async () => {
        const changedFiles = await git.changedFiles()
        const testFiles = await utils.glob(['**/*.test.js'])
        // An array of test files that (transitively) depend on changed files
        const affectedTestFiles = testFiles.filter((testFile) =>
          js.dependsOn({
            dependent: testFile,
            dependencies: changedFiles,
          }),
        )
 
        if (affectedTestFiles.length > 0) {
          // Equals to "pnpm jest /path/to/foo.test.ts /path/to/bar.test.ts ..."
          await $`pnpm jest ${affectedTestFiles}`
      },
    }
  },
})
@haetae/javascript@haetae/cli