es-git 0.0.12 → 0.1.0

package/index.d.ts

@@ -8,59 +8,299 @@ export interface CommitOptions {
   /**
    * Signature for author.
    *
-   * If not provided, default signature of repository will be used.
+   * If not provided, the default signature of the repository will be used.
    * If there is no default signature set for the repository, an error will occur.
    */
   author?: SignaturePayload
   /**
    * Signature for commiter.
    *
-   * If not provided, default signature of repository will be used.
+   * If not provided, the default signature of the repository will be used.
    * If there is no default signature set for the repository, an error will occur.
    */
   committer?: SignaturePayload
   parents?: Array<string>
 }
-export const enum DiffFlags {
-  /** File(s) treated as binary data. (1 << 0) */
+/**
+ * - `ProgramData` : System-wide on Windows, for compatibility with portable git.
+ * - `System` : System-wide configuration file. (e.g. `/etc/gitconfig`)
+ * - `XDG` : XDG-compatible configuration file. (e.g. `~/.config/git/config`)
+ * - `Global` : User-specific configuration. (e.g. `~/.gitconfig`)
+ * - `Local` : Repository specific config. (e.g. `$PWD/.git/config`)
+ * - `Worktree` : Worktree specific configuration file. (e.g. `$GIT_DIR/config.worktree`)
+ * - `App` : Application specific configuration file.
+ * - `Highest` : Highest level available.
+ */
+export type ConfigLevel = 'ProgramData' | 'System' | 'XDG' | 'Global' | 'Local' | 'Worktree' | 'App' | 'Highest';
+export interface ConfigEntry {
+  /** The name of this entry. */
+  name: string
+  /** The value of this entry. If no value is defined, the value will be `null`. */
+  value?: string
+  /** The configuration level of this entry. */
+  level: ConfigLevel
+  /** Depth of includes where this variable was found */
+  includeDepth: number
+}
+/**
+ * Create a new config instance containing a single on-disk file
+ *
+ * @category Config
+ * @signature
+ * ```ts
+ * function openConfig(path: string): Config;
+ * ```
+ *
+ * @param {string} path - Path to config file.
+ * @returns Config instance representing a git configuration key/value store.
+ */
+export declare function openConfig(path: string): Config
+/**
+ * Open the global, XDG and system configuration files
+ *
+ * Utility wrapper that finds the global, XDG and system configuration
+ * files and opens them into a single prioritized config object that can
+ * be used when accessing default config data outside a repository.
+ *
+ * @category Config
+ * @signature
+ * ```ts
+ * function openDefaultConfig(): Config;
+ * ```
+ *
+ * @returns Config instance representing a git configuration key/value store.
+ */
+export declare function openDefaultConfig(): Config
+/**
+ * Locate the path to the global configuration file.
+ *
+ * The user or global configuration file is usually located in
+ * `$HOME/.gitconfig`.
+ *
+ * This method will try to guess the full path to that file, if the file
+ * exists. The returned path may be used on any method call to load
+ * the global configuration file.
+ *
+ * This method will not guess the path to the XDG compatible config file
+ * (`.config/git/config`).
+ *
+ * @category Config
+ * @signature
+ * ```ts
+ * function findGlobalConfigPath(): string | null;
+ * ```
+ *
+ * @returns The path to the global configuration file.
+ */
+export declare function findGlobalConfigPath(): string | null
+/**
+ * Locate the path to the system configuration file.
+ *
+ * If `/etc/gitconfig` doesn't exist, it will look for `%PROGRAMFILES%`.
+ *
+ * @category Config
+ * @signature
+ * ```ts
+ * function findSystemConfigPath(): string | null;
+ * ```
+ *
+ * @returns The path to the system configuration file.
+ */
+export declare function findSystemConfigPath(): string | null
+/**
+ * Locate the path to the global XDG compatible configuration file.
+ *
+ * The XDG compatible configuration file is usually located in
+ * `$HOME/.config/git/config`.
+ *
+ * @category Config
+ * @signature
+ * ```ts
+ * function findXdgConfigPath(): string | null;
+ * ```
+ *
+ * @returns The path to the XDG compatible configuration file.
+ */
+export declare function findXdgConfigPath(): string | null
+/**
+ * Parse a string as a bool.
+ *
+ * @category Config
+ * @signature
+ * ```ts
+ * function parseConfigBool(value: string): boolean;
+ * ```
+ *
+ * @param {string} value - Input value.
+ * @returns Interprets "true", "yes", "on", 1, or any non-zero number as `true`.
+ * Interprets "false", "no", "off", 0, or an empty string as `false`.
+ */
+export declare function parseConfigBool(value: string): boolean
+/**
+ * Parse a string as an i32; handles suffixes like k, M, or G, and
+ * multiplies by the appropriate power of 1024.
+ *
+ * @category Config
+ * @signature
+ * ```ts
+ * function parseConfigI32(value: string): number;
+ * ```
+ *
+ * @param {string} value - Input value.
+ * @returns Parsed i32 value.
+ */
+export declare function parseConfigI32(value: string): number
+/**
+ * Parse a string as an i64; handles suffixes like k, M, or G, and
+ * multiplies by the appropriate power of 1024.
+ *
+ * @category Config
+ * @signature
+ * ```ts
+ * function parseConfigI64(value: string): number;
+ * ```
+ *
+ * @param {string} value - Input value.
+ * @returns Parsed i64 value.
+ */
+export declare function parseConfigI64(value: string): number
+/**
+ * - `DiffFlags.Binary` : File(s) treated as binary data.
+ * - `DiffFlags.NotBinary` : File(s) treated as text data.
+ * - `DiffFlags.ValidId` : `id` value is known correct.
+ * - `DiffFlags.Exists` : File exists at this side of the delta.
+ */
+export enum DiffFlags {
   Binary = 1,
-  /** File(s) treated as text data. (1 << 1) */
   NotBinary = 2,
-  /** `id` value is known correct. (1 << 2) */
   ValidId = 4,
-  /** File exists at this side of the delta. (1 << 3) */
   Exists = 8
 }
-/** Check diff flags contains given flags. */
+/**
+ * Check diff flags contains given flags.
+ *
+ * @category Diff
+ * @signature
+ * ```ts
+ * function diffFlagsContains(source: number, target: number): boolean;
+ * ```
+ *
+ * @param {number} source - Source flags.
+ * @param {number} target - Target flags.
+ * @returns Returns `true` is source flags contains target flags.
+ *
+ * @example
+ * ```ts
+ * import { DiffDelta, DiffFlags, diffFlagsContains } from 'es-git';
+ *
+ * const delta: DiffDelta;
+ * console.assert(diffFlagsContains(delta.flags(), DiffFlags.Binary | DiffFlags.ValidId));
+ * ```
+ */
 export declare function diffFlagsContains(source: number, target: number): boolean
-/** What type of change is described by a `DiffDelta`? */
-export type DeltaType = /** No changes */
-'Unmodified' | /** Entry does not exist in old version */
-'Added' | /** Entry does not exist in new version */
-'Deleted' | /** Entry content changed between old and new */
-'Modified' | /** Entry was renamed between old and new */
-'Renamed' | /** Entry was copied from another old entry */
-'Copied' | /** Entry is ignored item in workdir */
-'Ignored' | /** Entry is untracked item in workdir */
-'Untracked' | /** Type of entry changed between old and new */
-'Typechange' | /** Entry is unreadable */
-'Unreadable' | /** Entry in the index is conflicted */
-'Conflicted';
-/** Possible output formats for diff data */
-export type DiffFormat = /** full git diff (default) */
-'Patch' | /** just the headers of the patch */
-'PatchHeader' | /** like git diff --raw */
-'Raw' | /** like git diff --name-only */
-'NameOnly' | /** like git diff --name-status */
-'NameStatus' | /** git diff as used by git patch-id */
-'PatchId';
+/**
+ * - `Unmodified` : No changes.
+ * - `Added` : Entry does not exist in an old version.
+ * - `Deleted` : Entry does not exist in a new version.
+ * - `Modified` : Entry content changed between old and new.
+ * - `Renamed` : Entry was renamed between old and new.
+ * - `Copied` : Entry was copied from another old entry.
+ * - `Ignored` : Entry is ignored item in workdir.
+ * - `Untracked` : Entry is untracked item in workdir.
+ * - `Typechange` : Type of entry changed between old and new.
+ * - `Unreadable` : Entry is unreadable.
+ * - `Conflicted` : Entry in the index is conflicted.
+ */
+export type DeltaType = 'Unmodified' | 'Added' | 'Deleted' | 'Modified' | 'Renamed' | 'Copied' | 'Ignored' | 'Untracked' | 'Typechange' | 'Unreadable' | 'Conflicted';
+/**
+ * Possible output formats for diff data.
+ *
+ * - `Patch`: Full `git diff` (default)
+ * - `PatchHeader` : Just the headers of the patch
+ * - `Raw` : Like `git diff --raw` the headers of the patch
+ * - `NameOnly` : Like `git diff --name-only`
+ * - `NameStatus` : Like `git diff --name-status`
+ * - `PatchId` : `git diff` as used by `git patch-id`
+ */
+export type DiffFormat = 'Patch' | 'PatchHeader' | 'Raw' | 'NameOnly' | 'NameStatus' | 'PatchId';
 export interface DiffPrintOptions {
   format?: DiffFormat
 }
+export interface DiffFindOptions {
+  /** Look for renames? */
+  renames?: boolean
+  /** Consider old side of modified for renames? */
+  renamesFromRewrites?: boolean
+  /** Look for copies? */
+  copies?: boolean
+  /**
+   * Consider unmodified as copy sources?
+   *
+   * For this to work correctly, use `includeUnmodified` when the initial
+   * diff is being generated.
+   */
+  copiesFromUnmodified?: boolean
+  /** Mark significant rewrites for split. */
+  rewrites?: boolean
+  /** Actually split large rewrites into delete/add pairs */
+  breakRewrites?: boolean
+  /**
+   * Find renames/copies for untracked items in working directory.
+   *
+   * For this to work correctly use the `includeUntracked` option when the
+   * initial diff is being generated.
+   */
+  forUntracked?: boolean
+  /** Turn on all finding features. */
+  all?: boolean
+  /** Measure similarity ignoring leading whitespace (default) */
+  ignoreLeadingWhitespace?: boolean
+  /** Measure similarity ignoring all whitespace */
+  ignoreWhitespace?: boolean
+  /** Measure similarity including all data */
+  dontIgnoreWhitespace?: boolean
+  /** Measure similarity only by comparing SHAs (fast and cheap) */
+  exactMatchOnly?: boolean
+  /**
+   * Do not break rewrites unless they contribute to a rename.
+   *
+   * Normally, `breakRewrites` and `rewrites` will measure the
+   * self-similarity of modified files and split the ones that have changed a
+   * lot into a delete/add pair. Then the sides of that pair will be
+   * considered candidates for rename and copy detection
+   *
+   * If you add this flag in and the split pair is not used for an actual
+   * rename or copy, then the modified record will be restored to a regular
+   * modified record instead of being split.
+   */
+  breakRewritesForRenamesOnly?: boolean
+  /**
+   * Remove any unmodified deltas after find_similar is done.
+   *
+   * Using `copiesFromUnmodified` to emulate the `--find-copies-harder`
+   * behavior requires building a diff with the `includeUnmodified` flag. If
+   * you do not want unmodified records in the final result, pas this flag to
+   * have them removed.
+   */
+  removeUnmodified?: boolean
+  /** Similarity to consider a file renamed (default 50) */
+  renameThreshold?: number
+  /** Similarity of modified to be eligible rename source (default 50) */
+  renameFromRewriteThreshold?: number
+  /** Similarity to consider a file copy (default 50) */
+  copyThreshold?: number
+  /** Similarity to split modify into delete/add pair (default 60) */
+  breakRewriteThreshold?: number
+  /**
+   * Maximum similarity sources to examine for a file (somewhat like
+   * git-diff's `-l` option or `diff.renameLimit` config)
+   *
+   * Defaults to 200
+   */
+  renameLimit?: number
+}
 /** Valid modes for index and tree entries. */
-export type FileMode = 'Unreadable' | 'Tree' | 'Blob' | /** Group writable blob. Obsolete mode kept for compatibility reasons */
-'BlobGroupWritable' | 'BlobExecutable' | 'Link' | 'Commit';
-/** Structure describing options about how the diff should be executed. */
+export type FileMode = 'Unreadable' | 'Tree' | 'Blob' | 'BlobGroupWritable' | 'BlobExecutable' | 'Link' | 'Commit';
 export interface DiffOptions {
   /** Flag indicating whether the sides of the diff will be reversed. */
   reverse?: boolean
@@ -82,7 +322,7 @@ export interface DiffOptions {
   /**
    * Event with `includeTypechange`, the tree returned generally shows a
    * deleted blob. This flag correctly labels the tree transitions as a
-   * typechange record with the `new_file`'s mode set to tree.
+   * typechange record with the `newFile`'s mode set to tree.
    *
    * Note that the tree SHA will not be available.
    */
@@ -226,10 +466,8 @@ export interface IndexEntry {
    * (`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][git-index-docs]. Note that libgit2 will take care of
-   * handling the prefix compression mentioned there.
-   *
-   * [git-index-docs]: https://github.com/git/git/blob/a08a83db2bf27f015bec9a435f6d73e223c21c5e/Documentation/technical/index-format.txt#L107-L124
+   * [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.
    */
   path: Buffer
 }
@@ -272,12 +510,14 @@ export interface IndexAddAllOptions {
    */
   onMatch?: (args: IndexOnMatchCallbackArgs) => number
 }
-export type IndexStage = /** Match any index stage. */
-'Any' | /** A normal staged file in the index. */
-'Normal' | /** The ancestor side of a conflict. */
-'Ancestor' | /** The "ours" side of a conflict. */
-'Ours' | /** The "theirs" side of a conflict. */
-'Theirs';
+/**
+ * - `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.
+ */
+export type IndexStage = 'Any' | 'Normal' | 'Ancestor' | 'Ours' | 'Theirs';
 export interface IndexRemoveOptions {
   stage?: IndexStage
 }
@@ -298,93 +538,142 @@ export interface IndexUpdateAllOptions {
    */
   onMatch?: (args: IndexOnMatchCallbackArgs) => number
 }
-/** An enumeration all possible kinds objects may have. */
-export const enum ObjectType {
-  /** Any kind of git object */
-  Any = 0,
-  /** An object which corresponds to a git commit */
-  Commit = 1,
-  /** An object which corresponds to a git tree */
-  Tree = 2,
-  /** An object which corresponds to a git blob */
-  Blob = 3,
-  /** An object which corresponds to a git tag */
-  Tag = 4
-}
+/**
+ * - `Any` : Any kind of git object
+ * - `Commit` : An object which corresponds to a git commit
+ * - `Tree` : An object which corresponds to a git tree
+ * - `Blob` : An object which corresponds to a git blob
+ * - `Tag` : An object which corresponds to a git tag
+ */
+export type ObjectType = 'Any' | 'Commit' | 'Tree' | 'Blob' | 'Tag';
 /**
  * Check if given string is valid Oid.
  *
- * Returns `false` if the string is empty, is longer than 40 hex
+ * @category Oid
+ * @signature
+ * ```ts
+ * function isValidOid(value: string): boolean;
+ * ```
+ *
+ * @param {string} value - String to check if is valid Oid.
+ * @returns Returns `false` if the string is empty, is longer than 40 hex
  * characters, or contains any non-hex characters.
  */
 export declare function isValidOid(value: string): boolean
-/** Test if this Oid is all zeros. */
+/**
+ * Test if this Oid is all zeros.
+ *
+ * @category Oid
+ * @signature
+ * ```ts
+ * function isZeroOid(value: string): boolean;
+ * ```
+ *
+ * @param {string} value - String to check if is zero Oid.
+ * @returns Returns `true` if the string is zero Oid.
+ * @example
+ * ```ts
+ * import { zeroOid, isZeroOid } from 'es-git';
+ *
+ * console.assert(isZeroOid(zeroOid());
+ * ```
+ */
 export declare function isZeroOid(value: string): boolean
-/** Creates an all zero Oid structure. */
+/**
+ * Creates an all zero Oid structure.
+ *
+ * @category Oid
+ * @signature
+ * ```ts
+ * function zeroOid(): string;
+ * ```
+ *
+ * @returns Zero Oid string.
+ */
 export declare function zeroOid(): string
 /**
  * Hashes the provided data as an object of the provided type, and returns
  * an Oid corresponding to the result. This does not store the object
  * inside any object database or repository.
+ *
+ * @category Oid
+ * @signature
+ * ```ts
+ * function hashObjectOid(objType: ObjectType, bytes: Buffer): string;
+ * ```
+ *
+ * @param {ObjectType} objType - Git object type.
+ * @param {Buffer} bytes - Data to hashed.
+ * @returns Hashed string.
  */
 export declare function hashObjectOid(objType: ObjectType, bytes: Buffer): string
 /**
  * Hashes the content of the provided file as an object of the provided type,
  * and returns an Oid corresponding to the result. This does not store the object
  * inside any object database or repository.
+ *
+ * @category Oid
+ * @signature
+ * ```ts
+ * function hashFileOid(objType: ObjectType, path: string): string;
+ * ```
+ *
+ * @param {ObjectType} objType - Git object type.
+ * @param {string} path - File path to make hash.
+ * @returns Hashed string.
  */
 export declare function hashFileOid(objType: ObjectType, path: string): string
-/** An enumeration of all possible kinds of references. */
-export type ReferenceType = /** A reference which points at an object id. */
-'Direct' | /** A reference which points at another reference. */
-'Symbolic';
+/**
+ * - `Direct` : A reference which points at an object id.
+ * - `Symbolic` : A reference which points at another reference.
+ */
+export type ReferenceType = 'Direct' | 'Symbolic';
 /**
  * Ensure the reference name is well-formed.
  *
- * Validation is performed as if [`ReferenceFormat::ALLOW_ONELEVEL`]
- * was given to [`Reference::normalize_name`]. No normalization is
- * performed, however.
+ * Validation is performed as if `ReferenceFormat.AllowOnelevel`
+ * was given to `normalizeReferenceName`  No normalization is performed, however.
+ *
+ * @category Reference
+ * @signature
+ * ```ts
+ * function isValidReferenceName(refname: string): boolean;
+ * ```
+ *
+ * @param {string} refname - Reference name to check if it is valid.
+ * @returns Returns `true` if reference name is valid.
  *
  * @example
  * ```ts
- * import { isReferenceNameValid } from 'es-git';
+ * import { isValidReferenceName } from 'es-git';
  *
- * console.assert(isReferenceNameValid("HEAD"));
- * console.assert(isReferenceNameValid("refs/heads/main"));
+ * console.assert(isValidReferenceName("HEAD"));
+ * console.assert(isValidReferenceName("refs/heads/main"));
  *
  * // But:
- * console.assert(!isReferenceNameValid("main"));
- * console.assert(!isReferenceNameValid("refs/heads/*"));
- * console.assert(!isReferenceNameValid("foo//bar"));
+ * console.assert(!isValidReferenceName("main"));
+ * console.assert(!isValidReferenceName("refs/heads/*"));
+ * console.assert(!isValidReferenceName("foo//bar"));
  * ```
  */
-export declare function isReferenceNameValid(refname: string): boolean
-/** Options for normalize reference name. */
-export const enum ReferenceFormat {
-  /** No particular normalization. */
+export declare function isValidReferenceName(refname: string): boolean
+/**
+ * - `ReferenceFormat.Normal` : No particular normalization.
+ * - `ReferenceFormat.AllowOnelevel` : Control whether one-level refname are accepted
+ * (i.e., refnames that do not contain multiple `/`-separated components). Those are
+ * expected to be written only using uppercase letters and underscore
+ * (e.g. `HEAD`, `FETCH_HEAD`).
+ * - `ReferenceFormat.RefspecPattern` : Interpret the provided name as a reference pattern
+ * for a refspec (as used with remote repositories). If this option is enabled, the name
+ * is allowed to contain a single `*` in place of a full pathname
+ * components (e.g., `foo/*\/bar` but not `foo/bar*`).
+ * - `ReferenceFormat.RefspecShorthand` : Interpret the name as part of a refspec in shorthand
+ * form so the `AllowOnelevel` naming rules aren't enforced and `main` becomes a valid name.
+ */
+export enum ReferenceFormat {
   Normal = 0,
-  /**
-   * Control whether one-level refname are accepted (i.e., refnames that
-   * do not contain multiple `/`-separated components). Those are
-   * expected to be written only using uppercase letters and underscore
-   * (e.g. `HEAD`, `FETCH_HEAD`).
-   * (1 << 0)
-   */
   AllowOnelevel = 1,
-  /**
-   * Interpret the provided name as a reference pattern for a refspec (as
-   * used with remote repositories). If this option is enabled, the name
-   * is allowed to contain a single `*` in place of a full pathname
-   * components (e.g., `foo/*\/bar` but not `foo/bar*`).
-   * (1 << 1)
-   */
   RefspecPattern = 2,
-  /**
-   * Interpret the name as part of a refspec in shorthand form so the
-   * `AllowOnelevel` naming rules aren't enforced and `main` becomes a
-   * valid name.
-   * (1 << 2)
-   */
   RefspecShorthand = 4
 }
 /**
@@ -409,7 +698,16 @@ export const enum ReferenceFormat {
  *    the characters '~', '^', ':', '\\', '?', '[', and '*', and the
  *    sequences ".." and "@{" which have special meaning to revparse.
  *
- * If the reference passes validation, it is returned in normalized form,
+ * @category Reference
+ * @signature
+ * ```ts
+ * function normalizeReferenceName(refname: string, format?: number): string | null;
+ * ```
+ *
+ * @param {string} refname - Reference name to normalize.
+ * @param {number} [format] - Reference format flags which used for normalize.
+ *
+ * @returns If the reference passes validation, it is returned in normalized form,
  * otherwise an `null` is returned.
  *
  * @example
@@ -417,7 +715,7 @@ export const enum ReferenceFormat {
  * import { normalizeReferenceName, ReferenceFormat } from 'es-git';
  *
  * console.assert(
- *   normalizeReferenceName('foo//bar"),
+ *   normalizeReferenceName('foo//bar'),
  *   'foo/bar'
  * );
  * console.assert(
@@ -452,81 +750,83 @@ export interface RenameReferenceOptions {
   force?: boolean
   logMessage?: string
 }
+/**
+ * - `Fetch` : Fetch direction.
+ * - `Push` : Push direction.
+ */
 export type Direction = 'Fetch' | 'Push';
-export interface RefspecObject {
+/**
+ * A data object to represent a git [refspec][1].
+ *
+ * Refspecs are currently mainly accessed/created through a `Remote`.
+ *
+ * [1]: https://git-scm.com/book/en/Git-Internals-The-Refspec
+ */
+export interface Refspec {
   direction: Direction
+  /** The source specifier. */
   src: string
+  /** The destination specifier. */
   dst: string
+  /** Force update setting. */
   force: boolean
 }
-/** Options which can be specified to various fetch operations. */
-export interface ProxyOptions {
-  /**
-   * Try to auto-detect the proxy from the git configuration.
-   *
-   * Note that this will override `url` specified before.
-   */
-  auto?: boolean
-  /**
-   * Specify the exact URL of the proxy to use.
-   *
-   * Note that this will override `auto` specified before.
-   */
-  url?: string
-}
-export type FetchPrune = /** Use the setting from the configuration */
-'Unspecified' | /** Force pruning on */
-'On' | /** Force pruning off */
-'Off';
-export type Credential = /** Create a "default" credential usable for Negotiate mechanisms like NTLM or Kerberos authentication.*/
-{
+/** A interface to represent git credentials in libgit2. */
+export type Credential = {
  type: 'Default';
-} | /** Create a new ssh key credential object used for querying an ssh-agent.
-The username specified is the username to authenticate.*/
-{
+} | {
  type: 'SSHKeyFromAgent';
  username?: string;
-} | /** Create a new passphrase-protected ssh key credential object.*/
-{
+} | {
  type: 'SSHKeyFromPath';
  username?: string;
  publicKeyPath?: string;
  privateKeyPath: string;
  passphrase?: string;
-} | /** Create a new ssh key credential object reading the keys from memory.*/
-{
+} | {
  type: 'SSHKey';
  username?: string;
  publicKey?: string;
  privateKey: string;
  passphrase?: string;
-} | /** Create a new plain-text username and password credential object.*/
-{
+} | {
  type: 'Plain';
  username?: string;
  password: string;
 };
-/** Automatic tag following options. */
-export type AutotagOption = /** Use the setting from the remote's configuration */
-'Unspecified' | /** Ask the server for tags pointing to objects we're already downloading */
-'Auto' | /** Don't ask for any tags beyond the refspecs */
-'None' | /** Ask for all the tags */
-'All';
+export interface ProxyOptions {
+  /**
+   * Try to auto-detect the proxy from the git configuration.
+   *
+   * Note that this will override `url` specified before.
+   */
+  auto?: boolean
+  /**
+   * Specify the exact URL of the proxy to use.
+   *
+   * Note that this will override `auto` specified before.
+   */
+  url?: string
+}
 /**
- * Remote redirection settings; whether redirects to another host are
- * permitted.
- *
- * By default, git will follow a redirect on the initial request
- * (`/info/refs`), but not subsequent requests.
+ * - `Unspecified` : Use the setting from the configuration.
+ * - `On` : Force pruning on.
+ * - `Off` : Force pruning off
+ */
+export type FetchPrune = 'Unspecified' | 'On' | 'Off';
+/**
+ * - `Unspecified` : Use the setting from the remote's configuration
+ * - `Auto` : Ask the server for tags pointing to objects we're already downloading
+ * - `None` : Don't ask for any tags beyond the refspecs
+ * - `All` : Ask for all the tags
  */
-export type RemoteRedirect = /** Do not follow any off-site redirects at any stage of the fetch or push. */
-'None' | /**
- * Allow off-site redirects only upon the initial request. This is the
- * default.
+export type AutotagOption = 'Unspecified' | 'Auto' | 'None' | 'All';
+/**
+ * - `None` : Do not follow any off-site redirects at any stage of the fetch or push.
+ * - `Initial` : Allow off-site redirects only upon the initial request. This is the default.
+ * - `All` : Allow redirects at any stage in the fetch or push.
  */
-'Initial' | /** Allow redirects at any stage in the fetch or push. */
-'All';
-/** Options which can be specified to various fetch operations. */
+export type RemoteRedirect = 'None' | 'Initial' | 'All';
 export interface FetchOptions {
   credential?: Credential
   /** Set the proxy options to use for the fetch operation. */
@@ -587,67 +887,365 @@ export interface CreateRemoteOptions {
   fetchRefspec?: string
 }
 export interface FetchRemoteOptions {
+  /** Options which can be specified to various fetch operations. */
   fetch?: FetchOptions
   reflogMsg?: string
 }
 export interface PruneOptions {
   credential?: Credential
 }
-/** A listing of the possible states that a repository can be in. */
+/**
+ * Available states are `Clean`, `Merge`, `Revert`, `RevertSequence`, `CherryPick`,
+ * `CherryPickSequence`, `Bisect`, `Rebase`, `RebaseInteractive`, `RebaseMerge`,
+ * `ApplyMailbox`, `ApplyMailboxOrRebase`.
+ */
 export type RepositoryState = 'Clean' | 'Merge' | 'Revert' | 'RevertSequence' | 'CherryPick' | 'CherryPickSequence' | 'Bisect' | 'Rebase' | 'RebaseInteractive' | 'RebaseMerge' | 'ApplyMailbox' | 'ApplyMailboxOrRebase';
+/** Mode options for `RepositoryInitOptions`. */
+export enum RepositoryInitMode {
+  /** Use permissions configured by umask (default) */
+  SharedUnmask = 0,
+  /**
+   * Use `--shared=group` behavior, chmod'ing the new repo to be
+   * group writable and "g+sx" for sticky group assignment.
+   */
+  SharedGroup = 1533,
+  /** Use `--shared=all` behavior, adding world readability. */
+  SharedAll = 1535
+}
 export interface RepositoryInitOptions {
+  /**
+   * Create a bare repository with no working directory.
+   *
+   * Defaults to `false`.
+   */
   bare?: boolean
+  /**
+   * Return an error if the repository path appears to already be a git
+   * repository.
+   *
+   * Defaults to `false`.
+   */
+  noReinit?: boolean
+  /**
+   * 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`.
+   */
+  noDotgitDir?: boolean
+  /**
+   * Make the repo path (and workdir path) as needed. The ".git" directory
+   * will always be created regardless of this flag.
+   *
+   * Defaults to `true`.
+   */
+  mkdir?: boolean
+  /**
+   * 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
+  /** Set to one of the `RepositoryInit` constants, or a custom value. */
+  mode?: number
+  /**
+   * 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`.
+   */
+  externalTemplate?: boolean
+  /**
+   * 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.
+   */
+  templatePath?: string
+  /**
+   * 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.
+   */
+  workdirPath?: string
+  /**
+   * If set, this will be used to initialize the "description" file in the
+   * repository instead of using the template content.
+   */
+  description?: string
+  /**
+   * 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.
+   */
   initialHead?: string
+  /**
+   * If set, then after the rest of the repository initialization is
+   * completed an `origin` remote will be added pointing to this URL.
+   */
   originUrl?: string
 }
 export interface RepositoryOpenOptions {
-  flags: number
+  /**
+   * 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.
+   */
+  noSearch?: boolean
+  /**
+   * If this option is `true`, the search through parent directories will not cross
+   * a filesystem boundary (detected when the stat st_dev field changes).
+   */
+  crossFs?: boolean
+  /**
+   * 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.
+   */
+  bare?: boolean
+  /** If this options is `true`, don't try appending `/.git` to `path`. */
+  noDotgit?: boolean
+  /**
+   * 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`.
+   */
+  fromEnv?: boolean
+  /**
+   * ceiling_dirs specifies a list of paths that the search through parent
+   * directories will stop before entering.
+   */
   ceilingDirs?: Array<string>
 }
-export const enum RepositoryOpenFlags {
-  /** Only open the specified path; don't walk upward searching. (1 << 0) */
-  NoSearch = 1,
-  /** Search across filesystem boundaries. (1 << 1) */
-  CrossFS = 2,
-  /** Force opening as a bare repository, and defer loading its config. (1 << 2) */
-  Bare = 4,
-  /** Don't try appending `/.git` to the specified repository path. (1 << 3) */
-  NoDotGit = 8,
-  /** Respect environment variables like `$GIT_DIR`. (1 << 4) */
-  FromEnv = 16
-}
 export interface RepositoryCloneOptions {
+  /**
+   * Indicate whether the repository will be cloned as a bare repository or
+   * not.
+   */
+  bare?: boolean
+  /**
+   * Specify the name of the branch to check out after the clone.
+   *
+   * If not specified, the remote's default branch will be used.
+   */
+  branch?: string
+  /**
+   * Clone a remote repository, initialize and update its submodules
+   * recursively.
+   *
+   * This is similar to `git clone --recursive`.
+   */
   recursive?: boolean
+  /** Options which can be specified to various fetch operations. */
   fetch?: FetchOptions
 }
-/** Creates a new repository in the specified folder. */
-export declare function initRepository(path: string, options?: RepositoryInitOptions | undefined | null, signal?: AbortSignal | undefined | null): Promise<Repository>
-/** Attempt to open an already-existing repository at `path`. */
-export declare function openRepository(path: string, options?: RepositoryOpenOptions | undefined | null, signal?: AbortSignal | undefined | null): Promise<Repository>
 /**
- * Attempt to open an already-existing repository at or above `path`
+ * Creates a new repository in the specified folder.
  *
- * This starts at `path` and looks up the filesystem hierarchy
- * until it finds a repository.
- */
-export declare function discoverRepository(path: string, signal?: AbortSignal | undefined | null): Promise<Repository>
-/**
- * Clone a remote repository.
+ * @category Repository
+ * @signature
+ * ```ts
+ * function initRepository(
+ *   path: string,
+ *   options?: RepositoryInitOptions,
+ *   signal?: AbortSignal,
+ * ): Promise<Repository>;
+ * ```
+ *
+ * @param {string} path - Directory path to create new repository.
+ * @param {RepositoryInitOptions} [options] - Options which can be used to configure
+ * how a repository is initialized.
+ * @param {AbortSignal} [signal] - Abort signal.
+ *
+ * @returns A new repository.
+ *
+ * @example
+ *
+ * Basic example.
+ *
+ * ```ts
+ * import { initRepository } from 'es-git';
+ *
+ * const repo = await iniRepository('/path/to/repo');
+ * ```
+ *
+ * Create bare repository.
+ *
+ * ```ts
+ * import { initRepository } from 'es-git';
+ *
+ * const repo = await iniRepository('/path/to/repo.git', {
+ *   bare: true,
+ * });
+ * ```
+ */
+export declare function initRepository(path: string, options?: RepositoryInitOptions | undefined | null, signal?: AbortSignal | undefined | null): Promise<Repository>
+/**
+ * Attempt to open an already-existing repository at `path`.
+ *
+ * @category Repository
+ * @signature
+ * ```ts
+ * function openRepository(
+ *   path: string,
+ *   options?: RepositoryOpenOptions,
+ *   signal?: AbortSignal,
+ * ): Promise<Repository>;
+ * ```
+ *
+ * @param {string} path - Directory path to repository already-existing.
+ * @param {RepositoryOpenOptions} [options] - Options which can be used to configure
+ * how a repository is initialized.
+ * @param {AbortSignal} [signal] - Abort signal.
+ *
+ * @returns Opened repository.
+ *
+ * @example
+ *
+ * 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,
+ * });
+ * ```
+ */
+export declare function openRepository(path: string, options?: RepositoryOpenOptions | undefined | null, signal?: AbortSignal | undefined | null): Promise<Repository>
+/**
+ * Attempt to open an already-existing repository at or above `path`.
+ *
+ * This starts at `path` and looks up the filesystem hierarchy
+ * until it finds a repository.
+ *
+ * @category Repository
+ * @signature
+ * ```ts
+ * function discoverRepository(path: string, signal?: AbortSignal): Promise<Repository>;
+ * ```
+ *
+ * @param {string} path - Directory path to discover repository.
+ * @param {AbortSignal} [signal] - Abort signal.
+ *
+ * @returns Git repository.
+ */
+export declare function discoverRepository(path: string, signal?: AbortSignal | undefined | null): Promise<Repository>
+/**
+ * Clone a remote repository.
  *
  * This will use the options configured so far to clone the specified URL
  * into the specified local path.
+ *
+ * @category Repository
+ *
+ * @signature
+ * ```ts
+ * function cloneRepository(
+ *   url: string,
+ *   path: string,
+ *   options?: RepositoryCloneOptions | null,
+ *   signal?: AbortSignal | null
+ * ): Promise<Repository>;
+ * ```
+ *
+ * @param {string} url - Remote URL for repository.
+ * @param {string} path - Local path to clone repository.
+ * @param {RepositoryCloneOptions|undefined|null} [options] - Clone options for repository.
+ * @param {AbortSignal|undefined|null} [signal] - Abort signal.
+ * @returns Repository instance
+ *
+ * @example
+ *
+ * Clone repository using `https://` protocol.
+ *
+ * ```ts
+ * import { cloneRepository } from 'es-git';
+ *
+ * const repo = await cloneRepository(
+ *   'https://github.com/toss/es-git',
+ *   '/path/to/clone',
+ * );
+ * ```
+ *
+ * Clone repository using `git://` protocol.
+ *
+ * ```ts
+ * import { cloneRepository } from 'es-git';
+ *
+ * const repo = await cloneRepository(
+ *   'git@github.com:toss/es-git',
+ *   '/path/to/clone',
+ * );
+ * ```
+ *
+ * Clone repository with authentication.
+ *
+ * ```ts
+ * import { cloneRepository } from 'es-git';
+ *
+ * // Authenticate using ssh-agent
+ * const repo = await cloneRepository('git@github.com:toss/es-git', '.', {
+ *   fetch: {
+ *     credential: {
+ *       type: 'SSHKeyFromAgent',
+ *     },
+ *   },
+ * });
+ * ```
  */
 export declare function cloneRepository(url: string, path: string, options?: RepositoryCloneOptions | undefined | null, signal?: AbortSignal | undefined | null): Promise<Repository>
-/** Flags for the Revspec. */
-export const enum RevparseMode {
-  /** The spec targeted a single object (1 << 0) */
+/**
+ * Flags for the revparse.
+ * - `Single` : The spec targeted a single object.
+ * - `Range` : The spec targeted a range of commits.
+ * - `MergeBase` : The spec used the `...` operator, which invokes special semantics.
+ */
+export enum RevparseMode {
   Single = 1,
-  /** The spec targeted a range of commits (1 << 1) */
   Range = 2,
-  /** The spec used the `...` operator, which invokes special semantics. (1 << 2) */
   MergeBase = 4
 }
-/** Check revparse mode contains specific flags. */
+/**
+ * Check revparse mode contains specific flags.
+ *
+ * @category Revparse
+ * @signature
+ * ```ts
+ * function revparseModeContains(source: number, target: number): boolean;
+ * ```
+ *
+ * @param {number} source - Source flags.
+ * @param {number} target - Target flags.
+ * @returns Returns `true` is source flags contains target flags.
+ *
+ * @example
+ * ```ts
+ * import { openRepository, revparseModeContains, RevparseMode } from 'es-git';
+ *
+ * const repo = await openRepository('.');
+ * const spec = repo.revparse('main..other');
+ *
+ * console.assert(revparseModeContains(spec.mode, RevparseMode.Range));
+ * ```
+ */
 export declare function revparseModeContains(source: number, target: number): boolean
 /** A revspec represents a range of revisions within a repository. */
 export interface Revspec {
@@ -658,42 +1256,15 @@ export interface Revspec {
   /** Returns the intent of the revspec. */
   mode: number
 }
-/** Orderings that may be specified for Revwalk iteration. */
-export const enum RevwalkSort {
-  /**
-   * Sort the repository contents in no particular ordering.
-   *
-   * This sorting is arbitrary, implementation-specific, and subject to
-   * change at any time. This is the default sorting for new walkers.
-   */
+export enum RevwalkSort {
   None = 0,
-  /**
-   * Sort the repository contents in topological order (children before
-   * parents).
-   *
-   * This sorting mode can be combined with time sorting.
-   * (1 << 0)
-   */
   Topological = 1,
-  /**
-   * Sort the repository contents by commit time.
-   *
-   * This sorting mode can be combined with topological sorting.
-   * (1 << 1)
-   */
   Time = 2,
-  /**
-   * Iterate through the repository contents in reverse order.
-   *
-   * This sorting mode can be combined with any others.
-   * (1 << 2)
-   */
   Reverse = 4
 }
 /**
  * A Signature is used to indicate authorship of various actions throughout the
  * library.
- *
  * Signatures contain a name, email, and timestamp.
  */
 export interface Signature {
@@ -710,7 +1281,35 @@ export interface SignatureTimeOptions {
   /** Timezone offset, in minutes */
   offset?: number
 }
-/** Create a new action signature. */
+/**
+ * Create a new action signature.
+ *
+ * @category Signature
+ * @signature
+ * ```ts
+ * function createSignature(
+ *   name: string,
+ *   email: string,
+ *   timeOptions?: SignatureTimeOptions,
+ * ): Signature;
+ * ```
+ *
+ * @param {string} name - Name on the signature.
+ * @param {string} email - Email on the signature.
+ * @param {SignatureTimeOptions} [timeOptions] - Time options for signature.
+ *
+ * @returns
+ *
+ * @example
+ * ```ts
+ * import { createSignature } from 'es-git';
+ *
+ * const author = createSignature(
+ *   'Seokju Na',
+ *   'seokju.me@toss.im',
+ * );
+ * ```
+ */
 export declare function createSignature(name: string, email: string, timeOptions?: SignatureTimeOptions | undefined | null): Signature
 export interface SignaturePayload {
   /** Name on the signature. */
@@ -723,6 +1322,15 @@ export interface SignaturePayload {
  * Determine whether a tag name is valid, meaning that (when prefixed with refs/tags/) that
  * it is a valid reference name, and that any additional tag name restrictions are imposed
  * (eg, it cannot start with a -).
+ *
+ * @category Tag
+ * @signature
+ * ```ts
+ * function isValidTagName(tagName: string): boolean;
+ * ```
+ *
+ * @param {string} tagName - Tag name to check if it is valid.
+ * @returns Returns `true` if tag name is valid.
  */
 export declare function isValidTagName(tagName: string): boolean
 export interface CreateTagOptions {
@@ -733,6 +1341,7 @@ export interface CreateTagOptions {
    * If there is no default signature set for the repository, an error will occur.
    */
   tagger?: SignaturePayload
+  /** If `force` is true and a reference already exists with the given name, it'll be replaced. */
   force?: boolean
 }
 export interface CreateAnnotationTagOptions {
@@ -745,19 +1354,126 @@ export interface CreateAnnotationTagOptions {
   tagger?: SignaturePayload
 }
 export interface CreateLightweightTagOptions {
+  /** If `force` is true and a reference already exists with the given name, it'll be replaced. */
   force?: boolean
 }
+/**
+ * - `PreOrder` : Runs the traversal in pre-order.
+ * - `PostOrder` : Runs the traversal in post-order.
+ */
 export type TreeWalkMode = 'PreOrder' | 'PostOrder';
 /**
- * A structure to represent a git commit
- * @hideconstructor
+ * A class to represent a git [blob][1].
+ * [1]: https://git-scm.com/book/en/Git-Internals-Git-Objects
  */
+export declare class Blob {
+  /**
+   * Get the id (SHA1) of a repository blob.
+   *
+   * @category Blob/Methods
+   *
+   * @signature
+   * ```ts
+   * class Blob {
+   *   id(): string;
+   * }
+   * ```
+   *
+   * @returns ID(SHA1) of a repository blob.
+   */
+  id(): string
+  /**
+   * Determine if the blob content is most certainly binary or not.
+   *
+   * @category Blob/Methods
+   *
+   * @signature
+   * ```ts
+   * class Blob {
+   *   isBinary(): boolean;
+   * }
+   * ```
+   *
+   * @returns `true` if blob content is binary.
+   */
+  isBinary(): boolean
+  /**
+   * Get the content of this blob.
+   *
+   * @category Blob/Methods
+   *
+   * @signature
+   * ```ts
+   * class Blob {
+   *   content(): Uint8Array;
+   * }
+   * ```
+   *
+   * @returns Content of this blob.
+   */
+  content(): Uint8Array
+  /**
+   * Get the size in bytes of the contents of this blob.
+   *
+   * @category Blob/Methods
+   *
+   * @signature
+   * ```ts
+   * class Blob {
+   *   size(): bigint;
+   * }
+   * ```
+   *
+   * @returns Size in bytes of the contents of this blob.
+   */
+  size(): bigint
+}
+/** A class to represent a git commit. */
 export declare class Commit {
-  /** Get the id (SHA1) of a repository commit */
+  /**
+   * Get the id (SHA1) of a repository commit
+   *
+   * @category Commit/Methods
+   *
+   * @signature
+   * ```ts
+   * class Commit {
+   *   id(): string;
+   * }
+   * ```
+   *
+   * @returns ID(SHA1) of a repository commit.
+   */
   id(): string
-  /** Get the author of this commit. */
+  /**
+   * Get the author of this commit.
+   *
+   * @category Commit/Methods
+   *
+   * @signature
+   * ```ts
+   * class Commit {
+   *   author(): Signature;
+   * }
+   * ```
+   *
+   * @returns Author signature of this commit.
+   */
   author(): Signature
-  /** Get the committer of this commit. */
+  /**
+   * Get the committer of this commit.
+   *
+   * @category Commit/Methods
+   *
+   * @signature
+   * ```ts
+   * class Commit {
+   *   committer(): Signature;
+   * }
+   * ```
+   *
+   * @returns Committer signature of this commit.
+   */
   committer(): Signature
   /**
    * Get the full message of a commit.
@@ -765,7 +1481,19 @@ export declare class Commit {
    * The returned message will be slightly prettified by removing any
    * potential leading newlines.
    *
-   * Throws error if the message is not valid utf-8
+   * Throws error if the message is not valid utf-8.
+   *
+   * @category Commit/Methods
+   *
+   * @signature
+   * ```ts
+   * class Commit {
+   *   message(): string;
+   * }
+   * ```
+   *
+   * @returns Full message of this commit.
+   * @throws If the message is not valid utf-8.
    */
   message(): string
   /**
@@ -775,6 +1503,18 @@ export declare class Commit {
    * paragraph of the message with whitespace trimmed and squashed.
    *
    * Throws error if the summary is not valid utf-8.
+   *
+   * @category Commit/Methods
+   *
+   * @signature
+   * ```ts
+   * class Commit {
+   *   summary(): string;
+   * }
+   * ```
+   *
+   * @returns Short summary of this commit message.
+   * @throws If the summary is not valid utf-8.
    */
   summary(): string | null
   /**
@@ -785,29 +1525,504 @@ export declare class Commit {
    * are trimmed.
    *
    * Throws error if the summary is not valid utf-8.
+   *
+   * @category Commit/Methods
+   *
+   * @signature
+   * ```ts
+   * class Commit {
+   *   body(): string;
+   * }
+   * ```
+   *
+   * @returns Long body of this commit message.
+   * @throws If the body is not valid utf-8.
    */
   body(): string | null
   /**
    * Get the commit time (i.e. committer time) of a commit.
    *
-   * The first element of the tuple is the time, in seconds, since the epoch.
-   * The second element is the offset, in minutes, of the time zone of the
-   * committer's preferred time zone.
+   * @category Commit/Methods
+   *
+   * @signature
+   * ```ts
+   * class Commit {
+   *   time(): Date;
+   * }
+   * ```
+   *
+   * @returns Commit time of a commit.
    */
   time(): Date
-  /** Get the tree pointed to by a commit. */
+  /**
+   * Get the tree pointed to by a commit.
+   *
+   * @category Commit/Methods
+   *
+   * @signature
+   * ```ts
+   * class Commit {
+   *   tree(): Tree;
+   * }
+   * ```
+   *
+   * @returns Tree pointed to by a commit.
+   */
   tree(): Tree
-  /** Casts this Commit to be usable as an `GitObject` */
+  /**
+   * Casts this Commit to be usable as an `GitObject`.
+   *
+   * @category Commit/Methods
+   *
+   * @signature
+   * ```ts
+   * class Commit {
+   *   asObject(): GitObject;
+   * }
+   * ```
+   *
+   * @returns `GitObject` that casted from this commit.
+   */
   asObject(): GitObject
 }
+/** An iterator over the `ConfigEntry` values of a config. */
+export declare class ConfigEntries {
+  [Symbol.iterator](): Iterator<ConfigEntry, void, void>
+}
+export declare class Config {
+  /**
+   * Delete a config variable from the config file with the highest level
+   * (usually the local one).
+   *
+   * @category Config/Methods
+   * @signature
+   * ```ts
+   * class Config {
+   *   remove(name: string): void;
+   * }
+   * ```
+   *
+   * @param {string} name - The name of config entry.
+   */
+  remove(name: string): void
+  /**
+   * Remove multivar config variables in the config file with the highest level (usually the
+   * local one).
+   *
+   * @category Config/Methods
+   * @signature
+   * ```ts
+   * class Config {
+   *   removeMultivar(name: string, regexp: string): void;
+   * }
+   * ```
+   *
+   * @param {string} name - The name of config entry.
+   * @param {string} regexp - The regular expression is applied case-sensitively on the value.
+   */
+  removeMultivar(name: string, regexp: string): void
+  /**
+   * Get the value of a boolean 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.
+   *
+   * @category Config/Methods
+   * @signature
+   * ```ts
+   * class Config {
+   *   getBool(name: string): boolean;
+   * }
+   * ```
+   *
+   * @param {string} name - The name of config entry.
+   * @returns The value of a boolean config variable.
+   */
+  getBool(name: string): boolean
+  /**
+   * Find the value of a boolean 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.
+   *
+   * @category Config/Methods
+   * @signature
+   * ```ts
+   * class Config {
+   *   findBool(name: string): boolean | null;
+   * }
+   * ```
+   *
+   * @param {string} name - The name of config entry.
+   * @returns The value of a boolean config variable.
+   */
+  findBool(name: string): boolean | null
+  /**
+   * 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.
+   *
+   * @category Config/Methods
+   * @signature
+   * ```ts
+   * class Config {
+   *   getI32(name: string): number;
+   * }
+   * ```
+   *
+   * @param {string} name - The name of config entry.
+   * @returns The value of an integer config variable.
+   */
+  getI32(name: string): number
+  /**
+   * Find 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.
+   *
+   * @category Config/Methods
+   * @signature
+   * ```ts
+   * class Config {
+   *   findI32(name: string): number | null;
+   * }
+   * ```
+   *
+   * @param {string} name - The name of config entry.
+   * @returns The value of an integer config variable.
+   */
+  findI32(name: string): number | null
+  /**
+   * 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.
+   *
+   * @category Config/Methods
+   * @signature
+   * ```ts
+   * class Config {
+   *   getI64(name: string): number;
+   * }
+   * ```
+   *
+   * @param {string} name - The name of config entry.
+   * @returns The value of an integer config variable.
+   */
+  getI64(name: string): number
+  /**
+   * Find 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.
+   *
+   * @category Config/Methods
+   * @signature
+   * ```ts
+   * class Config {
+   *   findI64(name: string): number | null;
+   * }
+   * ```
+   *
+   * @param {string} name - The name of config entry.
+   * @returns The value of an integer config variable.
+   */
+  findI64(name: string): number | null
+  /**
+   * Get the value of a string config variable as a byte slice.
+   *
+   * @category Config/Methods
+   * @signature
+   * ```ts
+   * class Config {
+   *   getBytes(name: string): Uint8Array;
+   * }
+   * ```
+   *
+   * @param {string} name - The name of config entry.
+   * @returns The value of a string config variable as a byte slice.
+   */
+  getBytes(name: string): Uint8Array
+  /**
+   * Find the value of a string config variable as a byte slice.
+   *
+   * @category Config/Methods
+   * @signature
+   * ```ts
+   * class Config {
+   *   findBytes(name: string): Uint8Array | null;
+   * }
+   * ```
+   *
+   * @param {string} name - The name of config entry.
+   * @returns The value of a string config variable as a byte slice.
+   */
+  findBytes(name: string): Uint8Array | null
+  /**
+   * Get the value of a string config variable as an owned string.
+   *
+   * 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.
+   *
+   * @category Config/Methods
+   * @signature
+   * ```ts
+   * class Config {
+   *   getString(name: string): string;
+   * }
+   * ```
+   *
+   * @param {string} name - The name of config entry.
+   * @returns The value of a string config variable.
+   * @throws An error will be returned if the config value is not valid utf-8.
+   */
+  getString(name: string): string
+  /**
+   * Find the value of a string config variable as an owned string.
+   *
+   * 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.
+   *
+   * @category Config/Methods
+   * @signature
+   * ```ts
+   * class Config {
+   *   findString(name: string): string | null;
+   * }
+   * ```
+   *
+   * @param {string} name - The name of config entry.
+   * @returns The value of a string config variable.
+   */
+  findString(name: string): string | null
+  /**
+   * Get the value of a path config variable.
+   *
+   * A leading '~' will be expanded to the global search path (which
+   * defaults to the user's home directory but can be overridden via
+   * [`git_libgit2_opts`][1].
+   *
+   * [1]: https://libgit2.org/docs/reference/v1.9.0/common/git_libgit2_opts.html
+   *
+   * 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.
+   *
+   * @category Config/Methods
+   * @signature
+   * ```ts
+   * class Config {
+   *   getPath(name: string): string;
+   * }
+   * ```
+   *
+   * @param {string} name - The name of config entry.
+   * @returns The value of a path config variable.
+   */
+  getPath(name: string): string
+  /**
+   * Find the value of a path config variable.
+   *
+   * A leading '~' will be expanded to the global search path (which
+   * defaults to the user's home directory but can be overridden via
+   * [`git_libgit2_opts`][1].
+   *
+   * [1]: https://libgit2.org/docs/reference/v1.9.0/common/git_libgit2_opts.html
+   *
+   * 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.
+   *
+   * @category Config/Methods
+   * @signature
+   * ```ts
+   * class Config {
+   *   findPath(name: string): string | null;
+   * }
+   * ```
+   *
+   * @param {string} name - The name of config entry.
+   * @returns The value of a path config variable.
+   */
+  findPath(name: string): string | null
+  /**
+   * Get the entry for a config variable.
+   *
+   * @category Config/Methods
+   * @signature
+   * ```ts
+   * class Config {
+   *   getEntry(name: string): ConfigEntry;
+   * }
+   * ```
+   *
+   * @param {string} name - The name of config entry.
+   * @returns `ConfigEntry` object representing a certain entry owned by a `Config` instance.
+   */
+  getEntry(name: string): ConfigEntry
+  /**
+   * Find the entry for a config variable.
+   *
+   * @category Config/Methods
+   * @signature
+   * ```ts
+   * class Config {
+   *   findEntry(name: string): ConfigEntry | null;
+   * }
+   * ```
+   *
+   * @param {string} name - The name of config entry.
+   * @returns `ConfigEntry` object representing a certain entry owned by a `Config` instance.
+   */
+  findEntry(name: string): ConfigEntry | null
+  /**
+   * Iterate over all the config variables.
+   *
+   * @category Config/Methods
+   * @signature
+   * ```ts
+   * class Config {
+   *   entries(glob?: string): ConfigEntries;
+   * }
+   * ```
+   *
+   * @param {string} [glob] - If `glob` is provided, then the iterator will only iterate over all
+   * variables whose name matches the pattern.
+   * The regular expression is applied case-sensitively on the normalized form of
+   * the variable name: the section and variable parts are lower-cased. The
+   * subsection is left unchanged.
+   *
+   * @returns An iterator over the `ConfigEntry` values of a config.
+   * @example
+   *
+   * ```ts
+   * import { openDefaultConfig } from 'es-git';
+   *
+   * const config = openDefaultConfig();
+   * for (const entry of config.entries()) {
+   *   console.log(entry.name, entry.value);
+   * }
+   * ```
+   */
+  entries(glob?: string | undefined | null): ConfigEntries
+  /**
+   * Iterate over the values of a multivar.
+   *
+   * @category Config/Methods
+   * @signature
+   * ```ts
+   * class Config {
+   *   multivar(name: string, regexp?: string): ConfigEntries;
+   * }
+   * ```
+   *
+   * @param {string} name - The name of config entry.
+   * @param {string} [regexp] - If `regexp` is provided, then the iterator will only iterate over all
+   * values which match the pattern.
+   * The regular expression is applied case-sensitively on the normalized form of
+   * the variable name: the section and variable parts are lower-cased. The
+   * subsection is left unchanged.
+   *
+   * @returns An iterator over the `ConfigEntry` values of a config.
+   */
+  multivar(name: string, regexp?: string | undefined | null): ConfigEntries
+  /**
+   * Set the value of a boolean config variable in the config file with the
+   * highest level (usually the local one).
+   *
+   * @category Config/Methods
+   * @signature
+   * ```ts
+   * class Config {
+   *   setBool(name: string, value: boolean): void;
+   * }
+   * ```
+   *
+   * @param {string} name - The name of config entry.
+   * @param {boolean} value - The value of config entry.
+   */
+  setBool(name: string, value: boolean): void
+  /**
+   * Set the value of an integer config variable in the config file with the
+   * highest level (usually the local one).
+   *
+   * @category Config/Methods
+   * @signature
+   * ```ts
+   * class Config {
+   *   setI32(name: string, value: number): void;
+   * }
+   * ```
+   *
+   * @param {string} name - The name of config entry.
+   * @param {number} value - The value of config entry.
+   */
+  setI32(name: string, value: number): void
+  /**
+   * Set the value of an integer config variable in the config file with the
+   * highest level (usually the local one).
+   *
+   * @category Config/Methods
+   * @signature
+   * ```ts
+   * class Config {
+   *   setI64(name: string, value: number): void;
+   * }
+   * ```
+   *
+   * @param {string} name - The name of config entry.
+   * @param {number} value - The value of config entry.
+   */
+  setI64(name: string, value: number): void
+  /**
+   * Set the value of an multivar config variable in the config file with the
+   * highest level (usually the local one).
+   *
+   * @category Config/Methods
+   * @signature
+   * ```ts
+   * class Config {
+   *   setMultivar(name: string, regexp: string, value: string): void;
+   * }
+   * ```
+   *
+   * @param {string} name - The name of config entry.
+   * @param {string} regexp - The regular expression is applied case-sensitively on the value.
+   * @param {string} value - The value of config entry.
+   */
+  setMultivar(name: string, regexp: string, value: string): void
+  /**
+   * Set the value of a string config variable in the config file with the
+   * highest level (usually the local one).
+   *
+   * @category Config/Methods
+   * @signature
+   * ```ts
+   * class Config {
+   *   setString(name: string, value: string): void;
+   * }
+   * ```
+   *
+   * @param {string} name - The name of config entry.
+   * @param {string} value - The value of config entry.
+   */
+  setString(name: string, value: string): void
+}
 /**
  * The diff object that contains all individual file deltas.
  *
  * This is an opaque structure which will be allocated by one of the diff
- * generator functions on the `Repository` structure (e.g. `diff_tree_to_tree`
- * or other `diff_*` functions).
- *
- * @hideconstructor
+ * generator functions on the `Repository` class (e.g. `diffTreeToTree`
+ * or other `diff*` functions).
  */
 export declare class Diff {
   /**
@@ -819,59 +2034,211 @@ export declare class Diff {
    * as if the old version was from the "onto" list and the new version
    * is from the "from" list (with the exception that if the item has a
    * pending DELETE in the middle, then it will show as deleted).
+   *
+   * @category Diff/Methods
+   * @signature
+   * ```ts
+   * class Diff {
+   *   merge(diff: Diff): void;
+   * }
+   * ```
+   *
+   * @param {Diff} diff - Another diff to merge.
    */
   merge(diff: Diff): void
-  /** Returns an iterator over the deltas in this diff. */
+  /**
+   * Returns an iterator over the deltas in this diff.
+   *
+   * @category Diff/Methods
+   * @signature
+   * ```ts
+   * class Diff {
+   *   deltas(): Deltas;
+   * }
+   * ```
+   *
+   * @returns An iterator over the deltas in this diff.
+   */
   deltas(): Deltas
-  /** Check if deltas are sorted case sensitively or insensitively. */
+  /**
+   * Check if deltas are sorted case sensitively or insensitively.
+   *
+   * @category Diff/Methods
+   * @signature
+   * ```ts
+   * class Diff {
+   *   isSortedIcase(): boolean;
+   * }
+   * ```
+   *
+   * @returns Returns `true` if deltas are sorted case insensitively.
+   */
   isSortedIcase(): boolean
-  /** Accumulate diff statistics for all patches. */
+  /**
+   * Accumulate diff statistics for all patches.
+   *
+   * @category Diff/Methods
+   * @signature
+   * ```ts
+   * class Diff {
+   *   stats(): DiffStats;
+   * }
+   * ```
+   *
+   * @returns Diff statistics for all patches.
+   */
   stats(): DiffStats
-  /** Iterate over a diff generating formatted text output. */
+  /**
+   * Iterate over a diff generating formatted text output.
+   *
+   * @category Diff/Methods
+   * @signature
+   * ```ts
+   * class Diff {
+   *   print(options?: DiffPrintOptions | null): string;
+   * }
+   * ```
+   *
+   * @param {DiffPrintOptions} [options] - Print options for diff.
+   * @returns Formatted text output.
+   */
   print(options?: DiffPrintOptions | undefined | null): string
+  /**
+   * Transform a diff marking file renames, copies, etc.
+   *
+   * This modifies a diff in place, replacing old entries that look like
+   * renames or copies with new entries reflecting those changes. This also
+   * will, if requested, break modified files into add/remove pairs if the
+   * amount of change is above a threshold.
+   *
+   * @category Diff/Methods
+   * @signature
+   * ```ts
+   * class Diff {
+   *   findSimilar(options?: DiffFindOptions): void;
+   * }
+   * ```
+   *
+   * @param {DiffFindOptions} [options] - Options for finding diff.
+   */
+  findSimilar(options?: DiffFindOptions | undefined | null): void
 }
-/**
- * Structure describing a hunk of a diff.
- *
- * @hideconstructor
- */
+/** A class describing a hunk of a diff. */
 export declare class DiffStats {
-  /** Get the total number of files changed in a diff. */
+  /**
+   * Get the total number of files changed in a diff.
+   *
+   * @category Diff/DiffStats
+   * @signature
+   * ```ts
+   * class DiffStats {
+   *   get filesChanged(): bigint;
+   * }
+   * ```
+   *
+   * @returns Total number of files changed in a diff.
+   */
   get filesChanged(): bigint
-  /** Get the total number of insertions in a diff */
+  /**
+   * Get the total number of insertions in a diff
+   *
+   * @category Diff/DiffStats
+   * @signature
+   * ```ts
+   * class DiffStats {
+   *   get insertions(): bigint;
+   * }
+   * ```
+   *
+   * @returns Total number of insertions in a diff.
+   */
   get insertions(): bigint
-  /** Get the total number of deletions in a diff */
+  /**
+   * Get the total number of deletions in a diff
+   *
+   * @category Diff/DiffStats
+   * @signature
+   * ```ts
+   * class DiffStats {
+   *   get deletions(): bigint;
+   * }
+   * ```
+   *
+   * @returns Total number of deletions in a diff.
+   */
   get deletions(): bigint
 }
-/**
- * An iterator over the diffs in a delta
- *
- * @hideconstructor
- */
+/** An iterator over the diffs in a delta. */
 export declare class Deltas {
   [Symbol.iterator](): Iterator<DiffDelta, void, void>
 }
-/**
- * Description of changes to one entry.
- *
- * @hideconstructor
- */
+/** Description of changes to one entry. */
 export declare class DiffDelta {
   /**
    * Returns the flags on the delta.
    *
-   * For more information, see `DiffFlags`'s documentation.
+   * @category Diff/DiffDelta
+   * @signature
+   * ```ts
+   * class DiffDelta {
+   *   flags(): number;
+   * }
+   * ```
+   *
+   * @returns The flags on the delta.
+   *
+   * @example
+   * ```ts
+   * import { DiffDelta, DiffFlags, diffFlagsContains } from 'es-git';
+   *
+   * const delta: DiffDelta;
+   * console.assert(diffFlagsContains(delta.flags(), DiffFlags.Binary | DiffFlags.ValidId));
+   * ```
    */
   flags(): number
-  /** Returns the number of files in this delta. */
+  /**
+   * Returns the number of files in this delta.
+   *
+   * @category Diff/DiffDelta
+   * @signature
+   * ```ts
+   * class DiffDelta {
+   *   numFiles(): number;
+   * }
+   * ```
+   *
+   * @returns The number of files in this delta.
+   */
   numFiles(): number
-  /** Returns the status of this entry */
+  /**
+   * Returns the status of this entry.
+   *
+   * @category Diff/DiffDelta
+   * @signature
+   * ```ts
+   * class DiffDelta {
+   *   status(): DeltaType;
+   * }
+   * ```
+   *
+   * @returns The status of this entry.
+   */
   status(): DeltaType
   /**
    * Return the file which represents the "from" side of the diff.
    *
    * What side this means depends on the function that was used to generate
    * the diff and will be documented on the function itself.
+   *
+   * @category Diff/DiffDelta
+   * @signature
+   * ```ts
+   * class DiffDelta {
+   *   oldFile(): DiffFile;
+   * }
+   * ```
+   *
+   * @returns The file which represents the "from" side of the diff.
    */
   oldFile(): DiffFile
   /**
@@ -879,6 +2246,16 @@ export declare class DiffDelta {
    *
    * What side this means depends on the function that was used to generate
    * the diff and will be documented on the function itself.
+   *
+   * @category Diff/DiffDelta
+   * @signature
+   * ```ts
+   * class DiffDelta {
+   *   newFile(): DiffFile;
+   * }
+   * ```
+   *
+   * @returns The file which represents the "to" side of the diff.
    */
   newFile(): DiffFile
 }
@@ -888,44 +2265,130 @@ export declare class DiffDelta {
  * Although this is called a "file" it could represent a file, a symbolic
  * link, a submodule commit id, or even a tree (although that only happens if
  * you are tracking type changes or ignored/untracked directories).
- *
- * @hideconstructor
  */
 export declare class DiffFile {
   /**
    * Returns the Oid of this item.
    *
-   * If this entry represents an absent side of a diff (e.g. the `old_file`
+   * If this entry represents an absent side of a diff (e.g. the `oldFile`
    * of a `Added` delta), then the oid returned will be zeroes.
+   *
+   * @category Diff/DiffFile
+   * @signature
+   * ```ts
+   * class DiffFile {
+   *   id(): string;
+   * }
+   * ```
+   *
+   * @returns The Oid of this item.
    */
   id(): string
   /**
    * Returns the path of the entry relative to the working directory of the
    * repository.
+   *
+   * @category Diff/DiffFile
+   * @signature
+   * ```ts
+   * class DiffFile {
+   *   path(): string | null;
+   * }
+   * ```
+   *
+   * @returns Ths path of the entry relative to the working directory of the repository.
    */
   path(): string | null
-  /** Returns the size of this entry, in bytes */
+  /**
+   * Returns the size of this entry, in bytes.
+   *
+   * @category Diff/DiffFile
+   * @signature
+   * ```ts
+   * class DiffFile {
+   *   size(): bigint;
+   * }
+   * ```
+   *
+   * @returns The size of this entry, in bytes.
+   */
   size(): bigint
-  /** Returns `true` if file(s) are treated as binary data. */
+  /**
+   * Returns `true` if file(s) are treated as binary data.
+   *
+   * @category Diff/DiffFile
+   * @signature
+   * ```ts
+   * class DiffFile {
+   *   isBinary(): boolean;
+   * }
+   * ```
+   *
+   * @returns Returns `true` if file(s) are treated as binary data.
+   */
   isBinary(): boolean
-  /** Returns `true` if `id` value is known correct. */
+  /**
+   * Returns `true` if `id` value is known correct.
+   *
+   * @category Diff/DiffFile
+   * @signature
+   * ```ts
+   * class DiffFile {
+   *   isValidId(): boolean;
+   * }
+   * ```
+   *
+   * @returns Returns `true` if `id` value is known correct.
+   */
   isValidId(): boolean
-  /** Returns `true` if file exists at this side of the delta. */
+  /**
+   * Returns `true` if file exists at this side of the delta.
+   *
+   * @category Diff/DiffFile
+   * @signature
+   * ```ts
+   * class DiffFile {
+   *   exists(): boolean;
+   * }
+   * ```
+   *
+   * @returns Returns `true` if file exists at this side of the delta.
+   */
   exists(): boolean
-  /** Returns file mode. */
+  /**
+   * Returns file mode.
+   *
+   * @category Diff/DiffFile
+   * @signature
+   * ```ts
+   * class DiffFile {
+   *   mode(): FileMode;
+   * }
+   * ```
+   *
+   * @returns
+   */
   mode(): FileMode
 }
 /**
- * A structure to represent a git [index][1]
- * @hideconstructor
+ * A class to represent a git [index][1].
  *
- * [1]: http://git-scm.com/book/en/Git-Internals-Git-Objects
+ * [1]: https://git-scm.com/book/en/Git-Internals-Git-Objects
  */
 export declare class Index {
   /**
    * Get index on-disk version.
    *
-   * Valid return values are 2, 3, or 4.  If 3 is returned, an index
+   * @category Index/Methods
+   * @signature
+   * ```ts
+   * class Index {
+   *   version(): number;
+   * }
+   * ```
+   *
+   * @returns Index on-disk version.
+   * Valid return values are 2, 3, or 4. If 3 is returned, an index
    * with version 2 may be written instead, if the extension data in
    * version 3 is not necessary.
    */
@@ -933,20 +2396,38 @@ export declare class Index {
   /**
    * Set index on-disk version.
    *
-   * Valid values are 2, 3, or 4.  If 2 is given, git_index_write may
+   * @category Index/Methods
+   * @signature
+   * ```ts
+   * class Index {
+   *   setVersion(version: number): number;
+   * }
+   * ```
+   *
+   * @param {string} version - Version to set.
+   * Valid values are 2, 3, or 4. If 2 is given, git_index_write may
    * write an index with version 3 instead, if necessary to accurately
    * represent the index.
    */
   setVersion(version: number): void
-  /** Get one of the entries in the index by its path. */
-  getByPath(path: string, stage?: IndexStage | undefined | null): IndexEntry | null
   /**
-   * Add or update an index entry from a file on disk
+   * Get one of the entries in the index by its path.
    *
-   * The file path must be relative to the repository's working folder and
-   * must be readable.
+   * @category Index/Methods
+   * @signature
+   * ```ts
+   * class Index {
+   *   getByPath(path: string, stage?: IndexStage): IndexEntry | null;
+   * }
+   * ```
    *
-   * This method will fail in bare index instances.
+   * @param {string} path - Path to lookup entry.
+   * @param {IndexStage} [stage] - Git index stage states.
+   * @returns Index entry for the path.
+   */
+  getByPath(path: string, stage?: IndexStage | undefined | null): IndexEntry | null
+  /**
+   * Add or update an index entry from a file on disk.
    *
    * This forces the file to be added to the index, not looking at gitignore
    * rules.
@@ -954,17 +2435,38 @@ export declare class Index {
    * If this file currently is the result of a merge conflict, this file will
    * no longer be marked as conflicting. The data about the conflict will be
    * moved to the "resolve undo" (REUC) section.
+   *
+   * @category Index/Methods
+   * @signature
+   * ```ts
+   * class Index {
+   *   addPath(path: string): void;
+   * }
+   * ```
+   *
+   * @param {string} path - Relative file path to the repository's working directory and must be
+   * readable.
+   *
+   * @throws This method will fail in bare index instances.
    */
   addPath(path: string): void
   /**
    * Add or update index entries matching files in the working directory.
    *
-   * This method will fail in bare index instances.
+   * @category Index/Methods
+   * @signature
+   * ```ts
+   * class Index {
+   *   addAll(pathspecs: string[], options?: IndexAddAllOptions): void;
+   * }
+   * ```
    *
-   * The `pathspecs` are a list of file names or shell glob patterns that
-   * will matched against files in the repository's working directory. Each
-   * file that matches will be added to the index (either updating an
-   * existing entry or adding a new entry).
+   * @param {string[]} pathspecs - A List of file names of shell glob patterns that will matched
+   * against files in the repository's working directory. Each file that matches will be added
+   * to the index (either updating an existing entry or adding a new entry).
+   * @param {IndexAddAllOptions} [options] - Options for add or update index entries.
+   *
+   * @throws This method will fail in bare index instances.
    *
    * @example
    *
@@ -984,11 +2486,19 @@ export declare class Index {
    * Update the contents of an existing index object in memory by reading
    * from the hard disk.
    *
-   * If force is true, this performs a "hard" read that discards in-memory
-   * changes and always reloads the on-disk index data. If there is no
-   * on-disk version, the index will be cleared.
+   * @category Index/Methods
+   * @signature
+   * ```ts
+   * class Index {
+   *   read(force?: boolean): void;
+   * }
+   * ```
+   *
+   * @param {boolean} [force] - If force is `true`, this performs a "hard" read that discards
+   * in-memory changes and always reloads the on-disk index data. If there is no on-disk version,
+   * the index will be cleared.
    *
-   * If force is false, this does a "soft" read that reloads the index data
+   * If force is `false`, this does a "soft" read that reloads the index data
    * from disk only if it has changed since the last time it was loaded.
    * Purely in-memory index data will be untouched. Be aware: if there are
    * changes on disk, unwritten in-memory changes are discarded.
@@ -997,6 +2507,14 @@ export declare class Index {
   /**
    * Write an existing index object from memory back to disk using an atomic
    * file lock.
+   *
+   * @category Index/Methods
+   * @signature
+   * ```ts
+   * class Index {
+   *   write(): void;
+   * }
+   * ```
    */
   write(): void
   /**
@@ -1011,96 +2529,248 @@ export declare class Index {
    * existing repository.
    *
    * The index must not contain any file in conflict.
+   *
+   * @category Index/Methods
+   * @signature
+   * ```ts
+   * class Index {
+   *   writeTree(): void;
+   * }
+   * ```
    */
   writeTree(): string
   /**
    * Remove an index entry corresponding to a file on disk.
    *
-   * The file path must be relative to the repository's working folder. It
-   * may exist.
-   *
    * If this file currently is the result of a merge conflict, this file will
    * no longer be marked as conflicting. The data about the conflict will be
    * moved to the "resolve undo" (REUC) section.
+   *
+   * @category Index/Methods
+   * @signature
+   * ```ts
+   * class Index {
+   *   removePath(path: string, options?: IndexRemoveOptions): void;
+   * }
+   * ```
+   *
+   * @param {string} path - Relative file path to the repository's working directory.
+   * @param {IndexRemoveOptions} options - Options for remove an index entry.
    */
   removePath(path: string, options?: IndexRemoveOptions | undefined | null): void
-  /** Remove all matching index entries. */
-  removeAll(pathspecs: Array<string>, options?: IndexRemoveAllOptions | undefined | null): void
   /**
-   * Update all index entries to match the working directory
+   * Remove all matching index entries.
+   *
+   * @category Index/Methods
+   * @signature
+   * ```ts
+   * class Index {
+   *   removeAll(pathspecs: string[], options?: IndexRemoveAllOptions): void;
+   * }
+   * ```
    *
-   * This method will fail in bare index instances.
+   * @param {string[]} pathspecs - A List of file names of shell glob patterns that will matched
+   * against files in the repository's working directory
+   * @param {IndexRemoveAllOptions} options - Options for remove all matching index entry.
+   */
+  removeAll(pathspecs: Array<string>, options?: IndexRemoveAllOptions | undefined | null): void
+  /**
+   * Update all index entries to match the working directory.
    *
    * This scans the existing index entries and synchronizes them with the
    * working directory, deleting them if the corresponding working directory
    * file no longer exists otherwise updating the information (including
    * adding the latest version of file to the ODB if needed).
+   *
+   * @category Index/Methods
+   * @signature
+   * ```ts
+   * class Index {
+   *   updateAll(pathspecs: string[], options?: IndexUpdateAllOptions): void;
+   * }
+   * ```
+   *
+   * @param {string[]} pathspecs - A List of file names of shell glob patterns that will matched
+   * against files in the repository's working directory
+   * @param {IndexUpdateAllOptions} options - Options for update all matching index entry.
+   *
+   * @throws This method will fail in bare index instances.
    */
   updateAll(pathspecs: Array<string>, options?: IndexUpdateAllOptions | undefined | null): void
-  /** Get the count of entries currently in the index */
+  /**
+   * Get the count of entries currently in the index.
+   *
+   * @category Index/Methods
+   * @signature
+   * ```ts
+   * class Index {
+   *   count(): number;
+   * }
+   * ```
+   *
+   * @returns The count of entries currently in the index.
+   */
   count(): number
-  /** Return `true` is there is no entry in the index */
+  /**
+   * Return `true` is there is no entry in the index.
+   *
+   * @category Index/Methods
+   * @signature
+   * ```ts
+   * class Index {
+   *   isEmpty(): boolean;
+   * }
+   * ```
+   *
+   * @returns Return `true` is there is no entry in the index.
+   */
   isEmpty(): boolean
   /**
    * Get the full path to the index file on disk.
    *
-   * Returns `None` if this is an in-memory index.
+   * @category Index/Methods
+   * @signature
+   * ```ts
+   * class Index {
+   *   path(): string | null;
+   * }
+   * ```
+   *
+   * @returns Returns `null` if this is an in-memory index.
    */
   path(): string | null
   /**
    * Does this index have conflicts?
    *
-   * Returns `true` if the index contains conflicts, `false` if it does not.
+   * @category Index/Methods
+   * @signature
+   * ```ts
+   * class Index {
+   *   hasConflicts(): boolean;
+   * }
+   * ```
+   *
+   * @returns Returns `true` if the index contains conflicts, `false` if it does not.
    */
   hasConflicts(): boolean
-  /** Get an iterator over the entries in this index. */
+  /**
+   * Get an iterator over the entries in this index.
+   *
+   * @category Index/Methods
+   * @signature
+   * ```ts
+   * class Index {
+   *   entries(): IndexEntries;
+   * }
+   * ```
+   *
+   * @returns An iterator over the entries in this index.
+   */
   entries(): IndexEntries
 }
-/**
- * An iterator over the entries in an index
- *
- * @hideconstructor
- */
+/** An iterator over the entries in an index. */
 export declare class IndexEntries {
   [Symbol.iterator](): Iterator<IndexEntry, void, void>
 }
 /**
- * A structure to represent a git [object][1]
- * @hideconstructor
+ * A class to represent a git [object][1].
  *
- * [1]: http://git-scm.com/book/en/Git-Internals-Git-Objects
+ * [1]: https://git-scm.com/book/en/Git-Internals-Git-Objects
  */
 export declare class GitObject {
-  /** Get the id (SHA1) of a repository object */
+  /**
+   * Get the id (SHA1) of a repository object.
+   *
+   * @category Object/Methods
+   * @signature
+   * ```ts
+   * class GitObject {
+   *   id(): string;
+   * }
+   * ```
+   *
+   * @returns ID(SHA1) of a repository object.
+   */
   id(): string
   /**
    * Get the object type of object.
    *
-   * If the type is unknown, then `null` is returned.
+   * @category Object/Methods
+   * @signature
+   * ```ts
+   * class GitObject {
+   *   type(): ObjectType | null;
+   * }
+   * ```
+   *
+   * @returns If the type is unknown, then `null` is returned.
    */
   type(): ObjectType | null
   /**
    * Recursively peel an object until an object of the specified type is met.
    *
-   * If you pass `Any` as the target type, then the object will be
+   * @category Object/Methods
+   * @signature
+   * ```ts
+   * class GitObject {
+   *   peel(objType: ObjectType): GitObject;
+   * }
+   * ```
+   *
+   * @param {ObjectType} objType - If you pass `Any` as the target type, then the object will be
    * peeled until the type changes (e.g. a tag will be chased until the
    * referenced object is no longer a tag).
+   *
+   * @returns Git object which recursively peeled.
    */
   peel(objType: ObjectType): GitObject
-  /** Recursively peel an object until a commit is found */
+  /**
+   * Recursively peel an object until a commit is found.
+   *
+   * @category Object/Methods
+   * @signature
+   * ```ts
+   * class GitObject {
+   *   peelToCommit(): Commit;
+   * }
+   * ```
+   *
+   * @returns Git commit.
+   */
   peelToCommit(): Commit
+  /**
+   * Recursively peel an object until a blob is found.
+   *
+   * @category Object/Methods
+   * @signature
+   * ```ts
+   * class GitObject {
+   *   peelToBlob(): Blob;
+   * }
+   * ```
+   *
+   * @returns Git blob.
+   */
+  peelToBlob(): Blob
   /**
    * Attempt to view this object as a commit.
    *
-   * Returns `null` if the object is not actually a commit.
+   * @category Object/Methods
+   * @signature
+   * ```ts
+   * class GitObject {
+   *   asCommit(): Commit | null;
+   * }
+   * ```
+   *
+   * @returns Returns `null` if the object is not actually a commit.
    */
   asCommit(): Commit | null
 }
 /**
- * A structure to represent a git [reference][1].
- * @hideconstructor
+ * A class to represent a git [reference][1].
  *
- * [1]: http://git-scm.com/book/en/Git-Internals-Git-References
+ * [1]: https://git-scm.com/book/en/Git-Internals-Git-References
  */
 export declare class Reference {
   /**
@@ -1109,28 +2779,101 @@ export declare class Reference {
    * This method works for both direct and symbolic references. The reference
    * will be immediately removed on disk.
    *
-   * This function will return an error if the reference has changed from the
+   * @category Reference/Methods
+   * @signature
+   * ```ts
+   * class Reference {
+   *   delete(): void;
+   * }
+   * ```
+   *
+   * @throws This method will throws an error if the reference has changed from the
    * time it was looked up.
    */
   delete(): void
-  /** Check if a reference is a local branch. */
+  /**
+   * Check if a reference is a local branch.
+   *
+   * @category Reference/Methods
+   * @signature
+   * ```ts
+   * class Reference {
+   *   isBranch(): boolean;
+   * }
+   * ```
+   *
+   * @returns Returns `true` if a reference is a local branch.
+   */
   isBranch(): boolean
-  /** Check if a reference is a note. */
+  /**
+   * Check if a reference is a note.
+   *
+   * @category Reference/Methods
+   * @signature
+   * ```ts
+   * class Reference {
+   *   isNote(): boolean;
+   * }
+   * ```
+   *
+   * @returns Returns `true` if a reference is a note.
+   */
   isNote(): boolean
-  /** Check if a reference is a remote tracking branch */
+  /**
+   * Check if a reference is a remote tracking branch.
+   *
+   * @category Reference/Methods
+   * @signature
+   * ```ts
+   * class Reference {
+   *   isRemote(): boolean;
+   * }
+   * ```
+   *
+   * @returns Returns `true` if a reference is a remote tracking branch.
+   */
   isRemote(): boolean
-  /** Check if a reference is a tag */
+  /**
+   * Check if a reference is a tag.
+   *
+   * @category Reference/Methods
+   * @signature
+   * ```ts
+   * class Reference {
+   *   isTag(): boolean;
+   * }
+   * ```
+   *
+   * @returns Returns `true` if a reference is a tag.
+   */
   isTag(): boolean
   /**
    * Get the reference type of a reference.
    *
-   * If the type is unknown, then `null` is returned.
+   * @category Reference/Methods
+   * @signature
+   * ```ts
+   * class Reference {
+   *   type(): ReferenceType | null;
+   * }
+   * ```
+   *
+   * @returns Returns `null` if the type is unknown.
    */
   type(): ReferenceType | null
   /**
    * Get the full name of a reference.
    *
-   * Throws error if the name is not valid utf-8.
+   * @category Reference/Methods
+   * @signature
+   * ```ts
+   * class Reference {
+   *   name(): string;
+   * }
+   * ```
+   *
+   * @returns Full name of a reference.
+   * @throws Throws error if the name is not valid utf-8.
    */
   name(): string
   /**
@@ -1139,7 +2882,16 @@ export declare class Reference {
    * This will transform the reference name into a name "human-readable"
    * version. If no shortname is appropriate, it will return the full name.
    *
-   * Throws error if the shorthand is not valid utf-8.
+   * @category Reference/Methods
+   * @signature
+   * ```ts
+   * class Reference {
+   *   shorthand(): string;
+   * }
+   * ```
+   *
+   * @returns Full shorthand of a reference.
+   * @throws Throws error if the shorthand is not valid utf-8.
    */
   shorthand(): string
   /**
@@ -1147,26 +2899,65 @@ export declare class Reference {
    *
    * Only available if the reference is direct (i.e. an object id reference,
    * not a symbolic one).
+   *
+   * @category Reference/Methods
+   * @signature
+   * ```ts
+   * class Reference {
+   *   target(): string | null;
+   * }
+   * ```
+   *
+   * @returns OID pointed to by a direct reference.
    */
   target(): string | null
   /**
    * Return the peeled OID target of this reference.
    *
-   * This peeled OID only applies to direct references that point to a hard
-   * Tag object: it is the result of peeling such Tag.
+   * This peeled OID only applies to direct references that point to a hard.
+   *
+   * @category Reference/Methods
+   * @signature
+   * ```ts
+   * class Reference {
+   *   targetPeel(): string | null;
+   * }
+   * ```
+   *
+   * @returns Peeled OID of this reference.
    */
   targetPeel(): string | null
   /**
-   * Peel a reference to a tree
+   * Peel a reference to a tree.
    *
    * This method recursively peels the reference until it reaches
    * a tree.
+   *
+   * @category Reference/Methods
+   * @signature
+   * ```ts
+   * class Reference {
+   *   peelToTree(): Tree;
+   * }
+   * ```
+   *
+   * @returns Peeled `Tree` of this reference.
    */
   peelToTree(): Tree
   /**
    * Get full name to the reference pointed to by a symbolic reference.
    *
    * Only available if the reference is symbolic.
+   *
+   * @category Reference/Methods
+   * @signature
+   * ```ts
+   * class Reference {
+   *   symbolicTarget(): string | null;
+   * }
+   * ```
+   *
+   * @returns Full name of the reference pointed to by a symbolic reference.
    */
   symbolicTarget(): string | null
   /**
@@ -1177,6 +2968,16 @@ export declare class Reference {
    *
    * If a direct reference is passed as an argument, a copy of that
    * reference is returned.
+   *
+   * @category Reference/Methods
+   * @signature
+   * ```ts
+   * class Reference {
+   *   resolve(): Reference;
+   * }
+   * ```
+   *
+   * @returns Resolved reference.
    */
   resolve(): Reference
   /**
@@ -1184,146 +2985,414 @@ export declare class Reference {
    *
    * This method works for both direct and symbolic references.
    *
-   * If the force flag is not enabled, and there's already a reference with
-   * the given name, the renaming will fail.
+   * @category Reference/Methods
+   * @signature
+   * ```ts
+   * class Reference {
+   *   rename(newName: string, options?: RenameReferenceOptions): Reference;
+   * }
+   * ```
+   *
+   * @param {string} newName - Name to rename an existing reference.
+   * @param {RenameReferenceOptions} [options] - Options to rename an existing reference.
+   * @returns Renamed reference.
    */
   rename(newName: string, options?: RenameReferenceOptions | undefined | null): Reference
 }
 /**
- * A structure representing a [remote][1] of a git repository.
- * @hideconstructor
+ * A class representing a [remote][1] of a git repository.
  *
- * [1]: http://git-scm.com/book/en/Git-Basics-Working-with-Remotes
+ * [1]: https://git-scm.com/book/en/Git-Basics-Working-with-Remotes
  */
 export declare class Remote {
   /**
    * Get the remote's name.
    *
-   * Returns `null` if this remote has not yet been named, and
-   * Throws error if the URL is not valid utf-8
+   * @category Remote/Methods
+   * @signature
+   * ```ts
+   * class Remote {
+   *   name(): string | null;
+   * }
+   * ```
+   *
+   * @returns Returns `null` if this remote has not yet been named.
+   * @throws Throws error if the name is not valid utf-8.
    */
   name(): string | null
   /**
    * Get the remote's URL.
    *
-   * Throws error if the URL is not valid utf-8
+   * @category Remote/Methods
+   * @signature
+   * ```ts
+   * class Remote {
+   *   url(): string;
+   * }
+   * ```
+   *
+   * @throws Throws error if the URL is not valid utf-8.
    */
   url(): string
   /**
    * Get the remote's URL.
    *
-   * Returns `null` if push url not exists, and
-   * Throws error if the URL is not valid utf-8
+   * @category Remote/Methods
+   * @signature
+   * ```ts
+   * class Remote {
+   *   pushurl(): string | null;
+   * }
+   * ```
+   *
+   * @returns Returns `null` if push url not exists.
+   * @throws Throws error if the URL is not valid utf-8.
    */
   pushurl(): string | null
   /**
    * List all refspecs.
    *
-   * Filter refspec if has not valid src or dst with utf-8
+   * Filter refspec if has not valid `src` or `dst` with utf-8.
+   *
+   * @category Remote/Methods
+   * @signature
+   * ```ts
+   * class Remote {
+   *   refspecs(): Refspec[];
+   * }
+   * ```
+   *
+   * @returns List all refspecs.
+   *
+   * @example
+   * ```ts
+   * import { openRepository } from 'es-git';
+   *
+   * const repo = await openRepository('/path/to/repo');
+   * const remote = repo.getRemote('origin');
+   *
+   * // Retrieving the Refspecs configured for this remote
+   * const refspecs = remote.refspecs();
+   * console.log(refspecs[0]);
+   * // For the "+refs/heads/*:refs/remotes/origin/*" Refspec
+   * // {
+   * //   "direction": "Fetch",
+   * //   "src": "refs/heads/*",
+   * //   "dst": "refs/remotes/origin/*",
+   * //   "force": true
+   * // }
+   * ```
    */
-  refspecs(): Array<RefspecObject>
+  refspecs(): Array<Refspec>
   /**
-   * Download new data and update tips
+   * Download new data and update tips.
    *
    * Convenience function to connect to a remote, download the data, disconnect and update the remote-tracking branches.
+   *
+   * @category Remote/Methods
+   * @signature
+   * ```ts
+   * class Remote {
+   *   fetch(
+   *     refspecs: string[],
+   *     options?: FetchRemoteOptions,
+   *     signal?: AbortSignal,
+   *   ): Promise<void>;
+   * }
+   * ```
+   *
+   * @param {string[]} refspecs - Refspecs to fetch from remote.
+   * @param {FetchRemoteOptions} [options] - Options for fetch remote.
+   * @param {AbortSignal} [signal] Abort signal.
+   *
+   * @example
+   * ```ts
+   * import { openRepository } from 'es-git';
+   *
+   * const repo = await openRepository('/path/to/repo');
+   * const remote = repo.getRemote('origin');
+   *
+   * // Fetching data from the "main" branch
+   * await remote.fetch(['main']);
+   *
+   * // Providing an empty array fetches data using the default Refspec configured for the remote
+   * await remote.fetch([]);
+   * ```
    */
   fetch(refspecs: Array<string>, options?: FetchRemoteOptions | undefined | null, signal?: AbortSignal | undefined | null): Promise<void>
   /**
-   * Perform a push
+   * Perform a push.
    *
    * Perform all the steps for a push.
    * If no refspecs are passed, then the configured refspecs will be used.
+   *
+   * @category Remote/Methods
+   * @signature
+   * ```ts
+   * class Remote {
+   *   push(
+   *     refspecs: string[],
+   *     options?: PushOptions,
+   *     signal?: AbortSignal,
+   *   ): Promise<void>;
+   * }
+   * ```
+   *
+   * @param {string[]} refspecs - Refspecs to push to remote.
+   * @param {FetchRemoteOptions} [options] - Options for push remote.
+   * @param {AbortSignal} [signal] Abort signal.
+   *
+   * @example
+   * ```ts
+   * import { openRepository } from 'es-git';
+   *
+   * const repo = await openRepository('/path/to/repo');
+   * const remote = repo.getRemote('origin');
+   *
+   * // Push the local "main" branch to the remote "other" branch
+   * await remote.push(['refs/heads/main:refs/heads/other']);
+   *
+   * // Push with credential.
+   * await remote.push(['refs/heads/main:refs/heads/other'], {
+   *   credential: {
+   *     type: 'Plain',
+   *     password: '<personal access token>',
+   *   },
+   * });
+   * ```
    */
   push(refspecs: Array<string>, options?: PushOptions | undefined | null, signal?: AbortSignal | undefined | null): Promise<void>
-  /** Prune tracking refs that are no longer present on remote */
+  /**
+   * Prune tracking refs that are no longer present on remote.
+   *
+   * @category Remote/Methods
+   * @signature
+   * ```ts
+   * class Remote {
+   *   prune(options?: PruneOptions, signal?: AbortSignal): Promise<void>;
+   * }
+   * ```
+   *
+   * @param {PruneOptions} [options] - Options for prune remote.
+   * @param {AbortSignal} [signal] Abort signal.
+   */
   prune(options?: PruneOptions | undefined | null, signal?: AbortSignal | undefined | null): Promise<void>
-  /** Get the remote’s default branch. */
+  /**
+   * Get the remote’s default branch.
+   *
+   * The `fetch` operation from the remote is also performed.
+   *
+   * @category Remote/Methods
+   * @signature
+   * ```ts
+   * class Remote {
+   *   defaultBranch(signal?: AbortSignal): Promise<string>;
+   * }
+   * ```
+   *
+   * @param {AbortSignal} [signal] Abort signal.
+   * @returns Default branch name.
+   *
+   * @example
+   * ```ts
+   * import { openRepository } from 'es-git';
+   *
+   * const repo = await openRepository('/path/to/repo');
+   * const remote = repo.getRemote('origin');
+   *
+   * const branch = await remote.defaultBranch();
+   * console.log(branch); // "refs/heads/main"
+   * ```
+   */
   defaultBranch(signal?: AbortSignal | undefined | null): Promise<string>
 }
 /**
  * An owned git repository, representing all state associated with the
  * underlying filesystem.
  *
- * This structure corresponds to a `git_repository` in libgit2.
- *
- * When a repository goes out of scope, it is freed in memory but not deleted
- * from the filesystem.
- *
- * @hideconstructor
+ * This class corresponds to a git repository in libgit2.
  */
 export declare class Repository {
   /**
    * Lookup a reference to one of the commits in a repository.
    *
    * Returns `null` if the commit does not exist.
+   *
+   * @category Repository/Methods
+   *
+   * @signature
+   * ```ts
+   * class Repository {
+   *   findCommit(oid: string): Commit | null;
+   * }
+   * ```
+   * @param {string} oid - Commit ID(SHA1) to lookup.
+   * @returns Commit instance found by oid. Returns `null` if the commit does not exist.
    */
   findCommit(oid: string): Commit | null
-  /** Lookup a reference to one of the commits in a repository. */
+  /**
+   * Lookup a reference to one of the commits in a repository.
+   *
+   * @category Repository/Methods
+   *
+   * @signature
+   * ```ts
+   * class Repository {
+   *   getCommit(oid: string): Commit;
+   * }
+   * ```
+   *
+   * @param {string} oid - Commit ID(SHA1) to lookup.
+   * @returns Commit instance found by oid.
+   * @throws Throws error if the commit does not exist.
+   */
   getCommit(oid: string): Commit
   /**
-   * Create new commit in the repository
+   * Create new commit in the repository.
    *
-   * If the `update_ref` is not `null`, name of the reference that will be
+   * If the `updateRef` is not `null`, name of the reference that will be
    * updated to point to this commit. If the reference is not direct, it will
    * be resolved to a direct reference. Use "HEAD" to update the HEAD of the
    * current branch and make it point to this commit. If the reference
    * doesn't exist yet, it will be created. If it does exist, the first
    * parent must be the tip of this branch.
+   *
+   * @category Repository/Methods
+   *
+   * @signature
+   * ```ts
+   * class Repository {
+   *   commit(tree: Tree, message: string, options?: CommitOptions | null): string;
+   * }
+   * ```
+   *
+   * @returns ID(SHA1) of created commit.
    */
   commit(tree: Tree, message: string, options?: CommitOptions | undefined | null): string
+  /**
+   * Get the configuration file for this repository.
+   *
+   * @category Repository/Methods
+   * @signature
+   * ```ts
+   * class Repository {
+   *   config(): Config;
+   * }
+   * ```
+   *
+   * @returns If a configuration file has not been set, the default config set for the
+   * repository will be returned, including global and system configurations
+   * (if they are available).
+   */
+  config(): Config
   /**
    * Create a diff with the difference between two tree objects.
    *
-   * This is equivalent to `git diff <old-tree> <new-tree>`
+   * This is equivalent to `git diff <old-tree> <new-tree>`.
+   *
+   * @category Repository/Methods
+   * @signature
+   * ```ts
+   * class Repository {
+   *   diffTreeToTree(
+   *     oldTree?: Tree,
+   *     newTree?: Tree,
+   *     options?: DiffOptions,
+   *   ): Diff;
+   * }
+   * ```
+   *
+   * @param {Tree} [oldTree] - Tree used for the "oldFile" side of the delta. If you not pass,
+   * then an empty tree is used.
+   * @param {Tree} [newTree] - Tree used for the "newFile" side of the delta. If you not pass,
+   * then an empty tree is used.
+   * @param {DiffOptions} [options] - Describing options about how the diff should be executed.
    *
-   * The first tree will be used for the "old_file" side of the delta and the
-   * second tree will be used for the "new_file" side of the delta.  You can
-   * pass `null` to indicate an empty tree, although it is an error to pass
-   * `null` for both the `oldTree` and `newTree`.
+   * @returns {Diff} Diff between two tree objects.
+   * @throws Throws error if the `oldTree` and `newTree` is `null`.
    */
   diffTreeToTree(oldTree?: Tree | undefined | null, newTree?: Tree | undefined | null, options?: DiffOptions | undefined | null): Diff
   /**
    * Create a diff between two index objects.
    *
-   * The first index will be used for the "old_file" side of the delta, and
-   * the second index will be used for the "new_file" side of the delta.
+   * @category Repository/Methods
+   * @signature
+   * ```ts
+   * class Repository {
+   *   diffIndexToIndex(
+   *     oldIndex: Index,
+   *     newIndex: Index,
+   *     options?: DiffOptions,
+   *   ): Diff;
+   * }
+   * ```
+   *
+   * @param {Index} [oldIndex] - Index used for the "oldFile" side of the delta.
+   * @param {Index} [newIndex] - Index used for the "newFile" side of the delta.
+   * @param {DiffOptions} [options] - Describing options about how the diff should be executed.
+   *
+   * @returns {Diff} Diff between two index objects.
    */
   diffIndexToIndex(oldIndex: Index, newIndex: Index, options?: DiffOptions | undefined | null): Diff
   /**
    * Create a diff between the repository index and the workdir directory.
    *
    * This matches the `git diff` command.  See the note below on
-   * `tree_to_workdir` for a discussion of the difference between
+   * `diffTreeToWorkdir` for a discussion of the difference between
    * `git diff` and `git diff HEAD` and how to emulate a `git diff <treeish>`
    * using libgit2.
    *
-   * The index will be used for the "old_file" side of the delta, and the
-   * working directory will be used for the "new_file" side of the delta.
+   * @category Repository/Methods
+   * @signature
+   * ```ts
+   * class Repository {
+   *   diffIndexToWorkdir(index?: Index, options?: DiffOptions): Diff;
+   * }
+   * ```
+   *
+   * @param {Index} [index] - Index used for the "oldFile" side of the delta. The working directory
+   * will be used for the "newFile" side of the delta.
    *
-   * If you pass `null` for the index, then the existing index of the `repo`
-   * will be used. In this case, the index will be refreshed from disk
-   * (if it has changed) before the diff is generated.
+   * If not you pass, then the existing index of the repository  will be used. In this case,
+   * the index will be refreshed from disk (if it has changed) before the diff is generated.
+   *
+   * @param {DiffOptions} [options] - Describing options about how the diff should be executed.
+   *
+   * @returns {Diff} Diff between the repository index and the workdir directory.
    */
   diffIndexToWorkdir(index?: Index | undefined | null, options?: DiffOptions | undefined | null): Diff
   /**
    * Create a diff between a tree and the working directory.
    *
-   * The tree you provide will be used for the "old_file" side of the delta,
-   * and the working directory will be used for the "new_file" side.
+   * The tree you provide will be used for the "oldFile" side of the delta,
+   * and the working directory will be used for the "newFile" side.
    *
    * This is not the same as `git diff <treeish>` or `git diff-index <treeish>`.
    * Those commands use information from the index, whereas this
    * function strictly returns the differences between the tree and the files
-   * in the working directory, regardless of the state of the index.  Use
-   * `tree_to_workdir_with_index` to emulate those commands.
+   * in the working directory, regardless of the state of the index. Use
+   * `diffTreeToWorkdirWithIndex` to emulate those commands.
    *
-   * To see difference between this and `tree_to_workdir_with_index`,
+   * To see difference between this and `diffTreeToWorkdirWithIndex`,
    * consider the example of a staged file deletion where the file has then
-   * been put back into the working dir and further modified.  The
+   * been put back into the working dir and further modified. The
    * tree-to-workdir diff for that file is 'modified', but `git diff` would
    * show status 'deleted' since there is a staged delete.
    *
-   * If `null` is passed for `tree`, then an empty tree is used.
+   * @category Repository/Methods
+   * @signature
+   * ```ts
+   * class Repository {
+   *   diffTreeToWorkdir(oldTree?: Tree, options?: DiffOptions): Diff;
+   * }
+   * ```
+   *
+   * @param {Tree} [oldTree] - Tree used for the "oldFile" side of the delta. If you not pass,
+   * then an empty tree is used.
+   *
+   * @param {DiffOptions} [options] - Describing options about how the diff should be executed.
+   *
+   * @returns {Diff} Diff between a tree and the working directory.
    */
   diffTreeToWorkdir(oldTree?: Tree | undefined | null, options?: DiffOptions | undefined | null): Diff
   /**
@@ -1333,131 +3402,527 @@ export declare class Repository {
    * This emulates `git diff <tree>` by diffing the tree to the index and
    * the index to the working directory and blending the results into a
    * single diff that includes staged deleted, etc.
+   *
+   * @category Repository/Methods
+   * @signature
+   * ```ts
+   * class Repository {
+   *   diffTreeToWorkdirWithIndex(oldTree?: Tree, options?: DiffOptions): Diff;
+   * }
+   * ```
+   *
+   * @param {Tree} [oldTree] - Tree used for the "oldFile" side of the delta. If you not pass,
+   * then an empty tree is used.
+   *
+   * @param {DiffOptions} [options] - Describing options about how the diff should be executed.
+   *
+   * @returns {Diff} Diff between a tree and the working directory using index data to account for
+   * staged deletes, tracked files, etc.
    */
   diffTreeToWorkdirWithIndex(oldTree?: Tree | undefined | null, options?: DiffOptions | undefined | null): Diff
   /**
    * Get the Index file for this repository.
    *
    * If a custom index has not been set, the default index for the repository
-   * will be returned (the one located in .git/index).
+   * will be returned (the one located in `.git/index`).
+   *
+   * @category Repository/Methods
+   * @signature
+   * ```ts
+   * class Repository {
+   *   index(): Index;
+   * }
+   * ```
    *
-   * **Caution**: If the [`git2::Repository`] of this index is dropped, then this
-   * [`git2::Index`] will become detached, and most methods on it will fail. See
-   * [`git2::Index::open`]. Be sure the repository has a binding such as a local
-   * variable to keep it alive at least as long as the index.
+   * @returns The index file for this repository.
    */
   index(): Index
   /**
    * Lookup a reference to one of the objects in a repository.
    *
-   * Returns `null` if the object does not exist.
+   * @category Repository/Methods
+   * @signature
+   * ```ts
+   * class Repository {
+   *   findObject(oid: string): GitObject | null;
+   * }
+   * ```
+   *
+   * @param {string} oid - Git object ID(SHA1) to lookup.
+   * @returns Git object. Returns `null` if the object does not exist.
    */
   findObject(oid: string): GitObject | null
-  /** Lookup a reference to one of the objects in a repository. */
+  /**
+   * Lookup a reference to one of the objects in a repository.
+   *
+   * @category Repository/Methods
+   * @signature
+   * ```ts
+   * class Repository {
+   *   getObject(oid: string): GitObject;
+   * }
+   * ```
+   *
+   * @param {string} oid - Git object ID(SHA1) to lookup.
+   * @returns Git object.
+   * @throws Throws error if the object does not exist.
+   */
   getObject(oid: string): GitObject
-  /** Lookup a reference to one of the objects in a repository. */
+  /**
+   * Lookup a reference to one of the objects in a repository.
+   *
+   * @category Repository/Methods
+   * @signature
+   * ```ts
+   * class Repository {
+   *   findReference(name: string): Reference | null;
+   * }
+   * ```
+   *
+   * @param {string} name - Reference name to lookup.
+   * @returns Returns `null` if the reference does not exist.
+   *
+   * @example
+   *
+   * Get `HEAD` reference from the repository.
+   *
+   * ```ts
+   * import { openRepository } from 'es-git';
+   *
+   * const repo = await openRepository('.');
+   * const reference = repo.findReference('HEAD');
+   * ```
+   */
   findReference(name: string): Reference | null
-  /** Lookup a reference to one of the objects in a repository. */
+  /**
+   * Lookup a reference to one of the objects in a repository.
+   *
+   * @category Repository/Methods
+   * @signature
+   * ```ts
+   * class Repository {
+   *   getReference(name: string): Reference;
+   * }
+   * ```
+   *
+   * @param {string} name - Reference name to lookup.
+   * @returns Git reference.
+   * @throws Throws error if the reference does not exist.
+   *
+   * @example
+   *
+   * Get `HEAD` reference from the repository.
+   *
+   * ```ts
+   * import { openRepository } from 'es-git';
+   *
+   * const repo = await openRepository('.');
+   * const reference = repo.getReference('HEAD');
+   * ```
+   */
   getReference(name: string): Reference
-  /** List all remotes for a given repository */
+  /**
+   * List all remotes for a given repository
+   *
+   * @category Repository/Methods
+   * @signature
+   * ```ts
+   * class Repository {
+   *   remoteNames(): string[];
+   * }
+   * ```
+   *
+   * @returns All remote names for this repository.
+   *
+   * @example
+   * ```ts
+   * import { openRepository } from 'es-git';
+   *
+   * const repo = await openRepository('/path/to/repo');
+   * console.log(repo.remoteNames()); // ["origin"]
+   * ```
+   */
   remoteNames(): Array<string>
   /**
-   * Get remote from repository
+   * Get remote from repository.
+   *
+   * @category Repository/Methods
+   * @signature
+   * ```ts
+   * class Repository {
+   *   getRemote(name: string): Remote;
+   * }
+   * ```
    *
-   * Throws error if not exists
+   * @returns Remote instance.
+   * @throws Throws error if remote does not exist.
    */
   getRemote(name: string): Remote
-  /** Find remote from repository */
+  /**
+   * Find remote from repository.
+   *
+   * @category Repository/Methods
+   * @signature
+   * ```ts
+   * class Repository {
+   *   findRemote(name: string): Remote | null;
+   * }
+   * ```
+   *
+   * @returns Returns `null` if remote does not exist.
+   */
   findRemote(name: string): Remote | null
-  /** Add a remote with the default fetch refspec to the repository’s configuration. */
+  /**
+   * Add a remote with the default fetch refspec to the repository’s configuration.
+   *
+   * @category Repository/Methods
+   * @signature
+   * ```ts
+   * class Repository {
+   *   createRemote(name: string, url: string, options?: CreateRemoteOptions): Remote;
+   * }
+   * ```
+   *
+   * @param {string} name - The name of the remote.
+   * @param {string} url - Remote url.
+   * @param {CreateRemoteOptions} [options] - Options for creating remote.
+   * @returns Created remote.
+   */
   createRemote(name: string, url: string, options?: CreateRemoteOptions | undefined | null): Remote
-  /** Tests whether this repository is a bare repository or not. */
+  /**
+   * Tests whether this repository is a bare repository or not.
+   *
+   * @category Repository/Methods
+   * @signature
+   * ```ts
+   * class Repository {
+   *   isBare(): boolean;
+   * }
+   * ```
+   *
+   * @returns Returns `true` if repository is a bare.
+   */
   isBare(): boolean
-  /** Tests whether this repository is a shallow clone. */
+  /**
+   * Tests whether this repository is a shallow clone.
+   *
+   * @category Repository/Methods
+   * @signature
+   * ```ts
+   * class Repository {
+   *   isShallow(): boolean;
+   * }
+   * ```
+   *
+   * @returns Returns `true` if repository is a shallow clone.
+   */
   isShallow(): boolean
-  /** Tests whether this repository is a worktree. */
+  /**
+   * Tests whether this repository is a worktree.
+   *
+   * @category Repository/Methods
+   * @signature
+   * ```ts
+   * class Repository {
+   *   isWorktree(): boolean;
+   * }
+   * ```
+   *
+   * @returns Returns `true` if repository is a worktree.
+   */
   isWorktree(): boolean
-  /** Tests whether this repository is empty. */
+  /**
+   * Tests whether this repository is empty.
+   *
+   * @category Repository/Methods
+   * @signature
+   * ```ts
+   * class Repository {
+   *   isEmpty(): boolean;
+   * }
+   * ```
+   *
+   * @returns Returns `true` if repository is empty.
+   */
   isEmpty(): boolean
   /**
    * Returns the path to the `.git` folder for normal repositories or the
    * repository itself for bare repositories.
+   *
+   * @category Repository/Methods
+   * @signature
+   * ```ts
+   * class Repository {
+   *   path(): string;
+   * }
+   * ```
+   *
+   * @returns The path to the `.git` folder for normal repositories or the repository itself
+   * for bare repositories.
    */
   path(): string
-  /** Returns the current state of this repository */
+  /**
+   * Returns the current state of this repository.
+   *
+   * @category Repository/Methods
+   * @signature
+   * ```ts
+   * class Repository {
+   *   state(): RepositoryState;
+   * }
+   * ```
+   *
+   * @returns The current state of this repository.
+   */
   state(): RepositoryState
   /**
    * Get the path of the working directory for this repository.
    *
+   * @category Repository/Methods
+   * @signature
+   * ```ts
+   * class Repository {
+   *   workdir(): string | null;
+   * }
+   * ```
+   *
+   * @returns The path of the working directory for this repository.
    * If this repository is bare, then `null` is returned.
+   * ```
    */
   workdir(): string | null
-  /** Retrieve and resolve the reference pointed at by HEAD. */
+  /**
+   * Retrieve and resolve the reference pointed at by `HEAD`.
+   *
+   * @category Repository/Methods
+   * @signature
+   * ```ts
+   * class Repository {
+   *   head(): Reference;
+   * }
+   * ```
+   *
+   * @returns Reference pointed at by `HEAD`.
+   */
   head(): Reference
   /**
-   * Make the repository HEAD point to the specified reference.
+   * Make the repository `HEAD` point to the specified reference.
    *
-   * If the provided reference points to a tree or a blob, the HEAD is
+   * If the provided reference points to a tree or a blob, the `HEAD` is
    * unaltered and an error is returned.
    *
-   * If the provided reference points to a branch, the HEAD will point to
-   * that branch, staying attached, or become attached if it isn't yet. If
-   * the branch doesn't exist yet, no error will be returned. The HEAD will
-   * then be attached to an unborn branch.
+   * If the provided reference points to a branch, the `HEAD` will point to
+   * that branch, staying attached, or become attached if it isn't yet. If
+   * the branch doesn't exist yet, no error will be returned. The `HEAD` will
+   * then be attached to an unborn branch.
+   *
+   * Otherwise, the `HEAD` will be detached and will directly point to the
+   * commit.
+   *
+   * @category Repository/Methods
+   * @signature
+   * ```ts
+   * class Repository {
+   *   setHead(refname: string): void;
+   * }
+   * ```
+   *
+   * @param {string} refname - Specified reference to point into `HEAD`.
+   */
+  setHead(refname: string): void
+  /**
+   * Execute a rev-parse operation against the `spec` listed.
+   *
+   * The resulting revision specification is returned, or an error is
+   * returned if one occurs.
+   *
+   * @category Repository/Methods
+   * @signature
+   * ```ts
+   * class Repository {
+   *   revparse(spec: string): Revspec;
+   * }
+   * ```
+   *
+   * @param {string} spec - Revision string.
+   * @returns
+   */
+  revparse(spec: string): Revspec
+  /**
+   * Find a single object, as specified by a revision string.
+   *
+   * @category Repository/Methods
+   * @signature
+   * ```ts
+   * class Repository {
+   *   revparseSingle(spec: string): string;
+   * }
+   * ```
    *
-   * Otherwise, the HEAD will be detached and will directly point to the
-   * commit.
+   * @param {string} spec - Revision string.
+   * @returns OID of single object.
+   * @throws Throws error if the object does not exist.
    */
-  setHead(refname: string): void
+  revparseSingle(spec: string): string
   /**
-   * Execute a rev-parse operation against the `spec` listed.
+   * Create a revwalk that can be used to traverse the commit graph.
    *
-   * The resulting revision specification is returned, or an error is
-   * returned if one occurs.
+   * @category Repository/Methods
+   * @signature
+   * ```ts
+   * class Repository {
+   *   revwalk(): Revwalk;
+   * }
+   * ```
+   *
+   * @returns Revwalk to traverse the commit graph in this repository.
    */
-  revparse(spec: string): Revspec
-  /** Find a single object, as specified by a revision string. */
-  revparseSingle(spec: string): string
-  /** Create a revwalk that can be used to traverse the commit graph. */
   revwalk(): Revwalk
   /**
    * Lookup a tag object by prefix hash from the repository.
    *
-   * Returns `null` if tag does not exist.
+   * @category Repository/Methods
+   * @signature
+   * ```ts
+   * class Repository {
+   *   findTag(oid: string): Tag | null;
+   * }
+   * ```
+   *
+   * @param {string} oid - Prefix hash.
+   * @returns Returns `null` if tag does not exist.
    */
   findTag(oid: string): Tag | null
-  /** Lookup a tag object by prefix hash from the repository. */
+  /**
+   * Lookup a tag object by prefix hash from the repository.
+   *
+   * @category Repository/Methods
+   * @signature
+   * ```ts
+   * class Repository {
+   *   getTag(oid: string): Tag;
+   * }
+   * ```
+   *
+   * @param {string} oid - Prefix hash.
+   * @throws Throws error if tag does not exist.
+   */
   getTag(oid: string): Tag
   /**
    * Get a list with all the tags in the repository.
    *
-   * An optional fnmatch pattern can also be specified.
+   * @category Repository/Methods
+   * @signature
+   * ```ts
+   * class Repository {
+   *   tagNames(pattern?: string): string[];
+   * }
+   * ```
+   *
+   * @param {string} [pattern] - An optional fnmatch pattern can also be specified.
    */
   tagNames(pattern?: string | undefined | null): Array<string>
   /**
-   * iterate over all tags calling `callback` on each.
-   * the callback is provided the tag id and name
+   * Iterate over all tags calling `callback` on each.
+   * The callback is provided the tag id and name.
+   *
+   * @category Repository/Methods
+   * @signature
+   * ```ts
+   * class Repository {
+   *   tagForeach(callback: (oid: string, name: string) => boolean): void;
+   * }
+   * ```
+   *
+   * @param {(oid: string, name: string) => boolean} callback - If you wish to stop iteration,
+   * return `false` in the callback.
+   *
+   * @example
+   * ```ts
+   * 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']]
+   * ```
    */
   tagForeach(callback: (oid: string, name: string) => boolean): void
   /**
    * Delete an existing tag reference.
    *
-   * The tag name will be checked for validity, see `tag` for some rules
-   * about valid names.
+   * @category Repository/Methods
+   * @signature
+   * ```ts
+   * class Repository {
+   *   deleteTag(name: string): void;
+   * }
+   * ```
+   *
+   * @param {string} name - The tag name will be checked for validity, see `isValidTagName`
+   * for some rules about valid names.
    */
   deleteTag(name: string): void
   /**
-   * Create a new tag in the repository from an object
+   * Create a new tag in the repository from an object.
    *
-   * A new reference will also be created pointing to this tag object. If
-   * `force` is true and a reference already exists with the given name,
-   * it'll be replaced.
+   * A new reference will also be created pointing to this tag object.
    *
    * The message will not be cleaned up.
    *
    * The tag name will be checked for validity. You must avoid the characters
    * '~', '^', ':', ' \ ', '?', '[', and '*', and the sequences ".." and " @
    * {" which have special meaning to revparse.
+   *
+   * @category Repository/Methods
+   * @signature
+   * ```ts
+   * class Repository {
+   *   createTag(
+   *     name: string,
+   *     target: GitObject,
+   *     message: string,
+   *     options?: CreateTagOptions,
+   *   ): string;
+   * }
+   * ```
+   *
+   * @param {string} name - The name of tag.
+   * @param {GitObject} target - Git object to pointed by this tag.
+   * @param {string} message - The message of tag.
+   * @param {CreateTagOptions} [options] - Options for creating the tag.
+   *
+   * @returns Tag OID(SHA1) which created.
+   *
+   * @example
+   * ```ts
+   * 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"
+   * ```
    */
   createTag(name: string, target: GitObject, message: string, options?: CreateTagOptions | undefined | null): string
   /**
@@ -1468,30 +3933,87 @@ export declare class Repository {
    * The tag name will be checked for validity. You must avoid the characters
    * '~', '^', ':', ' \ ', '?', '[', and '*', and the sequences ".." and " @
    * {" which have special meaning to revparse.
+   *
+   * @category Repository/Methods
+   * @signature
+   * ```ts
+   * class Repository {
+   *   createAnnotationTag(
+   *     name: string,
+   *     target: GitObject,
+   *     message: string,
+   *     options?: CreateAnnotationTagOptions,
+   *   ): string;
+   * }
+   * ```
+   *
+   * @param {string} name - The name of tag.
+   * @param {GitObject} target - Git object to pointed by this tag.
+   * @param {string} message - The message of tag.
+   * @param {CreateAnnotationTagOptions} [options] - Options for creating the tag.
+   *
+   * @returns Tag OID(SHA1) which created.
    */
   createAnnotationTag(name: string, target: GitObject, message: string, options?: CreateAnnotationTagOptions | undefined | null): string
   /**
-   * Create a new lightweight tag pointing at a target object
+   * Create a new lightweight tag pointing at a target object.
    *
    * A new direct reference will be created pointing to this target object.
-   * If force is true and a reference already exists with the given name,
-   * it'll be replaced.
+   *
+   * @category Repository/Methods
+   * @signature
+   * ```ts
+   * class Repository {
+   *   createLightweightTag(
+   *     name: string,
+   *     target: GitObject,
+   *     options?: CreateLightweightTagOptions,
+   *   ): string;
+   * }
+   * ```
+   *
+   * @param {string} name - The name of tag.
+   * @param {GitObject} target - Git object to pointed by this tag.
+   * @param {CreateLightweightTagOptions} [options] - Options for creating the tag.
+   *
+   * @returns Tag OID(SHA1) which created.
    */
   createLightweightTag(name: string, target: GitObject, options?: CreateLightweightTagOptions | undefined | null): string
-  /** Lookup a reference to one of the objects in a repository. */
+  /**
+   * Lookup a reference to one of the objects in a repository.
+   *
+   * @category Repository/Methods
+   * @signature
+   * ```ts
+   * class Repository {
+   *   getTree(oid: string): Tree;
+   * }
+   * ```
+   *
+   * @param {string} oid - ID(SHA1) to lookup.
+   * @returns Git tree.
+   * @throws Throws error if tree does not exist.
+   */
   getTree(oid: string): Tree
   /**
    * Lookup a reference to one of the objects in a repository.
    *
-   * If it does not exists, returns `null`.
+   * @category Repository/Methods
+   * @signature
+   * ```ts
+   * class Repository {
+   *   findTree(oid: string): Tree | null;
+   * }
+   * ```
+   *
+   * @param {string} oid - ID(SHA1) to lookup.
+   * @returns If it does not exist, returns `null`.
    */
   findTree(oid: string): Tree | null
 }
 /**
  * A revwalk allows traversal of the commit graph defined by including one or
  * more leaves and excluding one or more roots.
- *
- * @hideconstructor
  */
 export declare class Revwalk {
   [Symbol.iterator](): Iterator<string, void, void>
@@ -1500,14 +4022,62 @@ export declare class Revwalk {
    *
    * The revwalk is automatically reset when iteration of its commits
    * completes.
+   *
+   * @category Revwalk/Methods
+   * @signature
+   * ```ts
+   * class Revwalk {
+   *   reset(): this;
+   * }
+   * ```
    */
   reset(): this
-  /** Set the order in which commits are visited. */
+  /**
+   * Set the order in which commits are visited.
+   *
+   * @category Revwalk/Methods
+   *
+   * @signature
+   * ```ts
+   * class Revwalk {
+   *   setSorting(sort: number): this;
+   * }
+   * ```
+   *
+   * @param {number} sort - Orderings that may be specified for Revwalk iteration.
+   * - `RevwalkSort.None` : Sort the repository contents in no particular ordering.
+   * This sorting is arbitrary, implementation-specific, and subject to
+   * change at any time. This is the default sorting for new walkers.
+   * - `RevwalkSort.Topological` : Sort the repository contents in topological order
+   * (children before parents).
+   * This sorting mode can be combined with time sorting.
+   * - `RevwalkSort.Time` : Sort the repository contents by commit time.
+   * This sorting mode can be combined with topological sorting.
+   * - `RevwalkSort.Reverse` : Iterate through the repository contents in reverse order.
+   * This sorting mode can be combined with any others.
+   *
+   * @example
+   * ```ts
+   * import { openRepository, RevwalkSort } from 'es-git';
+   *
+   * const repo = await openRepository('.');
+   * const revwalk = repo.revwalk();
+   * revwalk.setSorting(RevwalkSort.Time | RevwalkSort.Reverse);
+   * ```
+   */
   setSorting(sort: number): this
   /**
-   * Simplify the history by first-parent
+   * Simplify the history by first-parent.
    *
    * No parents other than the first for each commit will be enqueued.
+   *
+   * @category Revwalk/Methods
+   * @signature
+   * ```ts
+   * class Revwalk {
+   *   simplifyFirstParent(): this;
+   * }
+   * ```
    */
   simplifyFirstParent(): this
   /**
@@ -1518,23 +4088,46 @@ export declare class Revwalk {
    * The given commit will be used as one of the roots when starting the
    * revision walk. At least one commit must be pushed onto the walker before
    * a walk can be started.
+   *
+   * @category Revwalk/Methods
+   * @signature
+   * ```ts
+   * class Revwalk {
+   *   push(oid: string): this;
+   * }
+   * ```
+   *
+   * @param {string} oid - OID which belong to a commitish on the walked repository.
    */
   push(oid: string): this
   /**
-   * Push the repository's HEAD
+   * Push the repository's HEAD.
    *
-   * For more information, see `push`.
+   * @category Revwalk/Methods
+   * @signature
+   * ```ts
+   * class Revwalk {
+   *   pushHead(): this;
+   * }
+   * ```
    */
   pushHead(): this
   /**
-   * Push matching references
+   * Push matching references.
    *
    * The OIDs pointed to by the references that match the given glob pattern
    * will be pushed to the revision walker.
    *
-   * A leading 'refs/' is implied if not present as well as a trailing `/ \
-   * *` if the glob lacks '?', ' \ *' or '['.
+   * @category Revwalk/Methods
+   * @signature
+   * ```ts
+   * class Revwalk {
+   *   pushGlob(glob: string): this;
+   * }
+   * ```
    *
+   * @param {string} glob - A leading 'refs/' is implied if not present as well as a trailing `/ \
+   * *` if the glob lacks '?', ' \ *' or '['.
    * Any references matching this glob which do not point to a commitish
    * will be ignored.
    */
@@ -1542,23 +4135,57 @@ export declare class Revwalk {
   /**
    * Push and hide the respective endpoints of the given range.
    *
-   * The range should be of the form `<commit>..<commit>` where each
-   * `<commit>` is in the form accepted by `revparse_single`. The left-hand
+   * @category Revwalk/Methods
+   * @signature
+   * ```ts
+   * class Revwalk {
+   *   pushRange(range: string): this;
+   * }
+   * ```
+   *
+   * @param {string} range - The range should be of the form `<commit>..<commit>` where each
+   * `<commit>` is in the form accepted by `revparseSingle`. The left-hand
    * commit will be hidden and the right-hand commit pushed.
    */
   pushRange(range: string): this
   /**
-   * Push the OID pointed to by a reference
+   * Push the OID pointed to by a reference.
    *
-   * The reference must point to a commitish.
+   * @category Revwalk/Methods
+   * @signature
+   * ```ts
+   * class Revwalk {
+   *   pushRef(reference: string): this;
+   * }
+   * ```
+   *
+   * @param {string} reference - The reference must point to a commitish.
    */
   pushRef(reference: string): this
-  /** Mark a commit as not of interest to this revwalk. */
+  /**
+   * Mark a commit as not of interest to this revwalk.
+   *
+   * @category Revwalk/Methods
+   * @signature
+   * ```ts
+   * class Revwalk {
+   *   hide(oid: string): this;
+   * }
+   * ```
+   *
+   * @param {string} oid - Marked commit OID as not of interest of this revwalk.
+   */
   hide(oid: string): this
   /**
-   * Hide the repository's HEAD
+   * Hide the repository's HEAD.
    *
-   * For more information, see `hide`.
+   * @category Revwalk/Methods
+   * @signature
+   * ```ts
+   * class Revwalk {
+   *   hideHead(): this;
+   * }
+   * ```
    */
   hideHead(): this
   /**
@@ -1567,9 +4194,16 @@ export declare class Revwalk {
    * The OIDs pointed to by the references that match the given glob pattern
    * and their ancestors will be hidden from the output on the revision walk.
    *
-   * A leading 'refs/' is implied if not present as well as a trailing `/ \
-   * *` if the glob lacks '?', ' \ *' or '['.
+   * @category Revwalk/Methods
+   * @signature
+   * ```ts
+   * class Revwalk {
+   *   hideGlob(glob: string): this;
+   * }
+   * ```
    *
+   * @param {string} glob - A leading 'refs/' is implied if not present as well as a trailing `/ \
+   * *` if the glob lacks '?', ' \ *' or '['.
    * Any references matching this glob which do not point to a commitish
    * will be ignored.
    */
@@ -1577,120 +4211,381 @@ export declare class Revwalk {
   /**
    * Hide the OID pointed to by a reference.
    *
-   * The reference must point to a commitish.
+   * @category Revwalk/Methods
+   * @signature
+   * ```ts
+   * class Revwalk {
+   *   hideRef(reference: string): this;
+   * }
+   * ```
+   *
+   * @param {string} reference - The reference must point to a commitish.
    */
   hideRef(reference: string): this
 }
 /**
- * A structure to represent a git [tag][1]
- * @hideconstructor
+ * A class to represent a git [tag][1].
  *
- * [1]: http://git-scm.com/book/en/Git-Basics-Tagging
+ * [1]: https://git-scm.com/book/en/Git-Basics-Tagging
  */
 export declare class Tag {
-  /** Get the id (SHA1) of a repository tag */
+  /**
+   * Get the id (SHA1) of a repository tag.
+   *
+   * @category Tag/Methods
+   * @signature
+   * ```ts
+   * class Tag {
+   *   id(): string;
+   * }
+   * ```
+   *
+   * @returns ID(SHA1) of this tag.
+   */
   id(): string
   /**
-   * Get the message of a tag
+   * Get the message of a tag.
    *
-   * Returns `null`` if there is no message or if it is not valid utf8
+   * @category Tag/Methods
+   * @signature
+   * ```ts
+   * class Tag {
+   *   message(): string | null;
+   * }
+   * ```
+   *
+   * @returns Returns `null` if there is no message or if it is not valid utf8.
    */
   message(): string | null
   /**
-   * Get the name of a tag
+   * Get the name of a tag.
+   *
+   * @category Tag/Methods
+   * @signature
+   * ```ts
+   * class Tag {
+   *   name(): string;
+   * }
+   * ```
    *
-   * Throws error if it is not valid utf8
+   * @returns Name of tag.
+   * @throws Throws error if it is not valid utf8.
    */
   name(): string
-  /** Recursively peel a tag until a non tag git_object is found */
+  /**
+   * Recursively peel a tag until a non tag Git object is found.
+   *
+   * @category Tag/Methods
+   * @signature
+   * ```ts
+   * class Tag {
+   *   peel(): GitObject;
+   * }
+   * ```
+   *
+   * @returns Git object for this tag.
+   */
   peel(): GitObject
   /**
-   * Get the tagger (author) of a tag
+   * Get the tagger (author) of a tag.
    *
-   * If the author is unspecified, then `null` is returned.
+   * @category Tag/Methods
+   * @signature
+   * ```ts
+   * class Tag {
+   *   tagger(): Signature | null;
+   * }
+   * ```
+   *
+   * @returns If the author is unspecified, then `null` is returned.
    */
   tagger(): Signature | null
   /**
-   * Get the tagged object of a tag
+   * Get the tagged object of a tag.
    *
    * This method performs a repository lookup for the given object and
-   * returns it
+   * returns it.
+   *
+   * @category Tag/Methods
+   * @signature
+   * ```ts
+   * class Tag {
+   *   target(): GitObject;
+   * }
+   * ```
+   *
+   * @returns Tagged git object of a tag.
    */
   target(): GitObject
-  /** Get the OID of the tagged object of a tag */
+  /**
+   * Get the OID of the tagged object of a tag.
+   *
+   * @category Tag/Methods
+   * @signature
+   * ```ts
+   * class Tag {
+   *   targetId(): string;
+   * }
+   * ```
+   *
+   * @returns OID of the tagged object of a tag.
+   */
   targetId(): string
-  /** Get the ObjectType of the tagged object of a tag */
+  /**
+   * Get the ObjectType of the tagged object of a tag.
+   *
+   * @category Tag/Methods
+   * @signature
+   * ```ts
+   * class Tag {
+   *   targetType(): ObjectType | null;
+   * }
+   * ```
+   *
+   * @returns ObjectType of the tagged object of a tag.
+   */
   targetType(): ObjectType | null
 }
 /**
- * A structure to represent a git [tree][1]
- * @hideconstructor
+ * A class to represent a git [tree][1].
  *
- * [1]: http://git-scm.com/book/en/Git-Internals-Git-Objects
+ * [1]: https://git-scm.com/book/en/Git-Internals-Git-Objects
  */
 export declare class Tree {
-  /** Get the id (SHA1) of a repository object */
+  /**
+   * Get the id (SHA1) of a repository object.
+   *
+   * @category Tree/Methods
+   * @signature
+   * ```ts
+   * class Tree {
+   *   id(): string;
+   * }
+   * ```
+   *
+   * @returns ID(SHA1) of a repository object.
+   */
   id(): string
-  /** Get the number of entries listed in this tree. */
+  /**
+   * Get the number of entries listed in this tree.
+   *
+   * @category Tree/Methods
+   * @signature
+   * ```ts
+   * class Tree {
+   *   len(): bigint;
+   * }
+   * ```
+   *
+   * @returns The number of entries listed in this tree.
+   */
   len(): bigint
-  /** Return `true` if there is not entry */
+  /**
+   * @category Tree/Methods
+   * @signature
+   * ```ts
+   * class Tree {
+   *   isEmpty(): boolean;
+   * }
+   * ```
+   *
+   * @returns Return `true` if there is no entry.
+   */
   isEmpty(): boolean
-  /** Returns an iterator over the entries in this tree. */
+  /**
+   * Returns an iterator over the entries in this tree.
+   *
+   * @category Tree/Methods
+   * @signature
+   * ```ts
+   * class Tree {
+   *   iter(): TreeIter;
+   * }
+   * ```
+   *
+   * @returns An iterator over the entries in this tree.
+   */
   iter(): TreeIter
   /**
    * Traverse the entries in a tree and its subtrees in post or pre-order.
-   * The callback function will be run on each node of the tree that's
-   * walked. The return code of this function will determine how the walk
-   * continues.
    *
-   * libgit2 requires that the callback be an integer, where 0 indicates a
-   * successful visit, 1 skips the node, and -1 aborts the traversal completely.
-   * See [libgit2 documentation][1] for more information.
+   * @category Tree/Methods
+   * @signature
+   * ```ts
+   * class Tree {
+   *   walk(mode: TreeWalkMode, callback: (entry: TreeEntry) => number): void;
+   * }
+   * ```
+   *
+   * @param {TreeWalkMode} mode - A indicator of whether a tree walk should be performed
+   * in pre-order or post-order.
    *
-   * [1]: https://libgit2.org/libgit2/#HEAD/group/tree/git_tree_walk
+   * @param {(entry: TreeEntry) => number} callback - The callback function will be run on
+   * each node of the tree that's walked. The return code of this function will determine
+   * how the walk continues.
+   * `libgit2` requires that the callback be an integer, where 0 indicates a successful visit,
+   * 1 skips the node, and -1 aborts the traversal completely.
    */
   walk(mode: TreeWalkMode, callback: (entry: TreeEntry) => number): void
-  /** Lookup a tree entry by SHA value. */
+  /**
+   * Lookup a tree entry by SHA value.
+   *
+   * @category Tree/Methods
+   * @signature
+   * ```ts
+   * class Tree {
+   *   getId(id: string): TreeEntry | null;
+   * }
+   * ```
+   *
+   * @param {string} id - SHA value.
+   *
+   * @returns Tree entry with the given ID(SHA1).
+   */
   getId(id: string): TreeEntry | null
-  /** Lookup a tree entry by its position in the tree */
+  /**
+   * Lookup a tree entry by its position in the tree.
+   *
+   * @category Tree/Methods
+   * @signature
+   * ```ts
+   * class Tree {
+   *   get(index: number): TreeEntry | null;
+   * }
+   * ```
+   *
+   * @param {number} index - Index of tree entry.
+   *
+   * @returns Tree entry.
+   */
   get(index: number): TreeEntry | null
-  /** Lookup a tree entry by its filename */
+  /**
+   * Lookup a tree entry by its filename.
+   *
+   * @category Tree/Methods
+   * @signature
+   * ```ts
+   * class Tree {
+   *   getName(filename: string): TreeEntry | null;
+   * }
+   * ```
+   *
+   * @param {string} filename - Filename of tree entry.
+   *
+   * @returns Tree entry.
+   */
   getName(filename: string): TreeEntry | null
   /**
    * Retrieve a tree entry contained in a tree or in any of its subtrees,
    * given its relative path.
+   *
+   * @category Tree/Methods
+   * @signature
+   * ```ts
+   * class Tree {
+   *   getPath(path: string): TreeEntry | null;
+   * }
+   * ```
+   *
+   * @param {string} path - Relative path to tree entry.
+   *
+   * @returns Tree entry.
    */
   getPath(path: string): TreeEntry | null
-  /** Casts this Tree to be usable as an `GitObject` */
+  /**
+   * Casts this Tree to be usable as an `GitObject`.
+   *
+   * @category Tree/Methods
+   * @signature
+   * ```ts
+   * class Tree {
+   *   asObject(): GitObject;
+   * }
+   * ```
+   *
+   * @returns Git object.
+   */
   asObject(): GitObject
 }
-/**
- * An iterator over the entries in a tree.
- *
- * @hideconstructor
- */
+/** An iterator over the entries in a tree. */
 export declare class TreeIter {
   [Symbol.iterator](): Iterator<TreeEntry, void, void>
 }
 /**
- * A structure representing an entry inside of a tree. An entry is borrowed
+ * A class representing an entry inside of a tree. An entry is borrowed
  * from a tree.
- *
- * @hideconstructor
  */
 export declare class TreeEntry {
-  /** Get the id of the object pointed by the entry */
+  /**
+   * Get the id of the object pointed by the entry.
+   *
+   * @category Tree/TreeEntry
+   * @signature
+   * ```ts
+   * class TreeEntry {
+   *   id(): string;
+   * }
+   * ```
+   *
+   * @returns ID of the object pointed by the entry.
+   */
   id(): string
   /**
-   * Get the filename of a tree entry
+   * Get the filename of a tree entry.
+   *
+   * @category Tree/TreeEntry
+   * @signature
+   * ```ts
+   * class TreeEntry {
+   *   name(): string;
+   * }
+   * ```
    *
-   * Throws error if the name is not valid utf-8
+   * @returns The filename of a tree entry.
+   * @throws Throws error if the name is not valid utf-8.
    */
   name(): string
-  /** Get the type of the object pointed by the entry */
+  /**
+   * Get the type of the object pointed by the entry.
+   *
+   * @category Tree/TreeEntry
+   * @signature
+   * ```ts
+   * class TreeEntry {
+   *   type(): ObjectType | null;
+   * }
+   * ```
+   *
+   * @returns The type of the object pointed by the entry.
+   */
   type(): ObjectType | null
-  /** Get the UNIX file attributes of a tree entry */
+  /**
+   * Get the UNIX file attributes of a tree entry.
+   *
+   * @category Tree/TreeEntry
+   * @signature
+   * ```ts
+   * class TreeEntry {
+   *   filemode(): number;
+   * }
+   * ```
+   *
+   * @returns UNIX file attributes of a tree entry.
+   */
   filemode(): number
-  /** Convert a tree entry to the object it points to. */
+  /**
+   * Convert a tree entry to the object it points to.
+   *
+   * @category Tree/TreeEntry
+   * @signature
+   * ```ts
+   * class TreeEntry {
+   *   toObject(repo: Repository): GitObject;
+   * }
+   * ```
+   *
+   * @param {Repository} repo - Repository which this tree entry belongs to.
+   * @returns Git object that pointed by the entry.
+   */
   toObject(repo: Repository): GitObject
 }