### Install es-git with bun

Source: https://github.com/toss/es-git/blob/main/docs/getting-started.md

Install the es-git package using bun.

```sh
bun add es-git
```

--------------------------------

### Install Benchmark Dependencies

Source: https://github.com/toss/es-git/blob/main/benchmarks/README.md

Run this command to install the necessary dependencies for running the benchmarks. It assumes you are in the 'nodegit' directory.

```shell
cd nodegit
npm install
```

--------------------------------

### Install es-git with yarn

Source: https://github.com/toss/es-git/blob/main/docs/getting-started.md

Install the es-git package using yarn.

```sh
yarn add es-git
```

--------------------------------

### Install es-git with pnpm

Source: https://github.com/toss/es-git/blob/main/docs/getting-started.md

Install the es-git package using pnpm.

```sh
pnpm add es-git
```

--------------------------------

### Install es-git with npm

Source: https://github.com/toss/es-git/blob/main/docs/getting-started.md

Install the es-git package using npm.

```sh
npm install es-git
```

--------------------------------

### Run Benchmarks

Source: https://github.com/toss/es-git/blob/main/benchmarks/README.md

Execute this command to start the benchmark tests. This command is part of the 'just' task runner.

```shell
just benchmarks
```

--------------------------------

### Submodule.addFinalize()

Source: https://github.com/toss/es-git/blob/main/docs/reference/Submodule/Methods/addFinalize.md

Finalizes the setup of a new git submodule. This method should be called after `add setup` and the submodule clone operation. It stages the `.gitmodules` file and the submodule for commit.

```APIDOC
## Submodule.addFinalize()

### Description
Resolves the setup of a new git submodule. This should be called on a submodule once you have called add setup and done the clone of the submodule. This adds the `.gitmodules` file and the newly cloned submodule to the index to be ready to be committed (but doesn't actually do the commit).

### Method
```ts
addFinalize(): void
```

### Parameters
None

### Response
None
```

--------------------------------

### clone

Source: https://github.com/toss/es-git/blob/main/docs/reference/Submodule/Methods/clone.md

Performs the necessary `git clone` to setup a newly-created submodule.

```APIDOC
## clone

### Description
Performs the necessary `git clone` to setup a newly-created submodule.

### Signature
```ts
clone(
  options?: SubmoduleUpdateOptions | null | undefined,
  signal?: AbortSignal | null | undefined,
): Promise<Repository>;
```

### Parameters
#### Optional Parameters
- **options** (SubmoduleUpdateOptions | null | undefined) - Options for updating the submodule.
- **signal** (AbortSignal | null | undefined) - An AbortSignal to cancel the operation.
```

--------------------------------

### Get Remote Names

Source: https://github.com/toss/es-git/blob/main/docs/reference/Repository/Methods/remoteNames.md

Demonstrates how to get all remote names configured for a repository. Requires opening a repository first.

```typescript
import { openRepository } from 'es-git';

const repo = await openRepository('/path/to/repo');
console.log(repo.remoteNames()); // ["origin"]
```

--------------------------------

### discoverRepository

Source: https://github.com/toss/es-git/blob/main/docs/reference/Repository/discoverRepository.md

Attempts to open an existing repository by searching the filesystem hierarchy starting from the provided path.

```APIDOC
## discoverRepository

### Description
Attempts to open an already-existing repository at or above the specified path by searching the filesystem hierarchy.

### Signature
```ts
function discoverRepository(path: string, signal?: AbortSignal | null | undefined): Promise<Repository>;
```

### Parameters

#### Path Parameters
- **path** (string) - Required - Directory path to discover repository.
- **signal** (null | AbortSignal) - Optional - Abort signal.

### Returns

#### Success Response
- **Repository** - A Promise that resolves to the discovered Git repository.
```

--------------------------------

### Benchmark Results: Get Commit Operation

Source: https://github.com/toss/es-git/blob/main/benchmarks/README.md

Performance comparison for the 'get commit' operation. This table presents the speed and statistical performance metrics for es-git and other implementations.

```text
 ✓ index.bench.ts > get commit 2451ms
     name                       hz      min      max     mean      p75      p99     p995     p999     rme  samples
   · es-git               7,628.10   0.1154   1.2045   0.1311   0.1328   0.1821   0.1898   0.3014  ±0.51%     3815   fastest
   · nodegit              6,723.92   0.1314  11.6206   0.1487   0.1474   0.2221   0.2447   0.3603  ±4.52%     3362
   · @napi-rs/simple-git  2,359.88   0.3026   0.7248   0.4238   0.5073   0.6490   0.6592   0.7231  ±1.42%     1180
   · child_process         78.9937  12.1418  14.0038  12.6592  12.7804  14.0038  14.0038  14.0038  ±0.96%       40   slowest
```

--------------------------------

### Mailmap File Format Example

Source: https://github.com/toss/es-git/blob/main/docs/reference/Mailmap/createMailmapFromBuffer.md

Illustrates the expected format for mailmap file content, including comments and user mappings.

```plaintext
# Comment line (ignored)
Seokju Me <seokju.me@toss.im> Seokju Na <seokju.me@gmail.com>
```

--------------------------------

### Get Repository Configuration

