es-git 0.5.0-next.162 → 0.5.0-next.164

package/index.d.ts

@@ -1083,6 +1083,28 @@ export declare class Deltas extends Iterator<DiffDelta, void, void> {
   next(value?: void): IteratorResult<DiffDelta, void>
 }
 
+/**
+ * The result of a `describe` operation on either an `Describe` or a
+ * `Repository`.
+ */
+export declare class Describe {
+  /**
+   * Prints this describe result, returning the result as a string.
+   *
+   * @category Describe/Methods
+   * @signature
+   * ```ts
+   * class Describe {
+   *   format(options?: DescribeFormatOptions | null | undefined): string;
+   * }
+   * ```
+   *
+   * @param {DescribeFormatOptions} [options] - Options for formatting describe.
+   * @returns Formatted string for this describe.
+   */
+  format(options?: DescribeFormatOptions | undefined | null): string
+}
+
 /**
  * The diff object that contains all individual file deltas.
  *
@@ -1530,6 +1552,23 @@ export declare class GitObject {
    * @returns Returns `null` if the object is not actually a commit.
    */
   asCommit(): Commit | null
+  /**
+   * Describes a commit
+   *
+   * Performs a describe operation on this commitish object.
+   *
+   * @category GitObject/Methods
+   * @signature
+   * ```ts
+   * class Object {
+   *   describe(options?: DescribeOptions | null | undefined): Describe;
+   * }
+   * ```
+   *
+   * @param {DescribeOptions} [options] - Options for describe operation.
+   * @returns Instance of describe.
+   */
+  describe(options?: DescribeOptions | undefined | null): Describe
 }
 
 /**
@@ -1895,6 +1934,85 @@ export declare class Mailmap {
   resolveSignature(signature: SignaturePayload): Signature
 }
 
+/**
+ * A structure representing a [note][1] in git.
+ *
+ * [1]: http://alblue.bandlem.com/2011/11/git-tip-of-week-git-notes.html
+ */
+export declare class Note {
+  /**
+   * Get the note object's id
+   *
+   * @category Note/Methods
+   * @signature
+   * ```ts
+   * class Note {
+   *   id(): string;
+   * }
+   * ```
+   *
+   * @returns The note object's id.
+   */
+  id(): string
+  /**
+   * Get the note author
+   *
+   * @category Note/Methods
+   * @signature
+   * ```ts
+   * class Note {
+   *   author(): Signature;
+   * }
+   * ```
+   *
+   * @returns The note author signature.
+   */
+  author(): Signature
+  /**
+   * Get the note committer
+   *
+   * @category Note/Methods
+   * @signature
+   * ```ts
+   * class Note {
+   *   committer(): Signature;
+   * }
+   * ```
+   *
+   * @returns The note committer signature.
+   */
+  committer(): Signature
+  /**
+   * Get the note message as a string.
+   *
+   * @category Note/Methods
+   * @signature
+   * ```ts
+   * class Note {
+   *   message(): string;
+   * }
+   * ```
+   *
+   * @returns The note message as a string
+   * @throws Throws error if message is not utf-8.
+   */
+  message(): string
+}
+
+/**
+ * An iterator over all of the notes within a repository.
+ *
+ * This type extends JavaScript's `Iterator`, and so has the iterator helper
+ * methods. It may extend the upcoming TypeScript `Iterator` class in the future.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Iterator#iterator_helper_methods
+ * @see https://www.typescriptlang.org/docs/handbook/release-notes/typescript-5-6.html#iterator-helper-methods
+ */
+export declare class Notes extends Iterator<NoteIterItem, void, void> {
+
+  next(value?: void): IteratorResult<NoteIterItem, void>
+}
+
 /**
  * Representation of a rebase
  * Begin the rebase by iterating the returned `Rebase`
@@ -3218,6 +3336,134 @@ export declare class Repository {
    * @returns Merge analysis result.
    */
   analyzeMergeForRef(ourRef: Reference, theirHeads: Array<AnnotatedCommit>): MergeAnalysisResult
