git-chopstick-core 0.1.0

package/src/git/format-patch.ts

@@ -0,0 +1,17 @@
+import { revRange } from './rev-list'
+import { Repository } from '../models/repository'
+import { git } from '.'
+
+/**
+ * Generate a patch representing the changes associated with a range of commits
+ *
+ * @param repository where to generate path from
+ * @param base starting commit in range
+ * @param head ending commit in rage
+ * @returns patch generated
+ */
+export function formatPatch({ path }: Repository, base: string, head: string) {
+  const range = revRange(base, head)
+  const args = ['format-patch', '--unified=1', '--minimal', '--stdout', range]
+  return git(args, path, 'formatPatch').then(x => x.stdout)
+}

package/src/git/git-delimiter-parser.ts

@@ -0,0 +1,95 @@
+import { splitBuffer } from '../lib/split-buffer'
+
+/**
+ * Create a new parser suitable for parsing --format output from commands such
+ * as `git log`, `git stash`, and other commands that are not derived from
+ * `ref-filter`.
+ *
+ * Returns an object with the arguments that need to be appended to the git
+ * call and the parse function itself
+ *
+ * @param fields An object keyed on the friendly name of the value being
+ *               parsed with the value being the format string of said value.
+ *
+ *               Example:
+ *
+ *               `const { args, parse } = createLogParser({ sha: '%H' })`
+ */
+export function createLogParser<T extends Record<string, string>>(fields: T) {
+  const keys: Array<keyof T> = Object.keys(fields)
+  const format = Object.values(fields).join('%x00')
+  const formatArgs = ['-z', `--format=${format}`]
+
+  const parse = <V extends string | Buffer>(value: V) => {
+    const records = (
+      Buffer.isBuffer(value) ? splitBuffer(value, '\0') : value.split('\0')
+    ) as V[]
+    const entries = []
+
+    for (let i = 0; i < records.length - keys.length; i += keys.length) {
+      const entry = {} as { [K in keyof T]: V }
+      keys.forEach((key, ix) => (entry[key] = records[i + ix]))
+      entries.push(entry)
+    }
+
+    return entries
+  }
+
+  return { formatArgs, parse }
+}
+
+/**
+ * Create a new parser suitable for parsing --format output from commands such
+ * as `git for-each-ref`, `git branch`, and other commands that are not derived
+ * from `git log`.
+ *
+ * Returns an object with the arguments that need to be appended to the git
+ * call and the parse function itself
+ *
+ * @param fields An object keyed on the friendly name of the value being
+ *               parsed with the value being the format string of said value.
+ *
+ *               Example:
+ *
+ *               `const { args, parse } = createForEachRefParser({ sha: '%(objectname)' })`
+ */
+export function createForEachRefParser<T extends Record<string, string>>(
+  fields: T
+) {
+  const keys: Array<keyof T> = Object.keys(fields)
+  const format = Object.values(fields).join('%00')
+  const formatArgs = [`--format=%00${format}%00`]
+
+  const parse = (value: string) => {
+    const records = value.split('\0')
+    const entries = new Array<{ [K in keyof T]: string }>()
+
+    let entry
+    let consumed = 0
+
+    // start at 1 to avoid 0 modulo X problem. The first record is guaranteed
+    // to be empty anyway (due to %00 at the start of --format)
+    for (let i = 1; i < records.length - 1; i++) {
+      if (i % (keys.length + 1) === 0) {
+        if (records[i] !== '\n') {
+          throw new Error('Expected newline')
+        }
+        continue
+      }
+
+      entry = entry ?? ({} as { [K in keyof T]: string })
+      const key = keys[consumed % keys.length]
+      entry[key] = records[i]
+      consumed++
+
+      if (consumed % keys.length === 0) {
+        entries.push(entry)
+        entry = undefined
+      }
+    }
+
+    return entries
+  }
+
+  return { formatArgs, parse }
+}

package/src/git/gitignore.ts