Source: https://github.com/toss/es-git/blob/main/docs/reference/Repository/Methods/config.md

Retrieves the configuration object for the repository. Returns default configurations if none are explicitly set.

```typescript
class Repository {
  config(): Config;
}
```

--------------------------------

### Blame Line Range

Source: https://github.com/toss/es-git/blob/main/docs/reference/Repository/Methods/blameFile.md

Use this snippet to get blame information for a specific range of lines within a file. Specify the start and end lines using `minLine` and `maxLine` options.

```typescript
const rangeBlame = repo.blameFile('path/to/file.js', { minLine: 5, maxLine: 15 });
```

--------------------------------

### Emulate git add *

Source: https://github.com/toss/es-git/blob/main/docs/reference/Index/Methods/addAll.md

This example demonstrates how to use addAll to add all files in the working directory to the index, similar to the `git add *` command. It requires opening a repository and accessing its index.

```typescript
import {
  openRepository
} from 'es-git';

const repo = await openRepository('.');
const index = repo.index();
index.addAll(['*']);
index.write();
```

--------------------------------

### findStatusFile(path: string): Status | null

Source: https://github.com/toss/es-git/blob/main/docs/reference/Repository/Methods/findStatusFile.md

Get file status for a single file. This tries to get status for the filename that you give. If no files match that name (in either the HEAD, index, or working directory), this returns NotFound. If the name matches multiple files (for example, if the path names a directory or if running on a case-insensitive filesystem and yet the HEAD has two entries that both match the path), then this returns Ambiguous because it cannot give correct results. This does not do any sort of rename detection.

```APIDOC
## findStatusFile(path: string): Status | null

### Description
Get file status for a single file. This tries to get status for the filename that you give. If no files match that name (in either the HEAD, index, or working directory), this returns NotFound. If the name matches multiple files (for example, if the path names a directory or if running on a case-insensitive filesystem and yet the HEAD has two entries that both match the path), then this returns Ambiguous because it cannot give correct results. This does not do any sort of rename detection.

### Method
```ts
Repository.findStatusFile
```

### Parameters
#### Path Parameters
- **path** (string) - required - A single file path.

### Returns
#### Success Response
- **null | Status** - The `Status` of this single file. If the status file does not exists, returns `null`.
  - **conflicted** (boolean) - required
  - **current** (boolean) - required
  - **ignored** (boolean) - required
  - **indexDeleted** (boolean) - required
  - **indexModified** (boolean) - required
  - **indexNew** (boolean) - required
  - **indexRenamed** (boolean) - required
  - **indexTypechange** (boolean) - required
  - **wtDeleted** (boolean) - required
  - **wtModified** (boolean) - required
  - **wtNew** (boolean) - required
  - **wtRenamed** (boolean) - required
  - **wtTypechange** (boolean) - required
```

--------------------------------

### Initialize a New Repository

Source: https://github.com/toss/es-git/blob/main/docs/reference/Repository/initRepository.md

Initializes a new repository at the specified path. This is the basic usage.

```typescript
import { initRepository } from 'es-git';

const repo = await iniRepository('/path/to/repo');
```

--------------------------------

### Merge Diff Example

Source: https://github.com/toss/es-git/blob/main/docs/reference/Diff/Methods/merge.md

Demonstrates how to merge another diff into the current one. This method modifies the existing diff in place.

```typescript
class Diff {
  merge(diff: Diff): void;
}
```

--------------------------------

### Create a Bare Repository

Source: https://github.com/toss/es-git/blob/main/docs/reference/Repository/initRepository.md

Initializes a new bare repository. Bare repositories do not have a working directory and are typically used on servers.

```typescript
import { initRepository } from 'es-git';

const repo = await iniRepository('/path/to/repo.git', {
  bare: true,
});
```

--------------------------------

### initRepository

Source: https://github.com/toss/es-git/blob/main/docs/reference/Repository/initRepository.md

Initializes a new repository at the specified path. It can optionally create a bare repository.

```APIDOC
## initRepository

### Description
Initializes a new repository at the specified path. It can optionally create a bare repository.

### Method
Not specified (SDK function)

### Parameters
#### Path Parameters
- **path** (string) - Required - The path where the repository will be initialized.
- **options** (object) - Optional - Configuration options for the repository.
  - **bare** (boolean) - Optional - If true, creates a bare repository.

### Returns
#### Success Response
- **Repository** (Promise<Repository>) - A Promise that resolves to the newly created Repository object.

### Examples

#### Basic Example
```ts
import { initRepository } from 'es-git';

const repo = await initRepository('/path/to/repo');
```

#### Create Bare Repository
```ts
import { initRepository } from 'es-git';

const repo = await initRepository('/path/to/repo.git', {
  bare: true,
});
```
```

--------------------------------

### Get StatusEntry Path

Source: https://github.com/toss/es-git/blob/main/docs/reference/Status/StatusEntry/path.md

Call the path() method on a StatusEntry instance to get its path name.

```typescript
class StatusEntry {
  path(): string;
}
```

--------------------------------

### repoInit

Source: https://github.com/toss/es-git/blob/main/docs/reference/Submodule/Methods/repoInit.md

Initializes a submodule repository. This method sets up the necessary structure for a submodule's repository, preparing it to be cloned from its remote location. It supports optional parameters for configuring the repository's placement and for cancellation.

