Wasm-git

(Wasm should be pronounced like awesome starting with a W ).

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

The main purpose of bringing git to the browser, is to enable storage of web application data locally in the users web browser, with the option to synchronize with a remote server.

Demo in the browser

A simple demo in the browser can be found at:

https://wasm-git.petersalomonsen.com/

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. It shows basic operations like cloning, edit files, add and commit, push and pull.

Demo videos

Videos showing example applications using wasm-git can bee seen in this playlist. Wasm-git is used for local and offline storage of web application data, and for syncing with a remote server.

Examples

Wasm-git packages are built in two variants: Synchronuous and Asynchronuous. To run the sync version in the browser, a webworker is needed. This is because of the use of synchronous http requests and long running operations that would block if running on the main thread. The sync version has the smallest binary, but need extra client code to communicate with the web worker. When using the sync version in nodejs worker_threads are used, with Atomics to exchange data between threads.

The async version use Emscripten Asyncify, which allows calling the Wasm-git functions with async / await. It can also run from the main thread in the browser. Asyncify increase the binary size because of instrumentation to unwind and rewind WebAssembly state, but makes it possible to have simple client code without exchanging data with worker threads like in the sync version.

Examples of using Wasm-git can be found in the tests:

test for NodeJS
test-browser for the sync version in the browser with a web worker
test-browser-async] for the async version in the browser

The examples shows importing the lg2.js / lg2-async.js modules from the local build, but you may also access these from releases available at public CDNs.

Building and developing

The Github actions test pipeline shows all the commands needed to install dependencies, build the packages and run the tests.

Another option is loading the repository into a github codespace, where the configuration in .devcontainer folder will be used to install dependencies and set up a full development environment.

Emscripten fixes that were needed for making Wasm-git work

As part of being able to compile libgit2 to WebAssembly and run it in a Javascript environment, some fixes to Emscripten were needed.

Here are the Pull Requests that resolved the issues identified when the first version was developed:

for using with NODEFS you'll also need emscripten-core/emscripten#10669

All of these pull requests are merged to emscripten master as of 2020-03-29.

See .github/workflows/main.yml for a full build and test pipeline including installing emscripten.

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

Given you have installed and activated emscripten, you can use the script in emscriptenbuild/build.sh to configure and build, and you'll find the resulting lg2.js / lg2.wasm under the generated emscriptenbuild/examples folder.

An example of interacting with libgit2 from nodejs can be found in examples/example_node.js.

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.

Docker build

Build image in repository directory:

docker build -t wasm-git-image .

Example Release build and SINGLE_FILE parameter:

docker run -v .:/src/wasm-git --rm wasm-git-image /bin/bash -c "cd /src/wasm-git && git ls-files | xargs dos2unix && /src/wasm-git/docker_cleanup_and_build.sh Release SINGLE_FILE"

After build outputs can be found in emscriptenbuild/libgit2/examples/lg2.js and and in case no SINGLE_FILE parameter was provided also emscriptenbuild/libgit2/examples/lg2.wasm.

License

rraab-dev/wasm-git

ErrorLooks like something went wrong!

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Languages

Error
Looks like something went wrong!

Packages