es-git 0.5.0-next.164 → 0.5.0-next.166

package/index.d.ts

@@ -1464,6 +1464,23 @@ export declare class DiffStats {
  * [1]: https://git-scm.com/book/en/Git-Internals-Git-Objects
  */
 export declare class GitObject {
+  /**
+   * Describes a commit
+   *
+   * Performs a describe operation on this commitish object.
+   *
+   * @category GitObject/Methods
+   * @signature
+   * ```ts
+   * class Object {
+   *   describe(options?: DescribeOptions | null | undefined): Describe;
+   * }
+   * ```
+   *
+   * @param {DescribeOptions} [options] - Options for describe operation.
+   * @returns Instance of describe.
+   */
+  describe(options?: DescribeOptions | undefined | null): Describe
   /**
    * Get the id (SHA1) of a repository object.
    *
@@ -1552,23 +1569,6 @@ export declare class GitObject {
    * @returns Returns `null` if the object is not actually a commit.
    */
   asCommit(): Commit | null
-  /**
-   * Describes a commit
-   *
-   * Performs a describe operation on this commitish object.
-   *
-   * @category GitObject/Methods
-   * @signature
-   * ```ts
-   * class Object {
-   *   describe(options?: DescribeOptions | null | undefined): Describe;
-   * }
-   * ```
-   *
-   * @param {DescribeOptions} [options] - Options for describe operation.
-   * @returns Instance of describe.
-   */
-  describe(options?: DescribeOptions | undefined | null): Describe
 }
 
 /**
@@ -2800,6 +2800,98 @@ export declare class Repository {
    * @param {CheckoutOptions} [options] - Options for checkout.
    */
   checkoutTree(treeish: GitObject, options?: CheckoutOptions | undefined | null): void
+  /**
+   * 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.
+   *
+   * @category Repository/Methods
+   * @signature
+   * ```ts
+   * class Repository {
+   *   cherrypick(
+   *     commit: Commit,
+   *     options?: CherrypickOptions | undefined | null,
+   *   ): void;
+   * }
+   * ```
+   *
+   * @param {Commit} commit - The commit to cherrypick.
+   * @param {CherrypickOptions} [options] - Options for the cherrypick operation.
+   * @throws {Error} If the commit is a merge commit and no mainline is specified.
+   * @throws {Error} If there are conflicts during the cherrypick operation.
+   *
+   * @example
+   * ```ts
+   * 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();
+   * ```
+   */
+  cherrypick(commit: Commit, options?: CherrypickOptions | undefined | null): void
+  /**
+   * Applies a cherrypick of `cherrypick_commit` against `our_commit` and returns the resulting Index,
+   * without modifying the working directory or repository state.
+   * This method does not write any changes to disk or update HEAD.
+   * it is useful for computing what the cherrypick result would look like without actually applying it.
+   *
+   * @category Repository/Methods
+   * @signature
+   * ```ts
+   * class Repository {
+   *   cherrypickCommit(
+   *     cherrypickCommit: Commit,
+   *     ourCommit: Commit,
+   *     mainline: number,
+   *     mergeOptions?: MergeOptions | undefined | null,
+   *   ): Index;
+   * }
+   * ```
+   *
+   * @param {Commit} cherrypickCommit - The commit to cherrypick.
+   * @param {Commit} ourCommit - The commit to cherrypick against (usually HEAD).
+   * @param {number} mainline - The parent of the cherrypick commit, if it is a merge (1-based).
+   * @param {MergeOptions} [mergeOptions] - Options for merge conflict resolution.
+   * @returns The index result.
+   * @throws {Error} If the cherrypick commit is a merge and mainline is 0.
+   * @throws {Error} If there are conflicts and failOnConflict is true (default).
+   *
+   * @example
+   * ```ts
+   * // This is an example for cherrypick_commit
+   * import { openRepository } from "es-git";
+   *
+   * const repo = await openRepository("./path/to/repo");
+   * const cherry = repo.getCommit("cherrypick-commit");
+   * const target = repo.getCommit("onto-commit");
+   *
+   * // Returns the Index resulting from the cherrypick in memory,
+   * // without affecting HEAD or the working tree.
+   * // The mainline parameter indicates which parent to use as the baseline,
+   * // For merge commits, mainline specifies which parent to use as baseline (1 or 2).
+   * // For normal (non-merge) commits, use mainline 0.
+   * const idx = repo.cherrypickCommit(cherry, target, 0);
+   *
+   * // You can check for conflicts with idx.hasConflicts()
+   * ```
+   */
+  cherrypickCommit(cherrypickCommit: Commit, ourCommit: Commit, mainline: number, mergeOptions?: MergeOptions | undefined | null): Index
   /**
    * Lookup a reference to one of the commits in a repository.
    *
@@ -2872,6 +2964,25 @@ export declare class Repository {
    * (if they are available).
    */
   config(): Config
+  /**
+   * Describes a commit
+   *
+   * Performs a describe operation on the current commit and the worktree.
+   * After performing a describe on `HEAD`, a status is run and description is
+   * considered to be dirty if there are.
+   *
+   * @category Repository/Methods
+   * @signature
+   * ```ts
+   * class Repository {
+   *   describe(options?: DescribeOptions | null | undefined): Describe;
+   * }
+   * ```
+   *
+   * @param {DescribeOptions} [options] - Options for describe operation.
+   * @returns Instance of describe.
+   */
+  describe(options?: DescribeOptions | undefined | null): Describe
   /**
    * Create a diff with the difference between two tree objects.
    *
@@ -4584,25 +4695,6 @@ export declare class Repository {
    * @returns If it does not exist, returns `null`.
    */
   findTree(oid: string): Tree | null
-  /**
-   * Describes a commit
-   *
-   * Performs a describe operation on the current commit and the worktree.
-   * After performing a describe on `HEAD`, a status is run and description is
-   * considered to be dirty if there are.
-   *
-   * @category Repository/Methods
-   * @signature
-   * ```ts
-   * class Repository {
-   *   describe(options?: DescribeOptions | null | undefined): Describe;
-   * }
-   * ```
-   *
-   * @param {DescribeOptions} [options] - Options for describe operation.
-   * @returns Instance of describe.
-   */
-  describe(options?: DescribeOptions | undefined | null): Describe
 }
 
 /**
@@ -5828,6 +5920,21 @@ export interface CheckoutOptions {
   theirLabel?: string
 }
 
+/** Options for cherrypick behavior. */
+export interface CherrypickOptions {
+  /**
+   * 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.
+   */
+  mainline?: number
+  /** Options for merge resolution when cherrypicking a merge commit. */
+  mergeOptions?: MergeOptions
+  /** Options for checkout behavior when updating working directory. */
+  checkoutOptions?: CheckoutOptions
+}
+
 /**
  * Clone a remote repository.
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "es-git",
-  "version": "0.5.0-next.164+3f0c3d0",
+  "version": "0.5.0-next.166+44a2a2d",
   "main": "index.js",
   "types": "index.d.ts",
   "files": [
@@ -54,15 +54,15 @@
     "vitest": "^3.0.5"
   },
   "optionalDependencies": {
-    "es-git-darwin-x64": "0.5.0-next.164+3f0c3d0",
-    "es-git-darwin-arm64": "0.5.0-next.164+3f0c3d0",
-    "es-git-win32-x64-msvc": "0.5.0-next.164+3f0c3d0",
-    "es-git-win32-arm64-msvc": "0.5.0-next.164+3f0c3d0",
-    "es-git-linux-x64-gnu": "0.5.0-next.164+3f0c3d0",
-    "es-git-linux-x64-musl": "0.5.0-next.164+3f0c3d0",
-    "es-git-android-arm64": "0.5.0-next.164+3f0c3d0",
-    "es-git-linux-arm64-gnu": "0.5.0-next.164+3f0c3d0",
-    "es-git-linux-arm64-musl": "0.5.0-next.164+3f0c3d0",
-    "es-git-android-arm-eabi": "0.5.0-next.164+3f0c3d0"
+    "es-git-darwin-x64": "0.5.0-next.166+44a2a2d",
+    "es-git-darwin-arm64": "0.5.0-next.166+44a2a2d",
+    "es-git-win32-x64-msvc": "0.5.0-next.166+44a2a2d",
+    "es-git-win32-arm64-msvc": "0.5.0-next.166+44a2a2d",
+    "es-git-linux-x64-gnu": "0.5.0-next.166+44a2a2d",
+    "es-git-linux-x64-musl": "0.5.0-next.166+44a2a2d",
+    "es-git-android-arm64": "0.5.0-next.166+44a2a2d",
+    "es-git-linux-arm64-gnu": "0.5.0-next.166+44a2a2d",
+    "es-git-linux-arm64-musl": "0.5.0-next.166+44a2a2d",
+    "es-git-android-arm-eabi": "0.5.0-next.166+44a2a2d"
   }
 }