```APIDOC
## repoInit

### Description
Initializes and sets up a submodule repository in preparation for cloning.

### Method
Submodule.repoInit

### Parameters
#### Optional Parameters
- **useGitlink** (boolean | null) - Optional - Determines if the working directory should contain a gitlink to the repository in `.git/modules` or if the repository should be placed directly in the working directory.
- **signal** (AbortSignal | null) - Optional - An AbortSignal that can be used to cancel the operation.

### Returns
- **Promise<Repository>** - A promise that resolves with the initialized Repository object.
```

--------------------------------

### Get Blob Size

Source: https://github.com/toss/es-git/blob/main/docs/reference/Blob/Methods/size.md

This snippet shows how to get the size of a blob in bytes. The size is returned as a bigint.

```typescript
class Blob {
  size(): bigint;
}
```

--------------------------------

### Repository.submodule

Source: https://github.com/toss/es-git/blob/main/docs/reference/Repository/Methods/submodule.md

Sets up a new git submodule for checkout. This method performs the initial steps of 'git submodule add', including creating an entry in .gitmodules and initializing a repository at the specified path or in .git/modules.

```APIDOC
## Repository.submodule

### Description
Sets up a new git submodule for checkout. This method performs the initial steps of 'git submodule add', including creating an entry in .gitmodules and initializing a repository at the specified path or in .git/modules.

### Method
submodule

### Parameters
#### Path Parameters
- **url** (string) - Required - URL for the submodule's remote.
- **path** (string) - Required - Path at which the submodule should be created.
- **useGitlink** (null | boolean) - Optional - Should workdir contain a gitlink to the repo in `.git/modules` vs. repo directly in workdir.

### Returns
#### Success Response
- **Submodule** (Submodule) - The submodule.
```

--------------------------------

### Generate Reference Documentation

Source: https://github.com/toss/es-git/blob/main/docs/README.md

Use these commands to generate reference documentation. Options include generating all docs, specifying language, using glob patterns for specific files, or translating with OpenAI.

```shell
# Generate all reference documentations.
just docs-gen reference
```

```shell
# Generate all korean reference docuementations.
just docs-gen reference --lang=ko
```

```shell
# Generate specific reference documentations with glob pattern.
just docs-gen reference --pattern='Tree/Methods/*'
```

```shell
# Translate with OpenAI. Or pass api token with environment variables. (/docs/.env)
just docs-gen reference --translate-ai-token="<OpenAI API Key>"
```

--------------------------------

### Get filemode of a TreeEntry

Source: https://github.com/toss/es-git/blob/main/docs/reference/Tree/TreeEntry/filemode.md

Call the filemode() method on a TreeEntry instance to get its UNIX file attributes as a number.

```typescript
class TreeEntry {
  filemode(): number;
}
```

--------------------------------

### Get Tag Name

Source: https://github.com/toss/es-git/blob/main/docs/reference/Tag/Methods/name.md

This snippet shows how to get the name of a tag using the `name()` method. Ensure the tag name is valid UTF-8.

```typescript
class Tag {
  name(): string;
}
```

--------------------------------

### Get Submodule Working Directory OID

Source: https://github.com/toss/es-git/blob/main/docs/reference/Submodule/Methods/workdirId.md

Use this method to get the OID for the submodule in the current working directory. It returns null if no OID is found.

```typescript
class Submodule {
  workdirId(): string | null;
}
```

--------------------------------

### Get Repository Statuses

Source: https://github.com/toss/es-git/blob/main/docs/reference/Repository/Methods/statuses.md

Call the statuses() method on a Repository instance to get the status of all files. Ensure no pathspec is provided for accurate rename detection.

```typescript
class Repository {
  statuses(): Statuses;
}
```

--------------------------------

### initRepository

Source: https://github.com/toss/es-git/blob/main/docs/reference/Repository/initRepository.md

Creates a new repository in the specified folder. This function initializes a Git repository at the given path, with optional configuration and an abort signal.

```APIDOC
## initRepository

### Description
Creates a new repository in the specified folder.

### Signature
```ts
function initRepository(
  path: string,
  options?: RepositoryInitOptions | null | undefined,
  signal?: AbortSignal | null | undefined,
): Promise<Repository>;
```

### Parameters
#### Path Parameters
- **path** (string) - Required - The path where the repository will be initialized.
- **options** (RepositoryInitOptions | null | undefined) - Optional - Configuration options for initializing the repository.
- **signal** (AbortSignal | null | undefined) - Optional - An abort signal to cancel the operation.
```

--------------------------------

### Get Branch Reference Target

Source: https://github.com/toss/es-git/blob/main/docs/reference/Branch/Methods/referenceTarget.md

Call `referenceTarget()` on a `Branch` instance to get the OID it points to. Returns `null` if the branch does not point to a valid OID.

```typescript
class Branch {
  referenceTarget(): string | null;
}
```

--------------------------------

### Create a Tag with Tagger Information

Source: https://github.com/toss/es-git/blob/main/docs/reference/Repository/Methods/createTag.md

