es-git 0.4.0 → 0.5.0-next.153

package/index.d.ts

@@ -1029,6 +1029,93 @@ export declare function hashObjectOid(objType: ObjectType, bytes: Buffer): strin
  * @returns Hashed string.
  */
 export declare function hashFileOid(objType: ObjectType, path: string): string
+export interface RebaseCommitOptions {
+  /**
+   * Signature for author.
+   * To keep the author from the original commit leave this as empty.
+   */
+  author?: SignaturePayload
+  /** Signature for commiter. */
+  committer: SignaturePayload
+  /** To keep the message from the original commit leave this as empty. */
+  message?: string
+}
+/**
+ * A rebase operation
+ *
+ * Describes a single instruction/operation to be performed during the
+ * rebase.
+ */
+export interface RebaseOperation {
+  /** The type of rebase operation */
+  type?: RebaseOperationType
+  /**
+   * The commit ID being cherry-picked. This will be populated for all
+   * operations except those of type `GIT_REBASE_OPERATION_EXEC`.
+   */
+  id: string
+  /**
+   *The executable the user has requested be run.  This will only
+   * be populated for operations of type `Exec`.
+   */
+  exec?: string
+}
+/**
+ * A rebase operation.
+ * Describes a single instruction/operation to be performed during the
+ * rebase.
+ *
+ * - `Pick` : The given commit is to be cherry-picked. The client should commit the
+ * changes and continue if there are no conflicts.
+ * - `Reword` : The given commit is to be cherry-picked, but the client should prompt
+ * the user to provide an updated commit message.
+ * - `Edit` : The given commit is to be cherry-picked, but the client should stop to
+ * allow the user to edit the changes before committing them.
+ * - `Squash` : The given commit is to be squashed into the previous commit. The commit
+ * message will be merged with the previous message.
+ * - `Fixup` : The given commit is to be squashed into the previous commit. The commit
+ * message from this commit will be discarded.
+ * - `Exec` : No commit will be cherry-picked. The client should run the given command
+ * and (if successful) continue.
+ */
+export type RebaseOperationType = 'Pick' | 'Reword' | 'Edit' | 'Squash' | 'Fixup' | 'Exec';
+export interface RebaseOptions {
+  /**
+   * 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.
+   */
+  quiet?: boolean
+  /**
+   * 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).
+   */
+  inmemory?: boolean
+  /**
+   * 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.
+   */
+  rewriteNotesRef?: string
+  /** Options to control how trees are merged during `next()`. */
+  mergeOptions?: MergeOptions
+  /**
+   * 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.
+   */
+  checkoutOptions?: CheckoutOptions
+}
 /**
  * - `Direct` : A reference which points at an object id.
  * - `Symbolic` : A reference which points at another reference.
@@ -1624,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.
@@ -1730,6 +1856,84 @@ export interface SignaturePayload {
   email: string
   timeOptions?: SignatureTimeOptions
 }
+/**
+ * Options for saving a stash.
+ *
+ * All fields are optional. If not provided, sensible defaults will be used.
+ *
+ * @example
+ * ```ts
+ * import { openRepository } from 'es-git';
+ *
+ * const repo = await openRepository('./path/to/repo');
+ *
+ * // Basic usage
+ * repo.stashSave({
+ *   stasher: { name: 'Seokju Na', email: 'seokju.me@toss.im' }
+ * });
+ *
+ * // With options
+ * repo.stashSave({
+ *   stasher: { name: 'Seokju Na', email: 'seokju.me@toss.im' },
+ *   message: 'WIP: feature implementation',
+ *   includeUntracked: true
+ * });
+ * ```
+ */
+export interface StashSaveOptions {
+  /**
+   * The identity of the person performing the stashing.
+   * If not provided, uses the repository's default signature.
+   */
+  stasher?: SignaturePayload
+  /**
+   * Description along with the stashed state.
+   * If not provided, a default message will be generated.
+   */
+  message?: string
+  /**
+   * Whether to stash untracked files.
+   * Default: false
+   */
+  includeUntracked?: boolean
+  /**
+   * Whether to stash ignored files.
+   * Default: false
+   */
+  includeIgnored?: boolean
+  /**
+   * Whether to retain the index after stashing.
+   * If true, staged changes remain in the index after stashing.
+   * Default: false
+   */
+  keepIndex?: boolean
+}
+/**
+ * Options for applying a stash.
+ *
+ * Controls how a stash is applied to the working directory.
+ *
+ * @example
+ * ```ts
+ * import { openRepository } from 'es-git';
+ *
+ * const repo = await openRepository('./path/to/repo');
+ *
+ * // Default apply
+ * repo.stashApply(0);
+ *
+ * // With options
+ * repo.stashApply(0, { reinstantiateIndex: true });
+ * ```
+ */
+export interface StashApplyOptions {
+  /**
+   * Whether to reinstall the index from the stash.
+   * If true, the index state recorded in the stash is also restored.
+   * Default: false
+   */
+  reinstantiateIndex?: boolean
+}
 export interface Status {
   current: boolean
   indexNew: boolean
@@ -1742,6 +1946,7 @@ export interface Status {
   wtDeleted: boolean
   wtTypechange: boolean
   wtRenamed: boolean
+  wtUnreadable: boolean
   ignored: boolean
   conflicted: boolean
 }
@@ -3643,6 +3848,133 @@ export declare class GitObject {
    */
   asCommit(): Commit | null
 }
+/**
+ * Representation of a rebase
+ * Begin the rebase by iterating the returned `Rebase`
+ * (e.g., `for (const op of rebase) { ... }` or calling `next()`).
+ */
+export declare class Rebase {
+  /**
+   * Gets the count of rebase operations that are to be applied.
+   *
+   * @category Rebase/Methods
+   * @signature
+   * ```ts
+   * class Rebase {
+   *   len(): number;
+   * }
+   * ```
+   *
+   * @returns The count of rebase operations.
+   */
+  len(): bigint
+  /**
+   * Gets the original `HEAD` ref name for merge rebases.
+   *
+   * @category Rebase/Methods
+   * @signature
+   * ```ts
+   * class Rebase {
+   *   originHeadName(): string | null;
+   * }
+   * ```
+   *
+   * @returns The original `HEAD` ref name for merge rebases.
+   */
+  originHeadName(): string | null
+  /**
+   * Gets the original `HEAD` id for merge rebases.
+   *
+   * @category Rebase/Methods
+   * @signature
+   * ```ts
+   * class Rebase {
+   *   originHeadId(): string | null;
+   * }
+   * ```
+   *
+   * @returns The original `HEAD` id for merge rebases.
+   */
+  originHeadId(): string | null
+  /**
+   * Gets the index produced by the last operation, which is the result of
+   * `next()` and which will be committed by the next invocation of
+   * `commit()`. This is useful for resolving conflicts in an in-memory
+   * rebase before committing them.
+   *
+   * This is only applicable for in-memory rebases; for rebases within a
+   * working directory, the changes were applied to the repository's index.
+   *
+   * @category Rebase/Methods
+   * @signature
+   * ```ts
+   * class Rebase {
+   *   inmemoryIndex(): Index;
+   * }
+   * ```
+   *
+   * @returns The index produced by the last operation.
+   */
+  inmemoryIndex(): Index
+  /**
+   * Commits the current patch.  You must have resolved any conflicts that
+   * were introduced during the patch application from the rebase next
+   * invocation.
+   *
+   * @category Rebase/Methods
+   * @signature
+   * ```ts
+   * class Rebase {
+   *   commit(options: RebaseCommitOptions): string;
+   * }
+   * ```
+   *
+   * @param {RebaseCommitOptions} options - Options for committing the patch.
+   * @returns The commit ID of the commit that was created.
+   *
+   * @example
+   * ```ts
+   * import { openRepository } from 'es-git';
+   *
+   * const repo = await openRepository('.');
+   * const rebase = repo.rebase(...);
+   * const sig = { name: 'Seokju Na', email: 'seokju.me@toss.im' };
+   * for (const op of rebase) {
+   *   rebase.commit({ committer: sig });
+   * }
+   * ```
+   */
+  commit(options: RebaseCommitOptions): string
+  /**
+   * Aborts a rebase that is currently in progress, resetting the repository
+   * and working directory to their state before rebase began.
+   *
+   * @category Rebase/Methods
+   * @signature
+   * ```ts
+   * class Rebase {
+   *   abort(): void;
+   * }
+   * ```
+   */
+  abort(): void
+  /**
+   * Finishes a rebase that is currently in progress once all patches have
+   * been applied.
+   *
+   * @category Rebase/Methods
+   * @signature
+   * ```ts
+   * class Rebase {
+   *   finish(signature?: SignaturePayload | undefined | null): void;
+   * }
+   * ```
+   *
+   * @params {SignaturePayload | undefined | null} [signature] - The identity that is finishing the rebase
+   */
+  finish(signature?: SignaturePayload | undefined | null): void
+  [Symbol.iterator](): Iterator<RebaseOperation, void, void>
+}
 /**
  * A class to represent a git [reference][1].
  *
@@ -4771,7 +5103,7 @@ export declare class Repository {
    * }
    * ```
    *
-   * @param {Commit} outCommit - The commit that reflects the destination tree.
+   * @param {Commit} ourCommit - The commit that reflects the destination tree.
    * @param {Commit} theirCommit - The commit to merge in to `ourCommit`.
    * @param {MergeOptions} [options] - Merge options.
    * @returns The index result.
@@ -4797,7 +5129,7 @@ export declare class Repository {
    * ```
    *
    * @param {Tree} ancestorTree - The common ancestor between.
-   * @param {Tree} outTree - The tree that reflects the destination tree.
+   * @param {Tree} ourTree - The tree that reflects the destination tree.
    * @param {Tree} theirTree - The tree to merge in to `ourTree`.
    * @param {MergeOptions} [options] - Merge options.
    * @returns The index result.
@@ -4867,6 +5199,74 @@ export declare class Repository {
    * @throws Throws error if the object does not exist.
    */
   getObject(oid: string): GitObject
+  /**
+   * Initializes a rebase operation to rebase the changes in `branch`
+   * relative to `upstream` onto another branch. To begin the rebase process,
+   * call iterator.
+   *
+   * @category Repository/Methods
+   * @signature
+   * ```ts
+   * class Repository {
+   *   rebase(
+   *     branch?: AnnotatedCommit | undefined | null,
+   *     upstream?: AnnotatedCommit | undefined | null,
+   *     onto?: AnnotatedCommit | undefined | null,
+   *     options?: RebaseOptions | undefined | null,
+   *   ): Rebase;
+   * }
+   * ```
+   *
+   * @param {AnnotatedCommit | undefined | null} [branch] - Annotated commit representing the
+   * branch to rebase. Typically, the branch's head commit. If omitted, the currently checked-out
+   * branch is used.
+   * @param {AnnotatedCommit | undefined | null} [upstream] - 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.
+   * @param {AnnotatedCommit | undefined | null} [onto] - Specified the "new base" onto which the
+   * selected commits will be reapplied.
+   * @param {RebaseOptions | undefined | null} [options] - Fine-grained control of the rebase
+   * behavior, such as checkout options, merge options, and in-memory rebase.
+   * @returns The initialized rebase handle to iterate and apply steps.
+   *
+   * @example
+   * ```ts
+   * 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);
+   * ```
+   */
+  rebase(branch?: AnnotatedCommit | undefined | null, upstream?: AnnotatedCommit | undefined | null, onto?: AnnotatedCommit | undefined | null, options?: RebaseOptions | undefined | null): Rebase
+  /**
+   * Opens an existing rebase that was previously started by either an
+   * invocation of `rebase()` or by another client.
+   *
+   * @category Repository/Methods
+   * @signature
+   * ```ts
+   * class Repository {
+   *   openRebase(options?: RebaseOptions | undefined | null): Rebase;
+   * }
+   * ```
+   *
+   * @param {RebaseOptions | undefined | null} [options] - Fine-grained control of the rebase
+   * behavior, such as checkout options, merge options, and in-memory rebase.
+   * @returns The initialized rebase handle to iterate and apply steps.
+   * @throws Throws if the existing rebase was not found.
+   */
+  openRebase(options?: RebaseOptions | undefined | null): Rebase
   /**
    * Lookup a reference to one of the objects in a repository.
    *
@@ -5072,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
   /**
@@ -5163,7 +5573,7 @@ export declare class Repository {
    * }
    * ```
    *
-   * @param {Commit} commitish - A Commit which the HEAD should point to.
+   * @param {Commit} commit - A Commit which the HEAD should point to.
    */
   setHeadDetached(commit: Commit): void
   /**
@@ -5236,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.
    *
@@ -5286,6 +5785,175 @@ export declare class Repository {
    * @returns Revwalk to traverse the commit graph in this repository.
    */
   revwalk(): Revwalk
+  /**
+   * Save the local modifications to a new stash.
+   *
+   * This method saves your current working directory and index state to a new stash entry,
+   * allowing you to temporarily store changes and work on something else. The working directory
+   * is reverted to match the HEAD commit after stashing.
+   *
+   * @category Repository/Methods
+   * @signature
+   * ```ts
+   * class Repository {
+   *   stashSave(options?: StashSaveOptions): string;
+   * }
+   * ```
+   *
+   * @param {StashSaveOptions} [options] - Options for saving the stash.
+   * @returns {string} The object ID (40-character SHA1) of the commit containing the stashed state.
+   * @throws {Error} If there are no local changes to stash or if the stash operation fails.
+   *
+   * @example
+   * ```ts
+   * import { openRepository } from 'es-git';
+   *
+   * const repo = await openRepository('./path/to/repo');
+   *
+   * // Simple stash
+   * const stashId = repo.stashSave({
+   *   stasher: { name: 'Seokju Na', email: 'seokju.me@toss.im' },
+   *   message: 'WIP: implementing new feature'
+   * });
+   *
+   * // Stash including untracked files
+   * repo.stashSave({
+   *   stasher: { name: 'Seokju Na', email: 'seokju.me@toss.im' },
+   *   includeUntracked: true
+   * });
+   * ```
+   */
+  stashSave(options?: StashSaveOptions | undefined | null): string
+  /**
+   * Apply a single stashed state from the stash list.
+   *
+   * This method applies the changes from a stash entry to your working directory.
+   * Unlike `stashPop`, this does not remove the stash from the list after applying.
+   * Conflicts may occur if the stashed changes conflict with the current working directory.
+   *
+   * @category Repository/Methods
+   * @signature
+   * ```ts
+   * class Repository {
+   *   stashApply(index: number, options?: StashApplyOptions): void;
+   * }
+   * ```
+   *
+   * @param {number} index - The index of the stash to apply (0 is the most recent).
+   * @param {StashApplyOptions} [options] - Options for applying the stash.
+   * @throws {Error} If the stash index is invalid or if there are conflicts during application.
+   *
+   * @example
+   * ```ts
+   * import { openRepository } from 'es-git';
+   *
+   * const repo = await openRepository('./path/to/repo');
+   *
+   * // Apply the most recent stash
+   * repo.stashApply(0);
+   *
+   * // Apply with options
+   * repo.stashApply(0, { reinstantiateIndex: true });
+   * ```
+   */
+  stashApply(index: number, options?: StashApplyOptions | undefined | null): void
+  /**
+   * Remove a single stashed state from the stash list.
+   *
+   * This permanently deletes a stash entry. The stash is removed from the list and
+   * cannot be recovered. All subsequent stashes will be reindexed (e.g., stash@{2}
+   * becomes stash@{1} after dropping stash@{1}).
+   *
+   * @category Repository/Methods
+   * @signature
+   * ```ts
+   * class Repository {
+   *   stashDrop(index: number): void;
+   * }
+   * ```
+   *
+   * @param {number} index - The index of the stash to drop (0 is the most recent).
+   * @throws {Error} If the stash index is invalid.
+   *
+   * @example
+   * ```ts
+   * import { openRepository } from 'es-git';
+   *
+   * const repo = await openRepository('./path/to/repo');
+   *
+   * // Drop the most recent stash
+   * repo.stashDrop(0);
+   *
+   * // Drop the third stash
+   * repo.stashDrop(2);
+   * ```
+   */
+  stashDrop(index: number): void
+  /**
+   * Apply a single stashed state from the stash list and remove it from the list if successful.
+   *
+   * This method combines `stashApply` and `stashDrop` into a single operation. It applies
+   * the stash to your working directory and, if successful, removes it from the stash list.
+   * If the application fails (e.g., due to conflicts), the stash remains in the list.
+   *
+   * @category Repository/Methods
+   * @signature
+   * ```ts
+   * class Repository {
+   *   stashPop(index: number, options?: StashApplyOptions): void;
+   * }
+   * ```
+   *
+   * @param {number} index - The index of the stash to pop (0 is the most recent).
+   * @param {StashApplyOptions} [options] - Options for applying the stash.
+   * @throws {Error} If the stash index is invalid or if there are conflicts during application.
+   *
+   * @example
+   * ```ts
+   * import { openRepository } from 'es-git';
+   *
+   * const repo = await openRepository('./path/to/repo');
+   *
+   * // Pop the most recent stash
+   * repo.stashPop(0);
+   *
+   * // Pop with options
+   * repo.stashPop(0, { reinstantiateIndex: true });
+   * ```
+   */
+  stashPop(index: number, options?: StashApplyOptions | undefined | null): void
+  /**
+   * Get the list of stash states in the repository.
+   *
+   * Returns a StashList object that provides access to all stashes in the repository.
+   * The list is ordered with the most recent stash at index 0.
+   *
+   * @category Repository/Methods
+   * @signature
+   * ```ts
+   * class Repository {
+   *   stashList(): StashList;
+   * }
+   * ```
+   *
+   * @returns {StashList} A container providing access to all stash entries in the repository.
+   *
+   * @example
+   * ```ts
+   * import { openRepository } from 'es-git';
+   *
+   * const repo = await openRepository('./path/to/repo');
+   * const stashList = repo.stashList();
+   *
+   * if (!stashList.isEmpty()) {
+   *   console.log(`Found ${stashList.len()} stashes`);
+   *   for (const stash of stashList.iter()) {
+   *     console.log(`${stash.index()}: ${stash.message()}`);
+   *   }
+   * }
+   * ```
+   */
+  stashList(): StashList
   /**
    * Test if the ignore rules apply to a given file.
    *
@@ -5833,6 +6501,220 @@ export declare class Revwalk {
    */
   hideRef(reference: string): this
 }
