feat: implements branch features

index.d.ts

@@ -3,6 +3,46 @@
 
 /* auto-generated by NAPI-RS */
 
+/**
+ * Ensure the branch name is well-formed.
+ *
+ * @category Branch
+ * @signature
+ * ```ts
+ * function isValidBranchName(name: string): boolean;
+ * ```
+ *
+ * @param {string} name - Branch name to check is valid.
+ * @returns Returns `true` if the given branch name is well-formed.
+ */
+export declare function isValidBranchName(name: string): boolean
+export interface BranchesItem {
+  type: BranchType
+  name: string
+}
+/**
+ * - `Local` : A local branch not on a remote.
+ * - `Remote` : A branch for a remote.
+ */
+export type BranchType = 'Local' | 'Remote';
+export interface BranchRenameOptions {
+  /**
+   * If the force flag is not enabled, and there's already a branch with
+   * the given name, the renaming will fail.
+   */
+  force?: boolean
+}
+export interface CreateBranchOptions {
+  /**
+   * If `force` is true and a reference already exists with the given name,
+   * it'll be replaced.
+   */
+  force?: boolean
+}
+export interface BranchesFilter {
+  /** Branch type to filter. */
+  type?: BranchType
+}
 export interface CommitOptions {
   updateRef?: string
   /**
@@ -1446,6 +1486,148 @@ export declare class Blob {
    */
   size(): bigint
 }
