browser-git v1.0.3

browser-git

Introduction

GIT for the browser using libgit2 compiled to WebAssembly with Emscripten.

This is forked off of wasm-git by petersalomonsen.

That repo is a lot more clean and less hacky - I needed a few new features, and kinda just slapped them in as fast as I could. I also don't plan on keeping this up to date with mainline right now. I also am not keeping nodejs support working.

I will try to keep major breaking changes to major releases (eg if I released 2.0.0 that might break) - but I make no promises!

I strongly recommend checking out his version. Credit goes to him for figuring out how to compile this thing with emscripten and making it all work. It's seriously impressive.

Added features

• Creating new branches (create-branch) command
• Push uses your current branch instead of origin/master
• Checkout command actually updates HEAD

Original Demo in the browser

A simple demo in the browser can be found at:

https://githttpserverdemo.petersalomonsen.usw1.kubesail.io/

Please do not abuse, this is open for you to test and see the proof of concept

The sources for the demo can be found in the githttpserver project, which is a simple git server deployable to kubernetes. Showing basic operations like cloning, edit files, add and commit, push and pull.

Note: The url above is Peter Salomonsen's original version. If you want to try it with new features, run the copy in the repo.

CDN Build

There are some lovely cdns that host anything committed to npmjs.com for you automatically! You can use jsdelivr to get a stable version of the package.

You can use this to get the latest 1.x release: https://cdn.jsdelivr.net/npm/browser-git/1.x.x -- This should work for local development and most projects.

Note that the 1.x.x in the path will make it less cache-friendly. If you use this on a production site, consider using the full version instead. (eg 1.0.1)

Example WebWorker with pre built binaries

For running in the browser you should have your git interaction code in a webworker. This is because of the use of synchronous http requests and long running operations that would block if running on the main thread.

Here's an example of a simple webworker that uses pre-built binaries from https://cdn.jsdelivr.net/npm/browser-git@1.x.x/

const BROWSER_GIT_URL = 'https://cdn.jsdelivr.net/npm/browser-git/1.x.x/';
var Module = {
    locateFile: function(s) {
      return BROWSER_GIT_URL + s;
    }
};

importScripts(BROWSER_GIT_URL + 'lg2.js');

Module.onRuntimeInitialized = () => {
    const lg = Module;

    FS.mkdir('/working');
    FS.mount(MEMFS, { }, '/working');
    FS.chdir('/working');    

    FS.writeFile('/home/web_user/.gitconfig', '[user]\n' +
                'name = Test User\n' +
                'email = test@example.com');

    // clone a local git repository and make some commits

    lg.callMain(['clone',`http://localhost:5000/test.git`, 'testrepo']);

    FS.readdir('testrepo');
}

You'll start the worker from your html with the tag:

<script>new Worker('yourworker.js')</script>;

The example above expects to find a git repository at http://localhost:5000/test.git. If you want to clone from github you'd need a proxy running locally because of CORS restrictions that would prevent you accessing github directly. For testing you can use the proxy found in examples/webserverwithgithubproxy.js

Building

IMPORTANT: This depends on using an emscripten version with fixes made as of 2020-03-29. Use newer versions of emscripten

Dependencies

• cmake
• emscripten
• nodejs 12 or later (installed with emscripten)

See .travis.yml for a full build and test pipeline including installing emscripten.

Setup

Run setup.sh first to download libgit2 and apply patches.

Note that the initial build may be very slow finding things such as pthreads. This is normal, keep waiting.

Given you have installed and activated emscripten, you can use the command npm run build to configure and build, and you'll find the resulting lg2.js / lg2.wasm under the generated emscriptenbuild/examples folder. This command will automatically patch the files in the libgit2 folder, as well.

If you want a release build (minified javascript, smaller wasm file) you can run npm run build-release. This is what you want to use in any real apps.

An example for the browser (using webworkers) can be found in examples/example_webworker.js. You can start a webserver for this by running the examples/webserverwithgithubproxy.js script, which will launch a http server at http://localhost:5000 with a proxy to github. Proxy instead of direct calls is needed because of CORS restrictions in a browser environment.