+  /**
+   * Add a note for an object
+   *
+   * The `notesRef` argument is the canonical name of the reference to use,
+   * defaulting to "refs/notes/commits". If `force` is specified then
+   * previous notes are overwritten.
+   *
+   * @category Repository/Methods
+   * @signature
+   * ```ts
+   * class Repository {
+   *   note(oid: string, note: string, options?: CreateNoteOptions | null | undefined): string;
+   * }
+   * ```
+   *
+   * @param {string} oid - OID of the git object to decorate.
+   * @param {string} note - Content of the note to add for object oid.
+   * @param {CreateNoteOptions} [options] - Options for creating note.
+   * @returns OID for the note.
+   */
+  note(oid: string, note: string, options?: CreateNoteOptions | undefined | null): string
+  /**
+   * Get the default notes reference for this repository
+   *
+   * @category Repository/Methods
+   * @signature
+   * ```ts
+   * class Repository {
+   *   noteDefaultRef(): string;
+   * }
+   * ```
+   *
+   * @returns The default notes reference.
+   */
+  noteDefaultRef(): string
+  /**
+   * Creates a new iterator for notes in this repository.
+   *
+   * The `notesRef` argument is the canonical name of the reference to use,
+   * defaulting to "refs/notes/commits".
+   *
+   * @category Repository/Methods
+   * @signature
+   * ```ts
+   * class Repository {
+   *   notes(notesRef?: string | null | undefined): Notes;
+   * }
+   * ```
+   *
+   * @param {string} [notesRef] - The canonical name of the reference to use.
+   * @returns Iterator of all notes. The iterator returned yields pairs of `[string, string]`
+   * where first element is the id of the note and the second id is the id the note is annotating.
+   *
+   * @example
+   * ```ts
+   * import { openRepository } from 'es-git';
+   *
+   * const repo = await openRepository('.');
+   * for (const { noteId, annotatedId } of repo.notes()) {
+   *   const note = repo.getNote(noteId);
+   *   const commit = repo.getCommit(annotatedId);
+   * }
+   * ```
+   */
+  notes(notesRef?: string | undefined | null): Notes
+  /**
+   * Read the note for an object.
+   *
+   * The `notesRef` argument is the canonical name of the reference to use,
+   * defaulting to "refs/notes/commits".
+   *
+   * The id specified is the Oid of the git object to read the note from.
+   *
+   * @category Repository/Methods
+   * @signature
+   * ```ts
+   * class Repository {
+   *   getNote(id: string, options?: FindNoteOptions | null | undefined): Note;
+   * }
+   * ```
+   *
+   * @param {string} id - OID of the git object to read the note from.
+   * @param {FindNoteOptions} [options] - Options for finding note.
+   * @returns Instance of the note.
+   * @throws Throws error if note does not exists.
+   */
+  getNote(id: string, options?: FindNoteOptions | undefined | null): Note
+  /**
+   * Read the note for an object.
+   *
+   * The `notesRef` argument is the canonical name of the reference to use,
+   * defaulting to "refs/notes/commits".
+   *
+   * The id specified is the Oid of the git object to read the note from.
+   *
+   * @category Repository/Methods
+   * @signature
+   * ```ts
+   * class Repository {
+   *   findNote(id: string, options?: FindNoteOptions | null | undefined): Note | null;
+   * }
+   * ```
+   *
+   * @param {string} id - OID of the git object to read the note from.
+   * @param {FindNoteOptions} [options] - Options for finding note.
+   * @returns Instance of the note. If does not exists, returns `null`.
+   */
+  findNote(id: string, options?: FindNoteOptions | undefined | null): Note | null
+  /**
+   * Remove the note for an object.
+   *
+   * The `notesRef` argument is the canonical name of the reference to use,
+   * defaulting to "refs/notes/commits".
+   *
+   * The id specified is the Oid of the git object to remove the note from.
+   *
+   * @category Repository/Methods
+   * @signature
+   * ```ts
+   * class Repository {
+   *   deleteNote(id: string, options?: DeleteNoteOptions | null | undefined): void;
+   * }
+   * ```
+   *
+   * @param {string} id - OID of the git object to remove the note from.
+   * @param {DeleteNoteOptions} [options] - Options for deleting note.
+   */
+  deleteNote(id: string, options?: DeleteNoteOptions | undefined | null): void
   /**
    * Lookup a reference to one of the objects in a repository.
    *
@@ -4338,6 +4584,25 @@ export declare class Repository {
    * @returns If it does not exist, returns `null`.
    */
   findTree(oid: string): Tree | null
