cherrypick

Cherrypicks the given commit onto HEAD and updates the working tree and index. This method prepares the index and tree as if the commit were applied, but does not actually make a new commit.

Signature

class Repository {
  cherrypick(
    commit: Commit,
    options?: CherrypickOptions | undefined | null,
  ): void;
}

Parameters

• commitrequired · Commit
  

  The commit to cherrypick.

• optionsnull | CherrypickOptions
  

  Options for the cherrypick operation.

  • checkoutOptionsCheckoutOptions
    

    Options for checkout behavior when updating working directory.

    • allowConflictsboolean
      

      In safe mode, apply safe file updates even when there are conflicts instead of canceling the checkout. Defaults to false.

    • ancestorLabelstring
      

      The name of the common ancestor side of conflicts

    • conflictStyleDiff3boolean
      

      Indicates whether to include common ancestor data in diff3 format files for conflicts. Defaults to false.

    • conflictStyleMergeboolean
      

      Indicate whether a normal merge file should be written for conflicts. Defaults to false.

    • dirPermnumber
      

      Set the mode with which new directories are created. Default is 0755

    • disableFiltersboolean
      

      Indicate whether to apply filters like CRLF conversion.

    • disablePathspecMatchboolean
      

      Treat paths specified in path as exact file paths instead of as pathspecs.

    • dryRunboolean
      

      Indicate that this checkout should perform a dry run by checking for conflicts but not make any actual changes.

    • filePermnumber
      

      Set the mode with which new files are created. The default is 0644 or 0755 as dictated by the blob.

    • forceboolean
      

      Take any action necessary to get the working directory to match the target including potentially discarding modified files.

    • ourLabelstring
      

      The name of the common our side of conflicts

    • overwriteIgnoredboolean
      

      Indicate whether ignored files should be overwritten during the checkout. Defaults to true.

    • pathstring
      

      Add a path to be checked out. The path is a <a href="https://git-scm.com/docs/gitglossary.html#Documentation/gitglossary.txt-aiddefpathspecapathspec">pathspec</a> pattern, unless disablePathspecMatch is set. If no paths are specified, then all files are checked out. Otherwise only these specified paths are checked out.

    • recreateMissingboolean
      

      In safe mode, create files that don't exist. Defaults to false.

    • refreshboolean
      

      Indicate whether the index and git attributes should be refreshed from disk before any operations. Defaults to true,

    • removeIgnoredboolean
      

      Remove ignored files from the working dir. Defaults to false.

    • removeUntrackedboolean
      

      Remove untracked files from the working dir. Defaults to false.

    • safeboolean
      

      Indicate that the checkout should be performed safely, allowing new files to be created but not overwriting existing files or changes. This is the default.

    • skipUnmergedboolean
      

      Skip files with unmerged index entries. Defaults to false.

    • targetDirstring
      

      Set the directory to check out to

    • theirLabelstring
      

      The name of the common their side of conflicts

    • updateIndexboolean
      

      Prevents checkout from writing the updated files' information to the index. Defaults to true.

    • updateOnlyboolean
      

      Only update the contents of files that already exist. If set, files will not be created or deleted. Defaults to false.

    • useOursboolean
      

      Indicate whether the checkout should proceed on conflicts by using the stage 2 version of the file ("ours"). Defaults to false.

    • useTheirsboolean
      

      Indicate whether the checkout should proceed on conflicts by using the stage 3 version of the file ("theirs"). Defaults to false.

  • mainlinenumber
    

    Parent number for merge commits (1-based). When cherrypicking a merge commit, the mainline parent is the one you want to cherrypick from. The mainline is the branch from which the merge was made.

  • mergeOptionsMergeOptions
    

    Options for merge resolution when cherrypicking a merge commit.

    • diff3Styleboolean
      

      Create diff3-style file

    • failOnConflictboolean
      

      If a conflict occurs, exit immediately instead of attempting to continue resolving conflicts

    • filFavorFileFavor
      

      Specify a side to favor for resolving conflicts

    • findRenamesboolean
      

      Detect file renames

    • ignoreWhitespaceboolean
      

      Ignore all whitespace

    • ignoreWhitespaceChangeboolean
      

      Ignore changes in amount of whitespace

    • ignoreWhitespaceEolboolean
      

      Ignore whitespace at end of line

    • minimalboolean
      

      Take extra time to find minimal diff

    • noRecursiveboolean
      

      If the commits being merged have multiple merge bases, do not build a recursive merge base (by merging the multiple merge bases), instead simply use the first base.

    • patienceboolean
      

      Use the "patience diff" algorithm

    • recursionLimitnumber
      

      Maximum number of times to merge common ancestors to build a virtual merge base when faced with criss-cross merges. When this limit is reached, the next ancestor will simply be used instead of attempting to merge it. The default is unlimited.

    • renameThresholdnumber
      

      Similarity to consider a file renamed (default 50)

    • simplifyAlnumboolean
      

      Condense non-alphanumeric regions for simplified diff file

    • skipReucboolean
      

      Do not write the REUC extension on the generated index

    • standardStyleboolean
      

      Create standard conflicted merge files

    • targetLimitnumber
      

      Maximum similarity sources to examine for renames (default 200). If the number of rename candidates (add / delete pairs) is greater than this value, inexact rename detection is aborted. This setting overrides the merge.renameLimit configuration value.

Errors

• Error
  

  If the commit is a merge commit and no mainline is specified.

• Error
  

  If there are conflicts during the cherrypick operation.

Examples

import { openRepository } from 'es-git';

const repo = await openRepository('./path/to/repo');
const cherrypickCommit = repo.getCommit('cherrypick-commit');

// Cherrypick the commit onto HEAD and working tree
repo.cherrypick(cherrypickCommit);
repo.cleanupState();

// Cherrypick the commit against our commit selecting the first parent as mainline (This is necessary because, for merge commits, there is ambiguity about which side of the merge should be treated as the baseline.)
repo.cherrypick(cherrypickCommit, { mainline: 1 });
repo.cleanupState();

// Prevent working tree changes (dry run) but compute conflicts
repo.cherrypick(cherrypickCommit, { checkoutOptions: { dryRun: true } });
repo.cleanupState();

// Cherrypick the commit against our commit selecting the first parent as mainline and prevent working tree changes (dry run) but compute conflicts
repo.cherrypick(cherrypickCommit, { mainline: 1, checkoutOptions: { dryRun: true } });
repo.cleanupState();