This example demonstrates how to create a new tag with specific tagger information. It opens a repository, retrieves a commit, and then creates a tag named 'mytag' pointing to that commit. The tagger's name and email are provided in the options. Finally, it retrieves the created tag and logs its name and target.

```typescript
import {
  openRepository
} from 'es-git';

const repo = await openRepository('.');
const commit = repo.getCommit('828954df9f08dc8e172447cdacf0ddea1adf9e63');

const sha = repo.createTag(
  'mytag',
  commit.asObject(),
  'this is my tag message',
  {
    tagger: {
      name: 'Seokju Na',
      email: 'seokju.me@toss.im',
    },
  },
);
const tag = repo.getTag(sha);
console.log(tag.name()); // "mytag"
console.log(tag.target().id()); // "828954df9f08dc8e172447cdacf0ddea1adf9e63"
```

--------------------------------

### initRepository

Source: https://github.com/toss/es-git/blob/main/docs/reference/Repository/initRepository.md

Initializes a new Git repository at the specified directory path. It supports various configuration options to customize the initialization process.

```APIDOC
## initRepository

### Description
Initializes a new Git repository at the specified directory path. It supports various configuration options to customize the initialization process.

### Parameters
#### Path Parameters
- **path** (string) - required - Directory path to create new repository.

#### Request Body
- **options** (null | RepositoryInitOptions) - optional - Options which can be used to configure how a repository is initialized.
  - **bare** (boolean) - optional - Create a bare repository with no working directory. Defaults to `false`.
  - **description** (string) - optional - If set, this will be used to initialize the "description" file in the repository instead of using the template content.
  - **externalTemplate** (boolean) - optional - Enable or disable using external templates. If enabled, then the `template_path` option will be queried first, then `init.templatedir` from the global config, and finally `/usr/share/git-core-templates` will be used (if it exists). Defaults to `true`.
  - **initialHead** (string) - optional - The name of the head to point HEAD at. If not configured, this will be taken from your git configuration. If this begins with `refs/` it will be used verbatim; otherwise `refs/heads/` will be prefixed.
  - **mkdir** (boolean) - optional - Make the repo path (and workdir path) as needed. The ".git" directory will always be created regardless of this flag. Defaults to `true`.
  - **mkpath** (boolean) - optional - Make the repo path (and workdir path) as needed. The ".git" directory will always be created regardless of this flag. Defaults to `true`.
  - **mode** (number) - optional - Set to one of the `RepositoryInit` constants, or a custom value.
  - **noDotgitDir** (boolean) - optional - Normally a `/.git/` will be appended to the repo path for non-bare repos (if it is not already there), but passing this flag prevents that behavior. Defaults to `false`.
  - **noReinit** (boolean) - optional - Return an error if the repository path appears to already be a git repository. Defaults to `false`.
  - **originUrl** (string) - optional - If set, then after the rest of the repository initialization is completed an `origin` remote will be added pointing to this URL.
  - **templatePath** (string) - optional - When the `externalTemplate` option is set, this is the first location to check for the template directory. If this is not configured, then the default locations will be searched instead.
  - **workdirPath** (string) - optional - The path to the working directory. If this is a relative path it will be evaluated relative to the repo path. If this is not the "natural" working directory, a .git gitlink file will be created here linking to the repo path.
- **signal** (null | AbortSignal) - optional -
```

--------------------------------

### Get Submodule HEAD OID

Source: https://github.com/toss/es-git/blob/main/docs/reference/Submodule/Methods/headId.md

Call `headId()` on a `Submodule` instance to get the OID of the submodule in the current HEAD tree. Returns null if the submodule is not found.

```typescript
class Submodule {
  headId(): string | null;
}
```

--------------------------------

### Stage All Files

Source: https://github.com/toss/es-git/blob/main/docs/usage/commit.md

Use this snippet to stage all files in the staging area, similar to the `git add *` command. It requires an existing repository object and calls the `addAll()` method on the index.

```typescript
const index = repo.index();
index.addAll(['*']);
index.write();
```

--------------------------------

### Reflog get Method Signature

Source: https://github.com/toss/es-git/blob/main/docs/reference/Reflog/Methods/get.md

This is the TypeScript signature for the get method of the Reflog class. It takes a number as an index and returns either a ReflogEntry object or null.

```typescript
class Reflog {
  get(i: number): ReflogEntry | null;
}
```

--------------------------------

### Open Rebase

Source: https://github.com/toss/es-git/blob/main/docs/reference/Repository/Methods/openRebase.md

Initializes a rebase operation, returning a handle for further steps. Throws an error if the rebase was not found.

```APIDOC
## Open Rebase

### Description
Initializes a rebase operation, returning a handle for further steps. Throws an error if the rebase was not found.

### Returns
- **Rebase** (Rebase) - The initialized rebase handle to iterate and apply steps.

### Errors
- **Error** - Throws if the existing rebase was not found.
```

--------------------------------

### Branch setUpstream Method Signature

Source: https://github.com/toss/es-git/blob/main/docs/reference/Branch/Methods/setUpstream.md

This is the TypeScript signature for the setUpstream method on the Branch class. It indicates that the method takes a single string argument representing the upstream branch name and returns nothing.

```typescript
class Branch {
  setUpstream(upstreamName: string): void;
}
```

--------------------------------

