Fluent Git

Features:

• [x] git-notes basic subcommand (add, remove, show, etc) with handler:
  • [x] atCommit()
  • [x] atFile()
  • [x] 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.

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

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

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

• 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");

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

Example

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

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

Example

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

• 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");

• 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);

• 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

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

Example

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

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

Example

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

• 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();

• 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