+  /**
+   * Describes a commit
+   *
+   * Performs a describe operation on the current commit and the worktree.
+   * After performing a describe on `HEAD`, a status is run and description is
+   * considered to be dirty if there are.
+   *
+   * @category Repository/Methods
+   * @signature
+   * ```ts
+   * class Repository {
+   *   describe(options?: DescribeOptions | null | undefined): Describe;
+   * }
+   * ```
+   *
+   * @param {DescribeOptions} [options] - Options for describe operation.
+   * @returns Instance of describe.
+   */
+  describe(options?: DescribeOptions | undefined | null): Describe
 }
 
 /**
@@ -5734,6 +5999,31 @@ export interface CreateLightweightTagOptions {
  */
 export declare function createMailmapFromBuffer(content: string): Mailmap
 
+export interface CreateNoteOptions {
+  /**
+   * Signature of the notes commit author.
+   *
+   * 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 of the notes commit commiter.
+   *
+   * 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
+  /**
+   * canonical name of the reference to use.
+   *
+   * Defaults to "refs/notes/commits".
+   */
+  notesRef?: string
+  /** Overwrite existing note. */
+  force?: boolean
+}
+
 export interface CreateRemoteOptions {
   fetchRefspec?: string
 }
@@ -5811,6 +6101,29 @@ export type CredentialType =  'Default'|
 'SSHKey'|
 'Plain';
 
