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.

• Demo
• Implement Git in JavaScript

• Installation
• Usage
• API
  • save(filepath:<string>, file:<object>):<object>
  • save(files:<object>):<object>
  • discard():<object>
  • saveAll(file:<object>):<object>
  • del(filepath:<string>):<object>
  • get(filepath:<string>):<object>
  • getAll():<array>
  • rename(oldFilepath:<string>, newFilepath:<string>):<object>
  • getFilepath(file:<object>):<string>
  • exists(filepath:<string>):<boolean>
  • add(filepath:<string>):<object>
  • add():<object>
  • commit(message:<string>, meta:<object>):<string>
  • amend(hash:<string>, changes:<object>):<object>
  • show(hash:<string>):<object>
  • diff():<object>
  • adios(hash):<object>
  • checkout(hash:<string>, force:<boolean>):<object>
  • head():<string>
  • log():<object>
  • logAsTree():<object>
  • rollOut():<object>
  • export():<object>
  • import(data:<object>):<object>
  • listen(callback:<function>):<nothing>
  • commitDiffToHTML(hash:<string>):<string>
  • calcStrDiff(a:<string>, b:string):<object>
  • Static variables:
• Scripts

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.

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

Saves multiple files in the working directory.

discard():<object>

Cleans up the working directory.

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

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

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.

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

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

getAll():<array>

Gets all the files in the working directory.

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.

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

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

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

Checks if the file exists in the current working directory.

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

Adds a file to the staging area.

add():<object>

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

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

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

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

Amends an already existing commit.

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.

diff():<object>

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

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.

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

Sets the head to point to a specific commit.

head():<string>

log():<object>

Get all the commits.

logAsTree():<object>

Get all the commits.

rollOut():<object>

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

export():<object>

It dumps all the data of Gitfred.

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

The opposite of export method.

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).

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

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

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.

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