+/**
+ * A structure to represent a git [branch][1]
+ *
+ * A branch is currently just a wrapper to an underlying `Reference`. The
+ * reference can be accessed through the `get` and `into_reference` methods.
+ *
+ * [1]: http://git-scm.com/book/en/Git-Branching-What-a-Branch-Is
+ */
+export declare class Branch {
+  /**
+   * Get the OID pointed to by a reference which is this branch.
+   *
+   * @category Branch/Methods
+   * @signature
+   * ```ts
+   * class Branch {
+   *   referenceTarget(): string | null;
+   * }
+   * ```
+   *
+   * @returns The OID pointed to by a reference which is this branch.
+   */
+  referenceTarget(): string | null
+  /**
+   * Delete an existing branch reference.
+   *
+   * @category Branch/Methods
+   * @signature
+   * ```ts
+   * class Branch {
+   *   delete(): void;
+   * }
+   * ```
+   */
+  delete(): void
+  /**
+   * Determine if the current local branch is pointed at by `HEAD`.
+   *
+   * @category Branch/Methods
+   * @signature
+   * ```ts
+   * class Branch {
+   *   isHead(): boolean;
+   * }
+   * ```
+   *
+   * @returns Returns `true` if the current local branch is pointed at by `HEAD`.
+   */
+  isHead(): boolean
+  /**
+   * Move/rename an existing local branch reference.
+   *
+   * @category Branch/Methods
+   * @signature
+   * ```ts
+   * class Branch {
+   *   rename(newBranchName: string, options?: BranchRenameOptions | null | undefined): Branch;
+   * }
+   * ```
+   *
+   * @param {string} newBranchName - Branch name to move/rename.
+   * @param {BranchRenameOptions} [options] - Options for move/rename branch.
+   * @returns Move/renamed branch.
+   */
+  rename(newBranchName: string, options?: BranchRenameOptions | undefined | null): Branch
+  /**
+   * Return the name of the given local or remote branch.
+   *
+   * @category Branch/Methods
+   * @signature
+   * ```ts
+   * class Branch {
+   *   name(): string;
+   * }
+   * ```
+   *
+   * @returns The name of the given local or remote branch.
+   * @throws If the name is not valid utf-8.
+   */
+  name(): string
+  /**
+   * Return the reference supporting the remote tracking branch, given a
+   * local branch reference.
+   *
+   * @category Branch/Methods
+   * @signature
+   * ```ts
+   * class Branch {
+   *   findUpstream(): Branch | null;
+   * }
+   * ```
+   *
+   * @returns The reference supporting the remote tacking branch.
+   */
+  findUpstream(): Branch | null
+  /**
+   * Return the reference supporting the remote tracking branch, given a
+   * local branch reference.
+   *
+   * @category Branch/Methods
+   * @signature
+   * ```ts
+   * class Branch {
+   *   getUpstream(): Branch;
+   * }
+   * ```
+   *
+   * @returns The reference supporting the remote tacking branch.
+   * @throws Throws error if upstream does not exist.
+   */
+  getUpstream(): Branch
+  /**
+   * Set the upstream configuration for a given local branch.
+   *
+   * @category Branch/Methods
+   * @signature
+   * ```ts
+   * class Branch {
+   *   setUpstream(upstreamName: string): void;
+   * }
+   * ```
+   *
+   * @param {string} upstreamName - Branch name to set as upstream.
+   */
+  setUpstream(upstreamName: string): void
+  /**
+   * Unset the upstream configuration for a given local branch.
+   *
+   * @category Branch/Methods
+   * @signature
+   * ```ts
+   * class Branch {
+   *   unsetUpstream(): void;
+   * }
+   * ```
+   */
+  unsetUpstream(): void
+}
+/** An iterator over the branches inside of a repository. */
+export declare class Branches {
+  [Symbol.iterator](): Iterator<BranchesItem, void, void>
+}
 /** A class to represent a git commit. */
 export declare class Commit {
   /**
@@ -3231,6 +3413,88 @@ export declare class Remote {
  * This class corresponds to a git repository in libgit2.
  */
 export declare class Repository {
+  /**
+   * Create a new branch pointing at a target commit
+   *
+   * A new direct reference will be created pointing to this target commit.
+   *
+   * @category Repository/Methods
+   * @signature
+   * ```ts
+   * class Repository {
+   *   createBranch(
+   *     branchName: string,
+   *     target: Commit,
+   *     options?: CreateBranchOptions | null | undefined,
+   *   ): Branch;
+   * }
+   * ```
+   *
+   * @param {string} branchName - Name for the new branch.
+   * @param {Commit} target - Target commit which will be pointed by this branch.
+   * @param {CreateBranchOptions} [options] - Options for create branch.
+   * @returns {Branch} Newly created branch.
+   */
+  createBranch(branchName: string, target: Commit, options?: CreateBranchOptions | undefined | null): Branch
+  /**
+   * Lookup a branch by its name in a repository.
+   *
+   * @category Repository/Methods
+   * @signature
+   * ```ts
+   * class Repository {
+   *   findBranch(name: string, branchType: BranchType): Branch | null;
+   * }
+   * ```
+   *
+   * @param {string} name - A branch name.
+   * @param {BranchType} branchType - Branch type to lookup.
+   * @returns A found branch.
+   */
+  findBranch(name: string, branchType: BranchType): Branch | null
+  /**
+   * Lookup a branch by its name in a repository.
+   *
+   * @category Repository/Methods
+   * @signature
+   * ```ts
+   * class Repository {
+   *   getBranch(name: string, branchType: BranchType): Branch;
+   * }
+   * ```
+   *
+   * @param {string} name - A branch name.
+   * @param {BranchType} branchType - Branch type to lookup.
+   * @returns A found branch.
+   * @throws Throws error if branch does not exist.
+   */
+  getBranch(name: string, branchType: BranchType): Branch
+  /**
+   * Create an iterator which loops over the requested branches.
+   *
+   * @category Repository/Methods
+   * @signature
+   * ```ts
+   * class Repository {
+   *   branches(filter?: BranchesFilter | null | undefined): Branches;
+   * }
+   * ```
+   *
+   * @param {BranchesFilter} [filter] - Filter for the branches iterator.
+   * @returns An iterator which loops over the requested branches.
+   * @example
+   * ```ts
+   * import { openRepository } from 'es-git';
+   *
+   * const repo = await openRepository('/path/to/repo');
+   *
+   * for (const branch of repo.branches()) {
+   *   console.log(branch.type); // "Local"
+   *   console.log(branch.name); // "main"
+   * }
+   * ```
+   */
+  branches(filter?: BranchesFilter | undefined | null): Branches
   /**
    * Lookup a reference to one of the commits in a repository.
    *