fluent-git

Fluent Git

Features:

• git-notes basic subcommand (add, remove, show, etc) with handler:
  • atCommit()
  • atFile()
  • atFolder()
  • atSubmodule()
  • atTag()
• git-log...
  • search and list notes
  • search and list commit
• git-checkout...
• git-hooks...

Getting Started

To begin, you'll need to install fluent-git:

npm install fluent-git

or if you use yarn

yarn add fluent-git

git-notes ^[man]

^{tl;dr -- see example on each operation or handler}

import { notes } from "fluent-git";

notes([text|][,options]) is a function that take 2 arguments and both of them are optional:

• text - string that can be either SHA-1, HEAD, or notes.
• options - string that point to --ref. Or Object which represent the Options.

When text is undefined

notes()[handler](...)[operation](...)
// or
notes({
  ...Options
})[handler](...)[operation](...)

// in case you need autocompletion in typescript
const $notes = notes() as NoteUse.Manually

• Available operation: add, overwriteWith, copyFrom, append, remove, show
• Available handler: at, atCommit, atFile, atFolder

When text is a notes (not identified as string HEAD or hash)

notes('some long notes')[operation][handler](...)

// in case you need autocompletion in typescript
const $notes = notes('some long notes') as NoteUse.Text

• Available operation: add, overwrite, copy, append
• Available handler: at, atCommit, atFile, atFolder

When text is a hash string

const sha = '69f3c3d' // or 'HEAD'
notes(sha)[operation](...)

// in case you need autocompletion in typescript
const $notes = notes('69f3c3d') as NoteUse.Hash

• Available operation: add, overwriteWith, copyFrom, append, remove, show
• Available handler: at, atCommit, atFile, atFolder

Operation

add

Add notes on specific git-object (commit, blob/file, tree/folder, submodule, or tag)

• Arguments: string
• Expected value: any string that represent notes but it can not be hash string or word HEAD
• Return: ~

Example

notes().at(sha).add("some long notes");
notes("some long notes").add.at(sha);
notes("af23339").add("some long notes");

remove

Remove notes on specific git-object (commit, blob/file, tree/folder, submodule, or tag)

• Arguments: ~
• Expected value: ~
• Return: ~

Example

notes().at(sha).remove();
notes("af23339").remove();

show

Read notes on specific git-object (commit, blob/file, tree/folder, submodule, or tag)

• Arguments: ~
• Expected value: ~
• Return: string

Example

mynotes1 = notes().at(sha).show();
mynotes2 = notes("af23339").show();
console.log(String(mynotes1 + "\n" + mynotes2));

append

Append notes on specific git-object (commit, blob/file, tree/folder, submodule, or tag) that has/hasn't a notes.

• Arguments: string
• Expected value: any string that represent notes but it can not be hash string or word HEAD
• Return: ~

Example

notes().at(sha).append("some long notes");
notes("some long notes").append.at(sha);
notes("af23339").append("some long notes");

overwrite or overwriteWith

Overwrite notes on specific git-object (commit, blob/file, tree/folder, submodule, or tag). The source can be notes on another git-object or provided manually

• Arguments: string
• Expected value: any string that represent notes, hash string, or word HEAD
• Return: ~

Example

const sourceNotes = "HEAD";
notes().at(sha).overwriteWith("some long notes");
notes().at(sha).overwriteWith(sourceNotes);
notes("some long notes").overwrite.at(sha);
notes("af23339").overwriteWith("some long notes");
notes("af23339").overwriteWith(sourceNotes);

copy or copyFrom

Copy notes from git-object (commit, blob/file, tree/folder, submodule, or tag) to another git-object.

• Arguments: string
• Expected value: must be hash string or word HEAD
• Return: ~

Example

notes().at(sha).copyFrom("b0279ab");
notes("some long notes").copy.at("af23339"); // same as `add` operation
notes("af23339").copyFrom("b0279ab");

Handler

at(sha)

• Arguments: string
• Expected value: must be hash string or word HEAD

Example

notes().at("af23339").show();
notes().at("HEAD").show();

atCommit(message)

• Arguments: string
• Expected value: must be valid commit message

Example

notes().atCommit("Initial commit").show();

atFile(filename, commit)

• Arguments:
  • filename - string
  • commit - string
• Expected value:
  • commit - commit message or commit-id (SHA-1)
  • filename - a valid filename of that specific commit. Can include relative path (without ./) but not with absolute path

Example

notes().atFile("README.md", "Initial commit").show();
notes().atFile("README.md", "af23339").show();
notes().atFile("packages/mod1/README.md", "HEAD").show();

atFolder(folder, commit)

• Arguments:
  • folder - string
  • commit - string
• Expected value:
  • commit - commit message or commit-id (SHA-1)
  • folder - a valid folder of that specific commit. Must be relative path without prefix ./ and suffix '/'

Example

notes().atFolder("src", "Initial commit").show();
notes().atFolder("src", "af23339").show();
notes().atFolder("packages/mod1/src", "HEAD").show();

Options

The options are the combination of execa options plus this:

{
  ref: String; // represent flag --ref in git-notes
}

Who use this?

• guc-desktop
• [add yours 😉]

Contributing

• CONTRIBUTING.md for how you can make contribution
• HACKING.md for technical details

License