@@ -0,0 +1,157 @@
+import * as Path from 'path'
+import * as FS from 'fs'
+import { Repository } from '../models/repository'
+import { getConfigValue } from './config'
+import { writeFile } from 'fs/promises'
+
+/**
+ * Read the contents of the repository .gitignore.
+ *
+ * Returns a promise which will either be rejected or resolved
+ * with the contents of the file. If there's no .gitignore file
+ * in the repository root the promise will resolve with null.
+ */
+export async function readGitIgnoreAtRoot(
+  repository: Repository
+): Promise<string | null> {
+  const ignorePath = Path.join(repository.path, '.gitignore')
+
+  return new Promise<string | null>((resolve, reject) => {
+    FS.readFile(ignorePath, 'utf8', (err, data) => {
+      if (err) {
+        if (err.code === 'ENOENT') {
+          resolve(null)
+        } else {
+          reject(err)
+        }
+      } else {
+        resolve(data)
+      }
+    })
+  })
+}
+
+/**
+ * Persist the given content to the repository root .gitignore.
+ *
+ * If the repository root doesn't contain a .gitignore file one
+ * will be created, otherwise the current file will be overwritten.
+ */
+export async function saveGitIgnore(
+  repository: Repository,
+  text: string
+): Promise<void> {
+  const ignorePath = Path.join(repository.path, '.gitignore')
+
+  if (text === '') {
+    return new Promise<void>((resolve, reject) => {
+      FS.unlink(ignorePath, err => {
+        if (err) {
+          reject(err)
+        } else {
+          resolve()
+        }
+      })
+    })
+  }
+
+  const fileContents = await formatGitIgnoreContents(text, repository)
+  await writeFile(ignorePath, fileContents)
+}
+
+/** Add the given pattern or patterns to the root gitignore file */
+export async function appendIgnoreRule(
+  repository: Repository,
+  patterns: string | string[]
+): Promise<void> {
+  const text = (await readGitIgnoreAtRoot(repository)) || ''
+
+  const currentContents = await formatGitIgnoreContents(text, repository)
+
+  const newPatternText =
+    patterns instanceof Array ? patterns.join('\n') : patterns
+  const newText = await formatGitIgnoreContents(
+    `${currentContents}${newPatternText}`,
+    repository
+  )
+
+  await saveGitIgnore(repository, newText)
+}
+
+/**
+ * Convenience method to add the given file path(s) to the repository's gitignore.
+ *
+ * The file path will be escaped before adding.
+ */
+export async function appendIgnoreFile(
+  repository: Repository,
+  filePath: string | string[]
+): Promise<void> {
+  if (filePath instanceof Array) {
+    const escapedFilePaths = filePath.map(path =>
+      escapeGitSpecialCharacters(path)
+    )
+
+    return appendIgnoreRule(repository, escapedFilePaths)
+  }
+
+  const escapedFilePath = escapeGitSpecialCharacters(filePath)
+  return appendIgnoreRule(repository, escapedFilePath)
+}
+
+/** Escapes a string from special characters used in a gitignore file */
+export function escapeGitSpecialCharacters(pattern: string): string {
+  const specialCharacters = /[\[\]!\*\#\?]/g
+
+  return pattern.replaceAll(specialCharacters, match => {
+    return '\\' + match
+  })
+}
+
+/**
+ * Format the gitignore text based on the current config settings.
+ *
+ * This setting looks at core.autocrlf to decide which line endings to use
+ * when updating the .gitignore file.
+ *
+ * If core.safecrlf is also set, adding this file to the index may cause
+ * Git to return a non-zero exit code, leaving the working directory in a
+ * confusing state for the user. So we should reformat the file in that
+ * case.
+ *
+ * @param text The text to format.
+ * @param repository The repository associated with the gitignore file.
+ */
+async function formatGitIgnoreContents(
+  text: string,
+  repository: Repository
+): Promise<string> {
+  const autocrlf = await getConfigValue(repository, 'core.autocrlf')
+  const safecrlf = await getConfigValue(repository, 'core.safecrlf')
+
+  return new Promise<string>((resolve, reject) => {
+    if (autocrlf === 'true' && safecrlf === 'true') {
+      // based off https://stackoverflow.com/a/141069/1363815
+      const normalizedText = text.replace(/\r\n|\n\r|\n|\r/g, '\r\n')
+      resolve(normalizedText + '\r\n')
+      return
+    }
+
+    if (text === '' || text.endsWith('\n')) {
+      resolve(text)
+      return
+    }
+
+    if (autocrlf == null) {
+      // fallback to Git default behaviour
+      resolve(`${text}\n`)
+    } else {
+      const linesEndInCRLF = autocrlf === 'true'
+      if (linesEndInCRLF) {
+        resolve(`${text}\n`)
+      } else {
+        resolve(`${text}\r\n`)
+      }
+    }
+  })
+}

package/src/git/index.ts

@@ -0,0 +1,36 @@
+export * from './apply'
+export * from './branch'
+export * from './checkout'
+export * from './clone'
+export * from './commit'
+export * from './config'
+export * from './core'
+export * from './description'
+export * from './diff'
+export * from './fetch'
+export * from './for-each-ref'
+export * from './init'
+export * from './log'
+export * from './pull'
+export * from './push'
+export * from './reflog'
+export * from './refs'
+export * from './remote'
+export * from './reset'
+export * from './rev-list'
+export * from './rev-parse'
+export * from './status'
+export * from './update-ref'
+export * from './var'
+export * from './merge'
+export * from './diff-index'
+export * from './checkout-index'
+export * from './revert'
+export * from './rm'
+export * from './submodule'
+export * from './interpret-trailers'
+export * from './gitignore'
+export * from './rebase'
+export * from './format-patch'
+export * from './tag'
+export * from './worktree'

package/src/git/init.ts

@@ -0,0 +1,11 @@
+import { getDefaultBranch } from '../lib/helpers/default-branch'
+import { git } from './core'
+
+/** Init a new git repository in the given path. */
+export async function initGitRepository(path: string): Promise<void> {
+  await git(
+    ['-c', `init.defaultBranch=${await getDefaultBranch()}`, 'init'],
+    path,
+    'initGitRepository'
+  )
+}

package/src/git/interpret-trailers.ts

@@ -0,0 +1,176 @@
+import { git } from './core'
+import { Repository } from '../models/repository'
+import { getConfigValue } from './config'
+
+/**
+ * A representation of a Git commit message trailer.
+ *
+ * See git-interpret-trailers for more information.
+ */
+export interface ITrailer {
+  readonly token: string
+  readonly value: string
+}
+
+/**
+ * Gets a value indicating whether the trailer token is
+ * Co-Authored-By. Does not validate the token value.
+ */
+export function isCoAuthoredByTrailer(trailer: ITrailer) {
+  return trailer.token.toLowerCase() === 'co-authored-by'
+}
+
+/**
+ * Parse a string containing only unfolded trailers produced by
+ * git-interpret-trailers --only-input --only-trailers --unfold or
+ * a derivative such as git log --format="%(trailers:only,unfold)"
+ *
+ * @param trailers   A string containing one well formed trailer per
+ *                   line
+ *
+ * @param separators A string containing all characters to use when
+ *                   attempting to find the separator between token
+ *                   and value in a trailer. See the configuration
+ *                   option trailer.separators for more information
+ *
+ *                   Also see getTrailerSeparatorCharacters.
+ */
+export function parseRawUnfoldedTrailers(trailers: string, separators: string) {
+  const lines = trailers.split('\n')
+  const parsedTrailers = new Array<ITrailer>()
+
+  for (const line of lines) {
+    const trailer = parseSingleUnfoldedTrailer(line, separators)
+
+    if (trailer) {
+      parsedTrailers.push(trailer)
+    }
+  }
+
+  return parsedTrailers
+}
+
+export function parseSingleUnfoldedTrailer(
+  line: string,
+  separators: string
+): ITrailer | null {
+  for (const separator of separators) {
+    const ix = line.indexOf(separator)
+    if (ix > 0) {
+      return {
+        token: line.substring(0, ix).trim(),
+        value: line.substring(ix + 1).trim(),
+      }
+    }
+  }
+
+  return null
+}
+
+/**
+ * Get a string containing the characters that may be used in this repository
+ * separate tokens from values in commit message trailers. If no specific
+ * trailer separator is configured the default separator (:) will be returned.
+ */
+export async function getTrailerSeparatorCharacters(
+  repository: Repository
+): Promise<string> {
+  return (await getConfigValue(repository, 'trailer.separators')) || ':'
+}
+
+/**
+ * Extract commit message trailers from a commit message.
+ *
+ * The trailers returned here are unfolded, i.e. they've had their
+ * whitespace continuation removed and are all on one line. See the
+ * documentation for --unfold in the help for `git interpret-trailers`
+ *
+ * @param repository    The repository in which to run the interpret-
+ *                      trailers command. Although not intuitive this
+ *                      does matter as there are configuration options
+ *                      available for the format, position, etc of commit
+ *                      message trailers. See the manpage for
+ *                      git-interpret-trailers for more information.
+ *
+ * @param commitMessage A commit message from where to attempt to extract
+ *                      commit message trailers.
+ *
+ * @returns An array of zero or more parsed trailers
+ */
+export async function parseTrailers(
+  repository: Repository,
+  commitMessage: string
+): Promise<ReadonlyArray<ITrailer>> {
+  const result = await git(
+    ['interpret-trailers', '--parse'],
+    repository.path,
+    'parseTrailers',
+    {
+      stdin: commitMessage,
+    }
+  )
+
+  const trailers = result.stdout
+
+  if (trailers.length === 0) {
+    return []
+  }
+
+  const separators = await getTrailerSeparatorCharacters(repository)
+  return parseRawUnfoldedTrailers(result.stdout, separators)
+}
+
+/**
+ * Merge one or more commit message trailers into a commit message.
+ *
+ * If no trailers are given this method will simply try to ensure that
+ * any trailers that happen to be part of the raw message are formatted
+ * in accordance with the configuration options set for trailers in
+ * the given repository.
+ *
+ * Note that configuration may be set so that duplicate trailers are
+ * kept or discarded.
+ *
+ * @param repository    The repository in which to run the interpret-
+ *                      trailers command. Although not intuitive this
+ *                      does matter as there are configuration options
+ *                      available for the format, position, etc of commit
+ *                      message trailers. See the manpage for
+ *                      git-interpret-trailers for more information.
+ *
+ * @param commitMessage A commit message with or without existing commit
+ *                      message trailers into which to merge the trailers
+ *                      given in the trailers parameter
+ *
+ * @param trailers      Zero or more trailers to merge into the commit message
+ *
+ * @returns             A commit message string where the provided trailers (if)
+ *                      any have been merged into the commit message using the
+ *                      configuration settings for trailers in the provided
+ *                      repository.
+ */
+export async function mergeTrailers(
+  repository: Repository,
+  commitMessage: string,
+  trailers: ReadonlyArray<ITrailer>,
+  unfold: boolean = false
+) {
+  const args = ['interpret-trailers']
+
+  // See https://github.com/git/git/blob/ebf3c04b262aa/Documentation/git-interpret-trailers.txt#L129-L132
+  args.push('--no-divider')
+
+  if (unfold) {
+    args.push('--unfold')
+  }
+
+  for (const trailer of trailers) {
+    args.push('--trailer', `${trailer.token}=${trailer.value}`)
+  }
+
+  const result = await git(args, repository.path, 'mergeTrailers', {
+    stdin: commitMessage,
+  })
+
+  return result.stdout
+}

package/src/git/lfs.ts

@@ -0,0 +1,100 @@
+import { git } from './core'
+import { Repository } from '../models/repository'
+
+/** Install the global LFS filters. */
+export async function installGlobalLFSFilters(force: boolean): Promise<void> {
+  const args = ['lfs', 'install', '--skip-repo']
+  if (force) {
+    args.push('--force')
+  }
+
+  await git(args, __dirname, 'installGlobalLFSFilter')
+}
+
+/** Install LFS hooks in the repository. */
+export async function installLFSHooks(
+  repository: Repository,
+  force: boolean
+): Promise<void> {
+  const args = ['lfs', 'install']
+  if (force) {
+    args.push('--force')
+  }
+
+  await git(args, repository.path, 'installLFSHooks')
+}
+
+/** Is the repository configured to track any paths with LFS? */
+export async function isUsingLFS(repository: Repository): Promise<boolean> {
+  const env = {
+    GIT_LFS_TRACK_NO_INSTALL_HOOKS: '1',
+  }
+  const result = await git(['lfs', 'track'], repository.path, 'isUsingLFS', {
+    env,
+  })
+  return result.stdout.length > 0
+}
+
+/**
+ * Check if a provided file path is being tracked by Git LFS
+ *
+ * This uses the Git plumbing to read the .gitattributes file
+ * for any LFS-related rules that are set for the file
+ *
+ * @param repository repository with
+ * @param path relative file path in the repository
+ */
+export async function isTrackedByLFS(
+  repository: Repository,
+  path: string
+): Promise<boolean> {
+  const { stdout } = await git(
+    ['check-attr', 'filter', path],
+    repository.path,
+    'checkAttrForLFS'
+  )
+
+  // "git check-attr -a" will output every filter it can find in .gitattributes
+  // and it looks like this:
+  //
+  // README.md: diff: lfs
+  // README.md: merge: lfs
+  // README.md: text: unset
+  // README.md: filter: lfs
+  //
+  // To verify git-lfs this test will just focus on that last row, "filter",
+  // and the value associated with it. If nothing is found in .gitattributes
+  // the output will look like this
+  //
+  // README.md: filter: unspecified
+
+  const lfsFilterRegex = /: filter: lfs/
+
+  const match = lfsFilterRegex.exec(stdout)
+
+  return match !== null
+}
+
+/**
+ * Query a Git repository and filter the set of provided relative paths to see
+ * which are not covered by the current Git LFS configuration.
+ *
+ * @param repository
+ * @param filePaths List of relative paths in the repository
+ */
+export async function filesNotTrackedByLFS(
+  repository: Repository,
+  filePaths: ReadonlyArray<string>
+): Promise<ReadonlyArray<string>> {
+  const filesNotTrackedByGitLFS = new Array<string>()
+
+  for (const file of filePaths) {
+    const isTracked = await isTrackedByLFS(repository, file)
+
+    if (!isTracked) {
+      filesNotTrackedByGitLFS.push(file)
+    }
+  }
+
+  return filesNotTrackedByGitLFS
+}