### Get Submodule Ignore Rule

Source: https://github.com/toss/es-git/blob/main/docs/reference/Submodule/Methods/ignoreRule.md

Call the ignoreRule() method on a Submodule instance to get its associated ignore rule. This rule dictates the depth of inspection for the submodule's working directory status.

```typescript
class Submodule {
  ignoreRule(): SubmoduleIgnore;
}
```

--------------------------------

### getI64 Method

Source: https://github.com/toss/es-git/blob/main/docs/reference/Config/Methods/getI64.md

Retrieves the value of an integer configuration variable by its name. The method searches through all configuration files in order of priority and returns the first matching entry.

```APIDOC
## getI64

### Description
Get the value of an integer config variable. All config files will be looked into, in the order of their defined level. A higher level means a higher priority. The first occurrence of the variable will be returned here.

### Method Signature
```ts
class Config {
  getI64(name: string): number;
}
```

### Parameters
#### Path Parameters
- **name** (string) - Required - The name of config entry.

### Returns
#### Success Response
- **number** - The value of an integer config variable.
```

--------------------------------

### len()

Source: https://github.com/toss/es-git/blob/main/docs/reference/Rebase/Methods/len.md

Gets the count of rebase operations that are to be applied.

```APIDOC
## len()

### Description
Gets the count of rebase operations that are to be applied.

### Method
```ts
len(): number;
```

### Returns
- **bigint** - The count of rebase operations.
```

--------------------------------

### getByPath

Source: https://github.com/toss/es-git/blob/main/docs/reference/Index/Methods/getByPath.md

Get one of the entries in the index by its path.

```APIDOC
## getByPath

### Description
Get one of the entries in the index by its path.

### Method
```ts
Index.getByPath(path: string, stage?: IndexStage | null | undefined): IndexEntry | null
```

### Parameters
#### Path Parameters
- **path** (string) - required - Path to lookup entry.
- **stage** (null | IndexStage) - optional - Git index stage states.
  - `Any` : Match any index stage.
  - `Normal` : A normal staged file in the index.
  - `Ancestor` : The ancestor side of a conflict.
  - `Ours` : The "ours" side of a conflict.
  - `Theirs` : The "theirs" side of a conflict.

### Returns
- **IndexEntry | null** - Index entry for the path.

#### Success Response (200)
- **ctime** (Date) - required
- **dev** (number) - required
- **fileSize** (number) - required
- **flags** (number) - required
- **flagsExtended** (number) - required
- **gid** (number) - required
- **id** (string) - required
- **ino** (number) - required
- **mode** (number) - required
- **mtime** (Date) - required
- **path** (Buffer) - required - The path of this index entry as a byte vector. Regardless of the current platform, the directory separator is an ASCII forward slash (0x2F). There are no terminating or internal NUL characters, and no trailing slashes. Most of the time, paths will be valid utf-8 — but not always. For more information on the path storage format, see [these git docs](https://github.com/git/git/blob/a08a83db2bf27f015bec9a435f6d73e223c21c5e/Documentation/technical/index-format.txt#L107-L124). Note that libgit2 will take care of handling the prefix compression mentioned there.
- **uid** (number) - required
```

--------------------------------

### Open Bare Repository

Source: https://github.com/toss/es-git/blob/main/docs/reference/Repository/openRepository.md

Opens a repository as a bare repository, ignoring any working directory. This is useful for performance when only repository data is needed. The path should typically end with `.git` for bare repositories.

```typescript
import { openRepository } from 'es-git';

const repo = await openRepository('/path/to/repo.git', {
  bare: true,
});
```

--------------------------------

### Tag.targetId()

Source: https://github.com/toss/es-git/blob/main/docs/reference/Tag/Methods/targetId.md

Gets the OID of the tagged object for a given tag.

```APIDOC
## Tag.targetId()

### Description
Retrieves the Object ID (OID) of the object that a tag points to.

### Method
```ts
targetId(): string
```

### Returns
- **string**: OID of the tagged object of a tag.
```

--------------------------------

### originHeadId

Source: https://github.com/toss/es-git/blob/main/docs/reference/Rebase/Methods/originHeadId.md

Gets the original `HEAD` id for merge rebases.

```APIDOC
## originHeadId

### Description
Gets the original `HEAD` id for merge rebases.

### Signature
```ts
originHeadId(): string | null
```

### Returns
- **null | string** - The original `HEAD` id for merge rebases.
```

--------------------------------

### Get StatusEntry Path

Source: https://github.com/toss/es-git/blob/main/docs/reference/Status/StatusEntry/path.md

Retrieves the path name of a StatusEntry as a string.

```APIDOC
## StatusEntry.path()

### Description
Access this entry's path name as a string.

### Signature
```ts
class StatusEntry {
  path(): string;
}
```

### Returns
- **string**: The path of this entry.
```

--------------------------------

### repo.rebase

Source: https://github.com/toss/es-git/blob/main/docs/reference/Repository/Methods/rebase.md

Initializes a rebase operation, returning a handle to apply steps.

