es-git 0.4.0-next.144 → 0.4.0-next.146

package/index.d.ts

@@ -1711,6 +1711,45 @@ export declare function discoverRepository(path: string, signal?: AbortSignal |
  * ```
  */
 export declare function cloneRepository(url: string, path: string, options?: RepositoryCloneOptions | undefined | null, signal?: AbortSignal | undefined | null): Promise<Repository>
+/**
+ * Options for revert behavior.
+ *
+ * Controls how a revert is performed when applying the inverse of a commit.
+ *
+ * @example
+ * ```ts
+ * import { openRepository } from 'es-git';
+ *
+ * const repo = await openRepository('./path/to/repo');
+ * const head = repo.head().target()!;
+ * const commit = repo.getCommit(head);
+ *
+ * // Simple revert
+ * repo.revert(commit);
+ * repo.cleanupState();
+ *
+ * // Revert a merge commit selecting the first parent as mainline
+ * repo.revert(commit, { mainline: 1 });
+ * repo.cleanupState();
+ *
+ * // Prevent working tree changes (dry run) but compute conflicts
+ * repo.revert(commit, { checkoutOptions: { dryRun: true } });
+ * repo.cleanupState();
+ * ```
+ */
+export interface RevertOptions {
+  /**
+   * Parent number for merge commits (1-based).
+   *
+   * When reverting a merge commit, the mainline parent is the one you want to
+   * revert to. The mainline is the branch into which the merge was made.
+   */
+  mainline?: number
+  /** Options for merge conflict resolution. */
+  mergeOptions?: MergeOptions
+  /** Options for checkout behavior when updating working directory. */
+  checkoutOptions?: CheckoutOptions
+}
 /**
  * Flags for the revparse.
  * - `Single` : The spec targeted a single object.
@@ -5433,6 +5472,16 @@ export declare class Repository {
    * ```
    *
    * @returns The current state of this repository.
+   *
+   * @example
+   * ```ts
+   * import { openRepository } from 'es-git';
+   *
+   * const repo = await openRepository('./repo');
+   * console.log(repo.state()); // e.g., 'Clean'
+   * // After a revert/merge/cherry-pick, state can be 'Revert'/'Merge' etc.
+   * // Use repo.cleanupState() to return to 'Clean' when done handling.
+   * ```
    */
   state(): RepositoryState
   /**
@@ -5597,8 +5646,97 @@ export declare class Repository {
    *   cleanupState(): void;
    * }
    * ```
+   *
+   * @example
+   * ```ts
+   * import { openRepository } from 'es-git';
+   *
+   * const repo = await openRepository('./repo');
+   * // After revert or merge operations:
+   * if (repo.state() !== 'Clean') {
+   *   repo.cleanupState();
+   * }
+   * ```
    */
   cleanupState(): void
+  /**
+   * Reverts the given commit, applying the inverse of its changes to the
+   * HEAD commit and the working directory.
+   *
+   * @category Repository/Methods
+   * @signature
+   * ```ts
+   * class Repository {
+   *   revert(
+   *     commit: Commit,
+   *     options?: RevertOptions | undefined | null,
+   *   ): void;
+   * }
+   * ```
+   *
+   * @param {Commit} commit - The commit to revert.
+   * @param {RevertOptions} [options] - Options for the revert operation.
+   * @throws {Error} If the commit is a merge commit and no mainline is specified.
+   * @throws {Error} If there are conflicts during the revert operation.
+   *
+   * @example
+   * ```ts
+   * import { openRepository } from 'es-git';
+   *
+   * const repo = await openRepository('./path/to/repo');
+   * const last = repo.head().target()!;
+   * const commit = repo.getCommit(last);
+   *
+   * // Revert and update working tree
+   * repo.revert(commit);
+   * repo.cleanupState();
+   *
+   * // Revert a merge commit: specify the mainline parent
+   * // repo.revert(mergeCommit, { mainline: 1 });
+   * // repo.cleanupState();
+   * ```
+   */
+  revert(commit: Commit, options?: RevertOptions | undefined | null): void
+  /**
+   * Reverts the given commit against the given "our" commit, producing an
+   * index that reflects the result of the revert.
+   *
+   * The returned index must be written to disk for the changes to take effect.
+   *
+   * @category Repository/Methods
+   * @signature
+   * ```ts
+   * class Repository {
+   *   revertCommit(
+   *     revertCommit: Commit,
+   *     ourCommit: Commit,
+   *     mainline: number,
+   *     mergeOptions?: MergeOptions | undefined | null,
+   *   ): Index;
+   * }
+   * ```
+   *
+   * @param {Commit} revertCommit - The commit to revert.
+   * @param {Commit} ourCommit - The commit to revert against (usually HEAD).
+   * @param {number} mainline - The parent of the revert commit, if it is a merge (1-based).
+   * @param {MergeOptions} [mergeOptions] - Options for merge conflict resolution.
+   * @returns The index result.
+   *
+   * @example
+   * ```ts
+   * import { openRepository } from 'es-git';
+   *
+   * const repo = await openRepository('./path/to/repo');
+   * const head = repo.head().target()!;
+   * const our = repo.getCommit(head);
+   * const target = repo.getCommit(head);
+   *
+   * // Compute a revert index and apply to working tree
+   * const idx = repo.revertCommit(target, our, 0);
+   * repo.checkoutIndex(idx);
+   * ```
+   */
+  revertCommit(revertCommit: Commit, ourCommit: Commit, mainline: number, mergeOptions?: MergeOptions | undefined | null): Index
   /**
    * Execute a rev-parse operation against the `spec` listed.
    *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "es-git",
-  "version": "0.4.0-next.144+3fe2eaa",
+  "version": "0.4.0-next.146+81f034c",
   "main": "index.js",
   "types": "index.d.ts",
   "files": [
@@ -57,15 +57,15 @@
     "vitest": "^3.0.5"
   },
   "optionalDependencies": {
-    "es-git-darwin-x64": "0.4.0-next.144+3fe2eaa",
-    "es-git-darwin-arm64": "0.4.0-next.144+3fe2eaa",
-    "es-git-win32-x64-msvc": "0.4.0-next.144+3fe2eaa",
-    "es-git-win32-arm64-msvc": "0.4.0-next.144+3fe2eaa",
-    "es-git-linux-x64-gnu": "0.4.0-next.144+3fe2eaa",
-    "es-git-linux-x64-musl": "0.4.0-next.144+3fe2eaa",
-    "es-git-android-arm64": "0.4.0-next.144+3fe2eaa",
-    "es-git-linux-arm64-gnu": "0.4.0-next.144+3fe2eaa",
-    "es-git-linux-arm64-musl": "0.4.0-next.144+3fe2eaa",
-    "es-git-android-arm-eabi": "0.4.0-next.144+3fe2eaa"
+    "es-git-darwin-x64": "0.4.0-next.146+81f034c",
+    "es-git-darwin-arm64": "0.4.0-next.146+81f034c",
+    "es-git-win32-x64-msvc": "0.4.0-next.146+81f034c",
+    "es-git-win32-arm64-msvc": "0.4.0-next.146+81f034c",
+    "es-git-linux-x64-gnu": "0.4.0-next.146+81f034c",
+    "es-git-linux-x64-musl": "0.4.0-next.146+81f034c",
+    "es-git-android-arm64": "0.4.0-next.146+81f034c",
+    "es-git-linux-arm64-gnu": "0.4.0-next.146+81f034c",
+    "es-git-linux-arm64-musl": "0.4.0-next.146+81f034c",
+    "es-git-android-arm-eabi": "0.4.0-next.146+81f034c"
   }
 }