isomorphic-git/isomorphic-git

A pure JavaScript implementation of git for node and browsers!

isomorphic-git is a pure JavaScript implementation of git that works in node and browser environments (including WebWorkers and ServiceWorkers). This means it may perchance well perhaps well perchance moreover be former to study and write to to git repositories, as smartly as accept from and push to git remotes look after Github.

Isomorphic-git goals for a hundred% interoperability with the canonical git implementation. This means it does all its operations by improving recordsdata in a « .git » directory honest look after the git you is at possibility of be former to. The included isogit CLI can characteristic on git repositories for your desktop or server.

isomorphic-git goals to be a total resolution with out a meeting required.
I’ve tried carefully to construct the API so it’s a long way uncomplicated to use the full ingredients, with out paying a penalty in bundle size.
By providing performance as separate capabilities as a replacement of an object oriented API, code bundlers look after Webpack will principal encompass the performance your utility actually uses. (Or no longer lower than that is the map.)

I am working on adding form definitions so you may perchance well well perchance perhaps receive pleasure from static form-checking and figuring out code completion in editors look after CodeSandbox.

Getting Began

The « isomorphic » in isomorphic-git device it actually works equally smartly on the server or the browser.
That is no longer easy to present since git uses the file machine, and browsers wouldn’t private an fs module.
So relatively than counting on the fs module, isomorphic-git is BYOFS (Bring Your Possess File Draw).
When making a recent Git object, you pass it the fs module to use.

Whenever you is at possibility of be principal using isomorphic-git in Node, you may perchance well well perchance perhaps honest use the native fs module.

const git = require('isomorphic-git');
const fs = require('fs');
git.listFiles({fs, dir: __dirname});

Whenever you is at possibility of be writing code for the browser though, you are going to need something that emulates the fs API.
At the time of writing, perhaps the most total option is BrowserFS.
It has a pair of more steps desirous to field up than in Node, as considered under:

<script src="https://unpkg.com/browserfs">script>
<script src="https://unpkg.com/isomorphic-git">script>
<script>
BrowserFS.configure({ fs: "IndexedDB", alternatives: {} }, characteristic (err) {
  if (err) return console.log(err);
  window.fs = BrowserFS.BFSRequire("fs");
  git.listFiles({fs: window.fs, dir: '/'});
});
</script>

Moreover IndexedDB, BrowserFS helps many varied backends with assorted performance characteristics, as smartly as principal configurations equivalent to: more than one mounting aspects, and retaining a writeable filesystems on top of a study-principal filesystem. You do no longer want to perceive about all these ingredients, however familiarizing yourself with the quite loads of alternatives would be foremost in case you hit a storage restrict or performance bottleneck within the IndexedDB backend I instructed above.

CORS improve

Sadly, as a result of identical-starting place policy by default isomorphic-git can principal clone from the identical starting place as the webpage it’s running on. That is terribly inconvenient, because it device for all purposeful capabilities cloning and pushing repos want to be executed through a proxy. On the opposite hand, I am « being the alternate you bought to hope to admire on this planet » by making PRs to the full significant git repository cyber web hosting products and providers.

It is literally honest two lines of code to add the CORS headers!! Easy stuff. With out a doubt this may perchance well well perchance happen.

Using as an npm module

You can well perchance moreover install it from npm.

npm install --place isomorphic-git

Within the equipment.json you are going to peep there are in point of fact Four assorted versions:

  "important": "dist/for-node/",
  "browser": "dist/for-browserify/",
  "module": "dist/for-future/",
  "unpkg": "dist/bundle.umd.min.js",

This perhaps deserves a immediate clarification.

• the « important » model is for node.
• the « browser » model is for browserify.
• the « module » model is for native ES6 module loaders after they come.
• the « unpkg » model is the UMD plot.

For more vital aspects about each plot peep ./dist/README.md

isogit CLI

Isomorphic-git comes with a easy CLI instrument, named isogit because isomorphic-git is lots to form. It is actually honest a thin shell that interprets uncover line arguments into the identical JS API instructions. So you wants with the map to hump any recent or future isomorphic-git instructions using the CLI.

It always starts with an the perception that the recent working directory is a git root.
E.g. repo = recent Git({fs, dir: '.'}).

It uses minimisted to parse uncover line alternatives.

TODO: Doc this more. Furthermore write some assessments? IDK the CLI is more of a lark for locating out actually.

Supported Git instructions

I could perchance well well perchance moreover proceed to beget adjustments to the API till the 1.0 initiate, after which I promise no longer to beget any breaking adjustments.

instructions

utils

Interior code architecture

I actually private written this library as a series of layers that plot upon one but any other and will tree-shake completely:

Commands

Each and each uncover is readily available as its possess file, so you is at possibility of get a device to import particular particular person instructions
in case you principal need a pair of in elaborate to optimize your bundle size.

Managers

Managers are a level above objects. They procure care of implementation performance vital aspects look after

• batching reads to and from the file machine
• in-path of concurrency locks
• lockfiles
• caching recordsdata and invalidating cached results
• reusing objects
• object memory swimming pools

Models and Utils

Models and utils are the bottom level building blocks.
Models in general private only a pair of or no dependencies other than for 'buffer'.
This makes them moveable to many varied environments so they would perhaps well moreover be a purposeful lowest general denominator.

Utils are primarily miscellaneous capabilities.
Some are comfort wrappers for general filesystem operations.

Who is using isomorphic-git?

• nde – a futuristic next-know-how web IDE
• git-app-supervisor – install « unhosted » websites locally by git cloning them

The same projects

Acknowledgments

Isomorphic-git save no longer need been that you just may perchance well well perchance perhaps place confidence in with out the pioneering work by
@creationix and @chrisdickinson. Git is a no longer easy binary mess, and with out
their examples (and their modules!) I save no longer need been able to receive again even
shut to finishing this. They’re geniuses ahead of their time.

Contributors

Thanks goes to these honorable americans (emoji key):

This challenge follows the all-contributors specification. Contributions of any form welcome!

Backers

Thank you to all our backers! 🙏 [Turn into a backer]

Sponsors

Make stronger this challenge by becoming a sponsor. Your emblem will designate up here with a hyperlink to your web blueprint. [Turn into a sponsor]

License

This work is launched below The MIT License