+export interface DeleteNoteOptions {
+  /**
+   * Signature of the notes commit author.
+   *
+   * 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 of the notes commit commiter.
+   *
+   * 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
+  /**
+   * canonical name of the reference to use.
+   *
+   * Defaults to "refs/notes/commits".
+   */
+  notesRef?: string
+}
+
 /**
  * - `Unmodified` : No changes.
  * - `Added` : Entry does not exist in an old version.
@@ -5836,6 +6149,54 @@ export type DeltaType =  'Unmodified'|
 'Unreadable'|
 'Conflicted';
 
+export interface DescribeFormatOptions {
+  /**
+   * Sets the size of the abbreviated commit id to use.
+   *
+   * The value is the lower bound for the length of the abbreviated string,
+   * and the default is 7.
+   */
+  abbreviatedSize?: number
+  /**
+   * Sets whether or not the long format is used even when a shorter name
+   * could be used.
+   */
+  alwaysUseLongFormat?: boolean
+  /**
+   * If the workdir is dirty and this is set, this string will be appended to
+   * the description string.
+   */
+  dirtySuffix?: string
+}
+
+export interface DescribeOptions {
+  maxCandidatesTags?: number
+  /**
+   * Sets the reference lookup strategy
+   *
+   * This behaves like the `--tags` option to git-describe.
+   */
+  describeTags?: boolean
+  /**
+   * Sets the reference lookup strategy
+   *
+   * This behaves like the `--all` option to git-describe.
+   */
+  describeAll?: boolean
+  /**
+   * Indicates when calculating the distance from the matching tag or
+   * reference whether to only walk down the first-parent ancestry.
+   */
+  onlyFollowFirstParent?: boolean
+  /**
+   * If no matching tag or reference is found whether a describe option would
+   * normally fail. This option indicates, however, that it will instead fall
+   * back to showing the full id of the commit.
+   */
+  showCommitOidAsFallback?: boolean
+  pattern?: string
+}
+
 export interface DiffFindOptions {
   /** Look for renames? */
   renames?: boolean
@@ -6250,6 +6611,10 @@ export type FileMode =  'Unreadable'|
  */
 export declare function findGlobalConfigPath(): string | null
 
+export interface FindNoteOptions {
+  notesRef?: string
+}
+
 /**
  * Locate the path to the system configuration file.
  *
@@ -6722,6 +7087,11 @@ export interface MergePreference {
  */
 export declare function normalizeReferenceName(refname: string, format?: number | undefined | null): string | null
 
+export interface NoteIterItem {
+  noteId: string
+  annotatedId: string
+}
+
 /**
  * - `Any` : Any kind of git object
  * - `Commit` : An object which corresponds to a git commit

package/index.js

@@ -583,6 +583,7 @@ module.exports.Commit = nativeBinding.Commit
 module.exports.Config = nativeBinding.Config
 module.exports.ConfigEntries = nativeBinding.ConfigEntries
 module.exports.Deltas = nativeBinding.Deltas
+module.exports.Describe = nativeBinding.Describe
 module.exports.Diff = nativeBinding.Diff
 module.exports.DiffDelta = nativeBinding.DiffDelta
 module.exports.DiffFile = nativeBinding.DiffFile
@@ -591,6 +592,8 @@ module.exports.GitObject = nativeBinding.GitObject
 module.exports.Index = nativeBinding.Index
 module.exports.IndexEntries = nativeBinding.IndexEntries
 module.exports.Mailmap = nativeBinding.Mailmap
+module.exports.Note = nativeBinding.Note
+module.exports.Notes = nativeBinding.Notes
 module.exports.Rebase = nativeBinding.Rebase
 module.exports.Reference = nativeBinding.Reference
 module.exports.Remote = nativeBinding.Remote

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "es-git",
-  "version": "0.5.0-next.162+202d872",
+  "version": "0.5.0-next.164+3f0c3d0",
   "main": "index.js",
   "types": "index.d.ts",
   "files": [
@@ -54,15 +54,15 @@
     "vitest": "^3.0.5"
   },
   "optionalDependencies": {
-    "es-git-darwin-x64": "0.5.0-next.162+202d872",
-    "es-git-darwin-arm64": "0.5.0-next.162+202d872",
-    "es-git-win32-x64-msvc": "0.5.0-next.162+202d872",
-    "es-git-win32-arm64-msvc": "0.5.0-next.162+202d872",
-    "es-git-linux-x64-gnu": "0.5.0-next.162+202d872",
-    "es-git-linux-x64-musl": "0.5.0-next.162+202d872",
-    "es-git-android-arm64": "0.5.0-next.162+202d872",
-    "es-git-linux-arm64-gnu": "0.5.0-next.162+202d872",
-    "es-git-linux-arm64-musl": "0.5.0-next.162+202d872",
-    "es-git-android-arm-eabi": "0.5.0-next.162+202d872"
+    "es-git-darwin-x64": "0.5.0-next.164+3f0c3d0",
+    "es-git-darwin-arm64": "0.5.0-next.164+3f0c3d0",
+    "es-git-win32-x64-msvc": "0.5.0-next.164+3f0c3d0",
+    "es-git-win32-arm64-msvc": "0.5.0-next.164+3f0c3d0",
+    "es-git-linux-x64-gnu": "0.5.0-next.164+3f0c3d0",
+    "es-git-linux-x64-musl": "0.5.0-next.164+3f0c3d0",
+    "es-git-android-arm64": "0.5.0-next.164+3f0c3d0",
+    "es-git-linux-arm64-gnu": "0.5.0-next.164+3f0c3d0",
+    "es-git-linux-arm64-musl": "0.5.0-next.164+3f0c3d0",
+    "es-git-android-arm-eabi": "0.5.0-next.164+3f0c3d0"
   }
 }