```APIDOC
## repo.rebase

### Description
Initializes a rebase operation, returning a handle to apply steps.

### Method
`repo.rebase(branch: AnnotatedCommit, upstream: AnnotatedCommit)`

### Parameters
#### Path Parameters
- **branch** (AnnotatedCommit) - The commit representing the branch to rebase.
- **upstream** (AnnotatedCommit) - The commit representing the upstream branch to rebase onto.

### Returns
#### Success Response
- **Rebase** (object) - 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);
```
```

--------------------------------

### openConfig Function

Source: https://github.com/toss/es-git/blob/main/docs/reference/Config/openConfig.md

Creates a new config instance from a single on-disk file.

```APIDOC
## openConfig

### Description
Creates a new config instance containing a single on-disk file.

### Signature
```ts
function openConfig(path: string): Config;
```

### Parameters
#### Path Parameters
- **path** (string) - Required - Path to config file.

### Returns
#### Success Response
- **Config** (Config) - Config instance representing a git configuration key/value store.
```

--------------------------------

### originHeadName

Source: https://github.com/toss/es-git/blob/main/docs/reference/Rebase/Methods/originHeadName.md

Gets the original `HEAD` ref name for merge rebases.

```APIDOC
## originHeadName

### Description
Gets the original `HEAD` ref name for merge rebases.

### Method
```ts
originHeadName(): string | null
```

### Returns
- **null | string** - The original `HEAD` ref name for merge rebases.
```

--------------------------------

### Submodule.init

Source: https://github.com/toss/es-git/blob/main/docs/reference/Submodule/Methods/init.md

Copies submodule information into the .git/config file. Existing entries are not overwritten by default, but this can be forced by setting `overwrite` to true. An optional AbortSignal can be provided to cancel the operation.

```APIDOC
## Submodule.init

### Description
Copies submodule information into the .git/config file. Existing entries are not overwritten by default, but this can be forced by setting `overwrite` to true. An optional AbortSignal can be provided to cancel the operation.

### Method
```ts
init(overwrite?: boolean | null | undefined, signal?: AbortSignal | null | undefined): Promise<void>
```

### Parameters
#### Optional Parameters
- **overwrite** (boolean | null | undefined) - By default, existing entries will not be overwritten, but setting this to true forces them to be updated.
- **signal** (AbortSignal | null | undefined) - Optional AbortSignal to cancel the operation.
```

--------------------------------

### getHunkByIndex

Source: https://github.com/toss/es-git/blob/main/docs/reference/Blame/Methods/getHunkByIndex.md

Gets blame information for the specified index. The index is 0-based.

```APIDOC
## getHunkByIndex

### Description
Gets blame information for the specified index.

### Method
N/A (SDK Method)

### Signature
```ts
getHunkByIndex(index: number): BlameHunk;
```

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
N/A

### Response
#### Success Response
- **BlameHunk**: Information about the blame hunk.

#### Response Example
N/A
```

--------------------------------

### openDefaultConfig

Source: https://github.com/toss/es-git/blob/main/docs/reference/Config/openDefaultConfig.md

Opens the global, XDG, and system configuration files into a single prioritized config object.

```APIDOC
## openDefaultConfig

### Description
Opens the global, XDG, and system configuration files into a single prioritized config object that can be used when accessing default config data outside a repository.

### Signature

```ts
function openDefaultConfig(): Config;
```

### Returns

- **Config** - Config instance representing a git configuration key/value store.
```

--------------------------------

### Get Submodule Name

Source: https://github.com/toss/es-git/blob/main/docs/reference/Submodule/Methods/name.md

Retrieves the name of the submodule. This method is part of the Submodule class.

```typescript
class Submodule {
  name(): string;
}
```

--------------------------------

### Benchmark Summary

Source: https://github.com/toss/es-git/blob/main/benchmarks/README.md

A summary of benchmark results, highlighting which implementation was faster for specific operations and by what factor.

```text
Summary:

  nodegit - index.bench.ts > open
    1.02x faster than es-git
    4.63x faster than @napi-rs/simple-git

  es-git - index.bench.ts > rev-parse
    1.12x faster than nodegit
    2.53x faster than @napi-rs/simple-git
    71.78x faster than child_process

  es-git - index.bench.ts > revwalk
    1.06x faster than nodegit
    1.29x faster than @napi-rs/simple-git
    11.29x faster than child_process

  es-git - index.bench.ts > get commit
    1.13x faster than nodegit
    3.23x faster than @napi-rs/simple-git
    96.57x faster than child_process
```

--------------------------------

### Repository.config()

Source: https://github.com/toss/es-git/blob/main/docs/reference/Repository/Methods/config.md

Retrieves the configuration file for the repository. If no configuration file is explicitly set, it returns the default configuration, which includes global and system configurations if available.

```APIDOC
## Repository.config()

### Description
Retrieves the configuration file for the repository. If no configuration file is explicitly set, it returns the default configuration, which includes global and system configurations if available.

### Method
```ts
config(): Config
```

### Returns
- **Config** - The configuration object for the repository. This includes default, global, and system configurations if they are available and no specific configuration file has been set.
```

--------------------------------

### len()

Source: https://github.com/toss/es-git/blob/main/docs/reference/Status/Statuses/len.md

Gets the count of status entries in this list. Returns 0 if there are no changes in status.

```APIDOC
## len()

### Description
Gets the count of status entries in this list. If there are no changes in status (according to the options given when the status list was created), this should return 0.