+/**
+ * A class to represent a git stash entry.
+ *
+ * A stash entry represents a snapshot of the working directory and index that has been saved
+ * temporarily. Each stash entry has an index (position in the stash stack), an ID (commit SHA),
+ * and an optional message describing the changes.
+ */
+export declare class StashEntry {
+  /**
+   * Get the index of this stash entry.
+   *
+   * The index represents the position of this stash in the stash stack, where 0 is the most recent stash.
+   *
+   * @category Stash/Methods
+   * @signature
+   * ```ts
+   * class StashEntry {
+   *   index(): number;
+   * }
+   * ```
+   *
+   * @returns {number} Index of this stash entry (0-based, with 0 being the most recent).
+   *
+   * @example
+   * ```ts
+   * import { openRepository } from 'es-git';
+   *
+   * const repo = await openRepository('./path/to/repo');
+   * const stashList = repo.stashList();
+   * const stash = stashList.get(0);
+   * console.log(stash?.index()); // 0
+   * ```
+   */
+  index(): number
+  /**
+   * Get the id (SHA1) of this stash entry.
+   *
+   * Each stash is stored as a commit object, and this returns the commit SHA.
+   *
+   * @category Stash/Methods
+   * @signature
+   * ```ts
+   * class StashEntry {
+   *   id(): string;
+   * }
+   * ```
+   *
+   * @returns {string} The 40-character hexadecimal SHA1 hash of the stash commit.
+   *
+   * @example
+   * ```ts
+   * import { openRepository } from 'es-git';
+   *
+   * const repo = await openRepository('./path/to/repo');
+   * const stashList = repo.stashList();
+   * const stash = stashList.get(0);
+   * console.log(stash?.id()); // e.g., "a1b2c3d4e5f6..."
+   * ```
+   */
+  id(): string
+  /**
+   * Get the message of this stash entry.
+   *
+   * Returns the message associated with the stash when it was created. If no custom message
+   * was provided, it returns the default message generated by Git.
+   *
+   * @category Stash/Methods
+   * @signature
+   * ```ts
+   * class StashEntry {
+   *   message(): string | null;
+   * }
+   * ```
+   *
+   * @returns {string | null} The stash message, or null if not available.
+   *
+   * @example
+   * ```ts
+   * import { openRepository } from 'es-git';
+   *
+   * const repo = await openRepository('./path/to/repo');
+   * const stashList = repo.stashList();
+   * const stash = stashList.get(0);
+   * console.log(stash?.message()); // e.g., "WIP on main: abc1234 fix: typo"
+   * ```
+   */
+  message(): string | null
+}
+/**
+ * A container for a list of stash entries about a repository.
+ *
+ * The stash list provides access to all stashes in the repository. Stashes are indexed
+ * from 0 (most recent) to n-1 (oldest). This class provides methods to access individual
+ * stashes, check the count, and iterate over all stashes.
+ *
+ * @example
+ * ```ts
+ * import { openRepository } from 'es-git';
+ *
+ * const repo = await openRepository('./path/to/repo');
+ * const stashList = repo.stashList();
+ * console.log(`Total stashes: ${stashList.len()}`);
+ *
+ * // Iterate over all stashes
+ * for (const stash of stashList.iter()) {
+ *   console.log(`${stash.index()}: ${stash.message()}`);
+ * }
+ * ```
+ */
+export declare class StashList {
+  /**
+   * Gets a stash entry from this list at the specified index.
+   *
+   * @category Stash/Methods
+   * @signature
+   * ```ts
+   * class StashList {
+   *   get(index: number): StashEntry | null;
+   * }
+   * ```
+   *
+   * @param {number} index - Index of the stash entry to get (0-based, where 0 is the most recent).
+   * @returns {StashEntry | null} A stash entry from this list at the specified index, or `null` if the index is out of bounds.
+   *
+   * @example
+   * ```ts
+   * import { openRepository } from 'es-git';
+   *
+   * const repo = await openRepository('./path/to/repo');
+   * const stashList = repo.stashList();
+   *
+   * // Get the most recent stash
+   * const stash = stashList.get(0);
+   * if (stash) {
+   *   console.log(stash.message());
+   * }
+   * ```
+   */
+  get(index: number): StashEntry | null
+  /**
+   * Gets the count of stash entries in this list.
+   *
+   * @category Stash/Methods
+   * @signature
+   * ```ts
+   * class StashList {
+   *   len(): number;
+   * }
+   * ```
+   *
+   * @returns If there are no stashes in the repository, this should return 0.
+   */
+  len(): number
+  /**
+   * Check if the stash list is empty.
+   *
+   * @category Stash/Methods
+   * @signature
+   * ```ts
+   * class StashList {
+   *   isEmpty(): boolean;
+   * }
+   * ```
+   *
+   * @returns {boolean} Returns `true` if there are no stash entries in this repository.
+   *
+   * @example
+   * ```ts
+   * import { openRepository } from 'es-git';
+   *
+   * const repo = await openRepository('./path/to/repo');
+   * const stashList = repo.stashList();
+   *
+   * if (stashList.isEmpty()) {
+   *   console.log('No stashes found');
+   * } else {
+   *   console.log(`Found ${stashList.len()} stashes`);
+   * }
+   * ```
+   */
+  isEmpty(): boolean
+  /**
+   * Returns an iterator over the stash entries in this list.
+   *
+   * The iterator yields stash entries in order from newest (index 0) to oldest.
+   *
+   * @category Stash/Methods
+   * @signature
+   * ```ts
+   * class StashList {
+   *   iter(): StashListIter;
+   * }
+   * ```
+   *
+   * @returns {StashListIter} An iterator that yields StashEntry objects.
+   *
+   * @example
+   * ```ts
+   * import { openRepository } from 'es-git';
+   *
+   * const repo = await openRepository('./path/to/repo');
+   * const stashList = repo.stashList();
+   *
+   * // Iterate over stashes
+   * for (const stash of stashList.iter()) {
+   *   console.log(`${stash.index()}: ${stash.message()}`);
+   * }
+   * ```
+   */
+  iter(): StashListIter
+}
+export declare class StashListIter {
+  [Symbol.iterator](): Iterator<StashEntry, void, void>
+}
 /**
  * A container for a list of status information about a repository.
  *

package/index.js

@@ -310,7 +310,7 @@ if (!nativeBinding) {
   throw new Error(`Failed to load native binding`)
 }
 
-const { AnnotatedCommit, Blame, BlameHunks, BlameHunksByLine, Blob, isValidBranchName, Branch, Branches, BranchType, Commit, ConfigLevel, ConfigEntries, Config, openConfig, openDefaultConfig, findGlobalConfigPath, findSystemConfigPath, findXdgConfigPath, parseConfigBool, parseConfigI32, parseConfigI64, DiffFlags, diffFlagsContains, DeltaType, DiffFormat, Diff, DiffStats, Deltas, DiffDelta, FileMode, DiffFile, IndexStage, Index, IndexEntries, Mailmap, createMailmapFromBuffer, FileFavor, ObjectType, GitObject, isValidOid, isZeroOid, zeroOid, hashObjectOid, hashFileOid, ReferenceType, Reference, isValidReferenceName, ReferenceFormat, normalizeReferenceName, Direction, CredentialType, FetchPrune, AutotagOption, RemoteRedirect, Remote, RepositoryState, RepositoryInitMode, Repository, initRepository, openRepository, discoverRepository, cloneRepository, RevparseMode, revparseModeContains, RevwalkSort, Revwalk, createSignature, StatusShow, Statuses, StatusesIter, StatusEntry, isValidTagName, Tag, TreeWalkMode, Tree, TreeIter, TreeEntry } = nativeBinding
+const { AnnotatedCommit, Blame, BlameHunks, BlameHunksByLine, Blob, isValidBranchName, Branch, Branches, BranchType, Commit, ConfigLevel, ConfigEntries, Config, openConfig, openDefaultConfig, findGlobalConfigPath, findSystemConfigPath, findXdgConfigPath, parseConfigBool, parseConfigI32, parseConfigI64, DiffFlags, diffFlagsContains, DeltaType, DiffFormat, Diff, DiffStats, Deltas, DiffDelta, FileMode, DiffFile, IndexStage, Index, IndexEntries, Mailmap, createMailmapFromBuffer, FileFavor, ObjectType, GitObject, isValidOid, isZeroOid, zeroOid, hashObjectOid, hashFileOid, Rebase, RebaseOperationType, ReferenceType, Reference, isValidReferenceName, ReferenceFormat, normalizeReferenceName, Direction, CredentialType, FetchPrune, AutotagOption, RemoteRedirect, Remote, RepositoryState, RepositoryInitMode, Repository, initRepository, openRepository, discoverRepository, cloneRepository, RevparseMode, revparseModeContains, RevwalkSort, Revwalk, createSignature, StashEntry, StashList, StashListIter, StatusShow, Statuses, StatusesIter, StatusEntry, isValidTagName, Tag, TreeWalkMode, Tree, TreeIter, TreeEntry } = nativeBinding
 
 module.exports.AnnotatedCommit = AnnotatedCommit
 module.exports.Blame = Blame
@@ -356,6 +356,8 @@ module.exports.isZeroOid = isZeroOid
 module.exports.zeroOid = zeroOid
 module.exports.hashObjectOid = hashObjectOid
 module.exports.hashFileOid = hashFileOid
+module.exports.Rebase = Rebase
+module.exports.RebaseOperationType = RebaseOperationType
 module.exports.ReferenceType = ReferenceType
 module.exports.Reference = Reference
 module.exports.isValidReferenceName = isValidReferenceName
@@ -379,6 +381,9 @@ module.exports.revparseModeContains = revparseModeContains
 module.exports.RevwalkSort = RevwalkSort
 module.exports.Revwalk = Revwalk
 module.exports.createSignature = createSignature
+module.exports.StashEntry = StashEntry
+module.exports.StashList = StashList
+module.exports.StashListIter = StashListIter
 module.exports.StatusShow = StatusShow
 module.exports.Statuses = Statuses
 module.exports.StatusesIter = StatusesIter

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "es-git",
-  "version": "0.4.0",
+  "version": "0.5.0-next.153+40f6275",
   "main": "index.js",
   "types": "index.d.ts",
   "files": [
@@ -13,7 +13,7 @@
     "url": "https://github.com/toss/es-git.git"
   },
   "license": "MIT",
-  "packageManager": "yarn@4.9.1",
+  "packageManager": "yarn@4.9.2",
   "napi": {
     "name": "es-git",
     "triples": {
@@ -57,15 +57,15 @@
     "vitest": "^3.0.5"
   },
   "optionalDependencies": {
-    "es-git-darwin-x64": "0.4.0",
-    "es-git-darwin-arm64": "0.4.0",
-    "es-git-win32-x64-msvc": "0.4.0",
-    "es-git-win32-arm64-msvc": "0.4.0",
-    "es-git-linux-x64-gnu": "0.4.0",
-    "es-git-linux-x64-musl": "0.4.0",
-    "es-git-android-arm64": "0.4.0",
-    "es-git-linux-arm64-gnu": "0.4.0",
-    "es-git-linux-arm64-musl": "0.4.0",
-    "es-git-android-arm-eabi": "0.4.0"
+    "es-git-darwin-x64": "0.5.0-next.153+40f6275",
+    "es-git-darwin-arm64": "0.5.0-next.153+40f6275",
+    "es-git-win32-x64-msvc": "0.5.0-next.153+40f6275",
+    "es-git-win32-arm64-msvc": "0.5.0-next.153+40f6275",
+    "es-git-linux-x64-gnu": "0.5.0-next.153+40f6275",
+    "es-git-linux-x64-musl": "0.5.0-next.153+40f6275",
+    "es-git-android-arm64": "0.5.0-next.153+40f6275",
+    "es-git-linux-arm64-gnu": "0.5.0-next.153+40f6275",
+    "es-git-linux-arm64-musl": "0.5.0-next.153+40f6275",
+    "es-git-android-arm-eabi": "0.5.0-next.153+40f6275"
   }
 }