In-memory git-like interface for managing content
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
src
.gitignore
.npmignore
LICENSE
README.md
alfred.png
gitfred.min.js
package.json
yarn.lock

README.md

Gitfred

Gitfred

In-memory git-like library for managing textual content.

I've made the library as part of my work on poet.codes where I need to store multiple files and their different versions. Storing all the content every time simply doesn't scale so I needed a smarter approach. Something like Git but running in the browser. It needed to be lightweight and to provide similar diff/patch experience. That's what Gitfred is.


Installation

npm install gitfred / yarn add gitfred

or directly using https://unpkg.com/gitfred

Usage

const git = gitfred();

git.save("foo.js", { content: "hello winter" });

We have no commits yet, but we have our file in the working directory. If we run git.export() we'll see the following:

{
  "commits": {},
  "stage": [],
  "working": [
    [
      "foo.js",
      { "content": "hello winter" }
    ]
  ],
  "head": null
}

Let's stage our file.

git.add('foo.js');

No we have our file staged. The working directory and our staging area contain the same information.

{
  "commits": {},
  "stage": [
    [
      "foo.js",
      { "content": "hello winter" }
    ]
  ],
  "working": [
    [
      "foo.js",
      { "content": "hello winter" }
    ]
  ],
  "head": null
}

Let's make our first commit:

git.commit('first commit');

We just created a new commit with a hash equal to _1. There is nothing in our staging area and head now points to our first commit.

{
  "commits": {
    "_1": {
      "message": "first commit",
      "parent": null,
      "files": "[[\"foo.js\",{\"content\":\"hello winter\"}]]"
    }
  },
  "stage": [],
  "working": [
    [
      "foo.js",
      { "content": "hello winter" }
    ]
  ],
  "head": "_1"
}

We'll continue by editing our file and making another commit.

git.save("foo.js", { content: "winter is coming" });
git.add('foo.js');
git.commit('second commit');

There are two commits now and head points to the second one (with a hash of _2).

{
  "commits": {
    "_1": {
      "message": "first commit",
      "parent": null,
      "files": "[[\"foo.js\",{\"content\":\"hello winter\"}]]"
    },
    "_2": {
      "message": "second commit",
      "parent": "_1",
      "files": "@@ -20,20 +20,25 @@\n t\":\"\n-hello \n winter\n+ is comming\n \"}]]\n"
    }
  },
  "stage": [],
  "working": [
    [
      "foo.js",
      { "content": "winter is comming" }
    ]
  ],
  "head": "_2"
}

Also notice that the second commit does not contain the whole file but a patch on top of the first commit.

We may now go back to our first commit:

git.checkout('_1');

The head again points to _1 and our working directory contains also the files from that first commit.

{
  "commits": {
    "_1": {
      "message": "first commit",
      "parent": null,
      "files": "[[\"foo.js\",{\"content\":\"hello winter\"}]]"
    },
    "_2": {
      "message": "second commit",
      "parent": "_1",
      "files": "@@ -20,20 +20,25 @@\n t\":\"\n-hello \n winter\n+ is comming\n \"}]]\n"
    }
  },
  "stage": [],
  "working": [
    [
      "foo.js",
      { "content": "hello winter" }
    ]
  ],
  "head": "_1"
}

API

save(filepath:<string>, file:<object>):<object>

Saves a file in the working directory.

type description
filepath <string> A file path (ex. script.js).
file <object> A file object (ex. { "content": "let foo = 'bar';" }).
returns <object> A file object.

save(files:<object>):<object>

Saves multiple files in the working directory.

type description
files <object> A map where the keys are filepaths and the values are file objects. (ex. { "script.js": { content: "let foo = 'bar';" } })
returns <object> Gitfred instance.

discard():<object>

Cleans up the working directory.

type description
returns <object> Gitfred instance.

saveAll(file:<object>):<object>

Sometimes we need to update all the files at once with a single property. This method allows that.

type description
file <object> A file object (ex. { "content": "" })
returns <object> Gitfred instance.

If we for example use { "content": "" } all the files in the working directory will have empty content property.

del(filepath:<string>):<object>

Deletes a file from the working directory.

type description
filepath <string> A file path (ex. script.js).
returns <object> Gitfred instance.

get(filepath:<string>):<object>

Gets a file (from the working directory) behind a specific file path.

type description
filepath <string> A file path (ex. script.js).
returns <object> A file object or undefined if the file is not found.

getAll():<array>

Gets all the files in the working directory.

type description
returns <array> An array with all the files.

rename(oldFilepath:<string>, newFilepath:<string>):<object>

It renames a file or in other words updates a filepath but keeps the file object assign to it.