### Method
N/A (Method of a class instance)

### Endpoint
N/A

### Parameters
N/A

### Request Example
N/A

### Response
#### Success Response
- **return value** (bigint) - The count of status entries. Returns 0 if there are no changes in status.
```

--------------------------------

### StashList.len()

Source: https://github.com/toss/es-git/blob/main/docs/reference/Stash/Methods/len.md

Gets the count of stash entries in this list. Returns 0 if there are no stashes in the repository.

```APIDOC
## StashList.len()

### Description
Gets the count of stash entries in this list. Returns 0 if there are no stashes in the repository.

### Method
```ts
len(): number
```

### Returns
- **number**: The number of stash entries. Returns 0 if there are no stashes.
```

--------------------------------

### openRepository

Source: https://github.com/toss/es-git/blob/main/docs/reference/Repository/openRepository.md

Opens an existing repository at the specified directory path. It can accept optional configuration options and an abort signal.

```APIDOC
## openRepository

### Description
Attempt to open an already-existing repository at `path`.

### Signature
```ts
function openRepository(
  path: string,
  options?: RepositoryOpenOptions | null | undefined,
  signal?: AbortSignal | null | undefined,
): Promise<Repository>;
```

### Parameters
#### Path Parameters
- **path** (string) - required - Directory path to repository already-existing.

#### Options
- **options** (RepositoryOpenOptions | null | undefined) - optional - Options which can be used to configure how a repository is initialized.
  - **bare** (boolean) - optional - If this option is `true`, force opening the repository as bare event if it isn't, ignoring any working directory, and defer loading the repository configuration for performance.
  - **ceilingDirs** (string[]) - optional - ceiling_dirs specifies a list of paths that the search through parent directories will stop before entering.
  - **crossFs** (boolean) - optional - If this option is `true`, the search through parent directories will not cross a filesystem boundary (detected when the stat st_dev field changes).
  - **fromEnv** (boolean) - optional - If this option is `true`, `open` will ignore other options and `ceilingDirs`, and respect the same environment variables git does. Note, however, that `path` overrides `$GIT_DIR`.
  - **noDotgit** (boolean) - optional - If this options is `true`, don't try appending `/.git` to `path`.
  - **noSearch** (boolean) - optional - If this option is `true`, the path must point directly to a repository; otherwise, this may point to a subdirectory of a repository, and `open` will search up through parent directories.

#### Signal
- **signal** (AbortSignal | null | undefined) - optional - Abort signal.

### Returns
- **Promise<Repository>** - Opened repository.

### Examples
Basic example.
```ts
import { openRepository } from 'es-git';

const repo = await openRepository('/path/to/repo');
```

Open bare repository.
```ts
import { openRepository } from 'es-git';

const repo = await openRepository('/path/to/repo.git', {
  bare: true,
});
```
```

--------------------------------

### tagNames

Source: https://github.com/toss/es-git/blob/main/docs/reference/Repository/Methods/tagNames.md

Get a list with all the tags in the repository. An optional fnmatch pattern can also be specified.

```APIDOC
## tagNames

### Description
Get a list with all the tags in the repository. An optional fnmatch pattern can also be specified.

### Method
```ts
tagNames(pattern?: string | null | undefined): string[];
```

### Parameters
#### Path Parameters
- **pattern** (string | null | undefined) - Optional - An optional fnmatch pattern can also be specified.
```

--------------------------------

### Iterating Over Repository Tags

Source: https://github.com/toss/es-git/blob/main/docs/reference/Repository/Methods/tagForeach.md

This example demonstrates how to use tagForeach to collect all tag names and their corresponding SHAs into an array. The callback returns true to continue iteration for all tags.

```typescript
import { openRepository } from 'es-git';

const repo = await openRepository('.');
const tags = [];
repo.tagForeach((sha, name) => {
  tags.push([name, sha]);
  return true;
});

console.log(tags);
// [['aa0040546ed22b8bb33f3bd621e8d10ed849b02c', 'refs/tags/v0'],
//  ['674e3327707fcf32a348ecfc0cb6b93e57398b8c', 'refs/tags/v1'],
//  ['567aa5c6b219312dc7758ab88ebb7a1e5d36d26b', 'refs/tags/v2']]
```

--------------------------------

### Repository.noteDefaultRef

Source: https://github.com/toss/es-git/blob/main/docs/reference/Repository/Methods/noteDefaultRef.md

Gets the default notes reference for this repository. This method is part of the Repository class.

```APIDOC
## Repository.noteDefaultRef

### Description
Gets the default notes reference for this repository.

### Method
```ts
Repository.noteDefaultRef(): string
```

### Returns
- **string**: The default notes reference.
```

--------------------------------

### getHunkCount

Source: https://github.com/toss/es-git/blob/main/docs/reference/Blame/Methods/getHunkCount.md

Gets the number of hunks in the blame result. This method is part of the Blame class.

```APIDOC
## getHunkCount

### Description
Gets the number of hunks in the blame result.

### Method
```ts
getHunkCount(): number
```

