rebase

Initializes a rebase operation to rebase the changes in branch relative to upstream onto another branch. To begin the rebase process, call iterator.

Signature

class Repository {
  rebase(
    branch?: AnnotatedCommit | undefined | null,
    upstream?: AnnotatedCommit | undefined | null,
    onto?: AnnotatedCommit | undefined | null,
    options?: RebaseOptions | undefined | null,
  ): Rebase;
}

Parameters

• branchnull | AnnotatedCommit
  

  Annotated commit representing the branch to rebase. Typically, the branch's head commit. If omitted, the currently checked-out branch is used.

• upstreamnull | AnnotatedCommit
  

  Annotated commit that defines the "original base" of the commits to be rebased. If omitted, the repository will typically try to use the branch's configured upstream.

• ontonull | AnnotatedCommit
  

  Specified the "new base" onto which the selected commits will be reapplied.

• optionsnull | RebaseOptions
  

  Fine-grained control of the rebase behavior, such as checkout options, merge options, and in-memory rebase.

  • checkoutOptionsCheckoutOptions
    

    Options to control how files are written during Repository::rebase, next() and abort(). Note that a minimum strategy of GIT_CHECKOUT_SAFE is defaulted in init and next, and a minimum strategy of GIT_CHECKOUT_FORCE is defaulted in abort to match git semantics.

    • 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.

  • inmemoryboolean
    

    This will begin an in-memory rebase, which will allow callers to step through the rebase operations and commit the rebased changes, but will not rewind HEAD or update the repository to be in a rebasing state. This will not interfere with the working directory (if there is one).

  • mergeOptionsMergeOptions
    

    Options to control how trees are merged during next().

    • 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.

  • quietboolean
    

    This will instruct other clients working on this rebase that you want a quiet rebase experience, which they may choose to provide in an application-specific manner. This has no effect upon libgit2 directly, but is provided for interoperability between Git tools.

  • rewriteNotesRefstring
    

    Used by finish(), this is the name of the notes reference used to rewrite notes for rebased commits when finishing the rebase; if NULL, the contents of the configuration option notes.rewriteRef is examined, unless the configuration option notes.rewrite.rebase is set to false. If notes.rewriteRef is also NULL, notes will not be rewritten.

Returns

• Rebase
  

  The initialized rebase handle to iterate and apply steps.

Examples

import { openRepository } from 'es-git';

const repo = await openRepository('.');
const branchRef = repo.getReference('refs/heads/other');
const upstreamRef = repo.getReference('refs/heads/main');
const branch = repo.getAnnotatedCommitFromReference(branchRef);
const upstream = repo.getAnnotatedCommitFromReference(upstreamRef);

const sig = { name: 'Seokju Na', email: 'seokju.me@toss.im' };

const rebase = repo.rebase(branch, upstream);
for (const op of rebase) {
  rebase.commit({ committer: sig });
}
rebase.finish(sig);