type description
oldFilepath <string> A file path (ex. scriptA.js).
newFilepath <string> A file path (ex. scriptB.js).
returns <object> Gitfred instance.

getFilepath(file:<object>):<string>

Gets a file path which responds to a specific file object.

type description
file <object> A file object.
returns <object> A file path (ex. script.js) or undefined if the file object is not found.

exists(filepath:<string>):<boolean>

Checks if the file exists in the current working directory.

type description
filepath <string> A file path.
returns <boolean> true or false.

add(filepath:<string>):<object>

Adds a file to the staging area.

type description
filepath <string> A file path (ex. script.js).
returns <object> Gitfred instance.

add():<object>

Like the above one but it adds all the files from the working directory to the staging area.

type description
returns <object> Gitfred instance.

commit(message:<string>, meta:<object>):<string>

Registers a commit, cleans the staging area and sets the head to point to the new commit.

type description
message <string> The message of the commit
meta <object> Optional. A meta data that could be attached to the commit. (ex. { flag: true })
returns <string> The hash of the commit which is nothing fancy but _<number>

amend(hash:<string>, changes:<object>):<object>

Amends an already existing commit.

type description
hash <string> Hash of the commit that needs to be amended.
changes <string> An object key-value pairs. Check below.
returns <object> It returns the commit object.

The changes object has the following structure:

{
  message: <string>,
  meta: <object>,
  files: {
    <filepath:string>: <file:object>,
    <filepath:string>: <file:object>
  }
}

For example:

{
  message: 'A better message',
  meta: { flag: false, foo: 'bar' },
  files: {
    'a.js': { content: 'Foo' },
    'b.js': { content: 'Bar' }
  }
};

If the method is called with no arguments Gitfred takes whatever is in the current working directory and applies it to the commit where the head points to.

show(hash:<string>):<object>

Gets a commit behind a specific hash. If used with no arguments returns the commit where the head points to.

type description
hash <string> Hash of a commit.
returns <object> It returns a commit object.

diff():<object>

Shows the diff between the current working directory and the commit which the head points to.

type description
returns <object> It returns null if there's no diff or an object { text:<string>, html:<string> }.

adios(hash):<object>

You probably wonder why I picked such a method name right? This method deletes a specific commit. There is no such a thing in Git. We have revert and rebase but that's not really deleting. Gitfred has ridicules simple structure and it is quite easy to implement such functionality.

type description
hash <string> Hash of a commit.
returns <object> It returns the commit which is deleted.

checkout(hash:<string>, force:<boolean>):<object>

Sets the head to point to a specific commit.

type description
hash <string> Hash of a commit.
force <boolean> false by default. Gitfred throws an error if the staging area is empty or there is unstaged files. By setting this flag to true you are skipping those checks.
returns <object> Gitfred instance.

head():<string>

type description
returns <string> Returns a hash of a commit or null.

log():<object>

Get all the commits.

type description
returns <object> It returns all the commits in a single object where the commit hash is a key and the commit object a value.

logAsTree():<object>

Get all the commits.

type description
returns <object> It returns all the commits in a tree of objects.

rollOut():<object>

Get all the commits but with actual file content. .log and .logAsTree deliver the files as patches.

type description
returns <object> It returns all the commits.

export():<object>

It dumps all the data of Gitfred.

type description
returns <object> All the data of Gitfred.

import(data:<object>):<object>

The opposite of export method.

type description
data <object> Gitfred data.
returns <object> The working directory object.

listen(callback:<function>):<nothing>

Send a listener function which will be called when the working tree is changed (ON_CHANGE event), when the staging area is changed (ON_ADD event), when a new commit is made (ON_COMMIT event) and when the head is updated (ON_CHECKOUT event).

type description
callback <function> Fired with either one of the following: ON_CHANGE, ON_ADD, ON_COMMIT, or ON_CHECKOUT.
returns <nothing>

commitDiffToHTML(hash:<string>):<string>

It returns a HTML string containing the diff in a specific commit

type description
hash <string> Hash of a commit.
returns <string> HTML string.

calcStrDiff(a:<string>, b:string):<object>

Compares string a with string b. Returns either null or a diff object which contains text and html properties.

type description
a <string> Old Text
b <string> New text
returns <string> null or object { text:<string>, html:<string> }.

Static variables:

  • git.ON_CHANGE - send to the listener passed to listen method. Fired when something in the working directory is changed.
  • git.ON_ADD - send to the listener passed to listen method
  • git.ON_COMMIT - send to the listener passed to listen method
  • git.ON_CHECKOUT - send to the listener passed to listen method

Scripts

  • yarn release - building the library
  • yarn test - running the tests once
  • yarn dev - running the tests in a watch mode