### Returns
- **number** - The number of hunks in the blame result
```

--------------------------------

### findSystemConfigPath

Source: https://github.com/toss/es-git/blob/main/docs/reference/Config/findSystemConfigPath.md

Locates the system configuration file path. It first checks for the existence of `/etc/gitconfig`. If not found, it proceeds to look within the `%PROGRAMFILES%` directory.

```APIDOC
## findSystemConfigPath

### Description
Locates the system configuration file path. It first checks for the existence of `/etc/gitconfig`. If not found, it proceeds to look within the `%PROGRAMFILES%` directory.

### Signature
```ts
function findSystemConfigPath(): string | null;
```

### Returns
- **string | null**: The path to the system configuration file.
```

--------------------------------

### Get Blob Content

Source: https://github.com/toss/es-git/blob/main/docs/reference/Blob/Methods/content.md

Retrieves the binary content of the blob. The content is returned as a Uint8Array.

```typescript
class Blob {
  content(): Uint8Array;
}
```

--------------------------------

### Get and Iterate Stash List

Source: https://github.com/toss/es-git/blob/main/docs/reference/Repository/Methods/stashList.md

Demonstrates how to open a repository, retrieve the stash list, check if it's empty, and iterate through the stashes to log their index and message. Requires the 'es-git' library.

```typescript
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()}`);
  }
}
```

--------------------------------

### Open Repository

Source: https://github.com/toss/es-git/blob/main/docs/reference/Repository/openRepository.md

Basic usage of `openRepository` to open a repository at a given path. Ensure the path points to an existing repository.

```typescript
import { openRepository } from 'es-git';

const repo = await openRepository('/path/to/repo');
```

--------------------------------

### Get DiffFile mode

Source: https://github.com/toss/es-git/blob/main/docs/reference/Diff/DiffFile/mode.md

Call the `mode()` method on a `DiffFile` instance to retrieve its file mode.

```typescript
class DiffFile {
  mode(): FileMode;
}
```

--------------------------------

### Create a Signed Commit

Source: https://github.com/toss/es-git/blob/main/docs/usage/commit.md

This snippet shows how to create a GPG signed commit by providing a signature string during the commit process. It also demonstrates how to extract the signature information from a created commit.

```typescript
import { openRepository } from 'es-git';

const repo = await openRepository('.');
const index = repo.index();
const treeOid = index.writeTree();
const tree = repo.getTree(treeOid);

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

// Create a signed commit
const oid = repo.commit(tree, 'signed commit', {
    updateRef: 'HEAD',
    author: signature,
    committer: signature,
    parents: [repo.head().target()!],
    signature: '-----BEGIN PGP SIGNATURE-----\nVersion: GnuPG v1\n\niQEcBAABAgAGBQJTest123\n-----END PGP SIGNATURE-----'
});

// Extract signature from the commit
const signatureInfo = repo.extractSignature(oid);
console.log(signatureInfo.signature);
// {
//  signature: '-----BEGIN PGP SIGNATURE-----\nVersion: GnuPG v1\n\niQEcBAABAgAGBQJTest123\n-----END PGP SIGNATURE-----',
//  signedData: 'tree ab9abf28de846b5968a8f12156f1d5ce3f4a198e\n' +
//  'parent a01e9888e46729ef4aa68953ba19b02a7a64eb82\n' +
//  'author Seokju Na <seokju.me@toss.im> 1744517729 +0000\n' +
//  'committer Seokju Na <seokju.me@toss.im> 1744517729 +0000\n' +
//  '\n' +
//  'signed commit'
// }
```

--------------------------------

### Get Commit Time

Source: https://github.com/toss/es-git/blob/main/docs/reference/Commit/Methods/time.md

Retrieve the committer time of a commit. This method returns a Date object.

```typescript
class Commit {
  time(): Date;
}
```

--------------------------------

### es-git Performance Summary

Source: https://github.com/toss/es-git/blob/main/docs/performance.md

Summary of performance comparisons, highlighting how much faster es-git is than other libraries for specific operations. This provides a quick overview of es-git's advantages.

```text
  nodegit - index.bench.ts > open
    1.02x faster than es-git
    4.63x faster than @napi-rs/simple-git

  es-git - index.bench.ts > rev-parse
    1.12x faster than nodegit
    2.53x faster than @napi-rs/simple-git
    71.78x faster than child_process

  es-git - index.bench.ts > revwalk
    1.06x faster than nodegit
    1.29x faster than @napi-rs/simple-git
    11.29x faster than child_process

  es-git - index.bench.ts > get commit
    1.13x faster than nodegit
    3.23x faster than @napi-rs/simple-git
    96.57x faster than child_process
```

--------------------------------

### iter()

Source: https://github.com/toss/es-git/blob/main/docs/reference/Blame/Methods/iter.md

Gets all blame hunks as an iterator. This method returns a Generator that yields BlameHunk objects.

```APIDOC
## iter()

### Description
Gets all blame hunks as an iterator. This method returns a Generator that yields BlameHunk objects.

### Method
N/A (Class method)

### Endpoint
N/A (Class method)

### Returns
- **BlameHunks** (Generator) - Iterator of all blame hunks

### Examples
```ts
// Using for...of loop
for (const hunk of blame.iter()) {
  console.log(hunk.finalCommitId);
}

// Using spread operator to collect all hunks
const hunks = [...blame.iter()];
```
```