Package Exports

isomorphic-git
isomorphic-git/dist/bundle.umd.min.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (isomorphic-git) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

isomorphic-git

isomorphic-git is a pure JavaScript reimplementation of git that works in both Node.js and browser JavaScript environments. It can read and write to git repositories, fetch from and push to git remotes (such as GitHub), all without any native C++ module dependencies.

Goals

Isomorphic-git aims for 100% interoperability with the canonical git implementation. This means it does all its operations by modifying files in a ".git" directory just like the git you are used to. The included isogit CLI can operate on git repositories on your desktop or server.

This library aims to be a complete solution with no assembly required. The API has been designed with modern tools like Rollup and Webpack in mind. By providing functionality as individual functions, code bundlers can produce smaller bundles by including only the functions your application uses.

The project includes type definitions so you can enjoy static type-checking and intelligent code completion in editors like VS Code and CodeSandbox.

Supported Environments

The following environments are tested in CI and will continue to be supported until the next breaking version:

Node 10

Chrome 79

Edge 79

Firefox 72

Safari 13

Android 10

iOS 13

1.0 Release Plans

The 1.0 release is planned to coincide with the stable release of the new Chromium-based Micorosoft Edge in January 2020, so that we can drop support for the old Edge browser. Update: The new Edge browser is out, so I'm working on getting 1.0 out now.

At the time of writing, the following breaking changes are planned:

The supported browser versions will be bumped.
Commands that will be renamed:
- The checkout command will be replaced with the implementation used in the safer and faster fastCheckout command and fastCheckout will be removed.
- The walkBeta2 command renamed to walk, and the walkBeta1 command will be removed.
Deprecated commands and function arguments will be removed:
- The sign command will be removed.
- The commands utils.auth and utils.oauth2 will be removed.
- The emitter function argument will be removed.
- The fs function argument will be removed.
- The fast argument to pull will be removed since it will always use the fastCheckout implementation.
- The signing function argument of log will be removed, and log will simply always return a payload. Update: Actually, it now returns the same kind of objects as readCommit because that just makes a lot of sense. (This change is to simplify the type signature of log so we don't need function overloading; it is the only thing blocking me from abandoning the hand-crafted index.d.ts file and generating the TypeScript definitions directly from the JSDoc tags that already power the website docs.)
Any functions that currently return Buffer objects will instead return Uint8Array so we can eventually drop the bloated Buffer browser polyfill.
The pattern and globbing options will be removed from statusMatrix so we can drop the dependencies on globalyzer and globrex, but you'll be able to bring your own filter function instead.
The autoTranslateSSH feature will be removed, since it's trivial to implement using just the UnknownTransportError.data.suggestion
Make the 'message' event behave like 'rawmessage' and remove 'rawmessage'.
Update the README to recommend LightningFS rather than BrowserFS.
The internal-apis will be excluded from dist before publishing. Because those are only exposed so I could unit test them and no one should be using them lol.
I think I will change the plugins API. The current API (plugins.set('fs', fs)) uses a kinda-hacky run-time schema validation that just checks whether certain methods are defined. Static type checking would actually provide a better developer experience and better guarantees, but having .set be polymorphic is hard to accurately describe using JSDoc, so I might switch to an API like plugins.fs(fs).
- this also means we can set new FileSystem(_fs) in the plugins.fs(fs) command, because we don't have to expose a getter like plugins.get()!
I think I'll tweak readObject and writeObject so that readObject doesn't have a crazy polymorphic return type and they somehow "fit" with all the more specific read/write Blob/Commit/Tag/Tree commands.

Getting Started

The "isomorphic" in isomorphic-git means it works equally well on the server or the browser. That's tricky to do since git uses the file system, and browsers don't have an fs module. So rather than relying on the fs module, isomorphic-git is BYOFS (Bring Your Own File System). Before you can use most isomorphic-git functions, you need to set the fs module via the plugin system.

If you're only using isomorphic-git in Node, you can just use the native fs module.

const git = require('isomorphic-git');
const fs = require('fs');
git.plugins.set('fs', fs)

If you're writing code for the browser though, you'll need something that emulates the fs API. The easiest to setup and most performant library is LightningFS which is maintained by the same author and basically part of the isomorphic-git suite. If LightningFS doesn't meet your requirements, isomorphic-git should also work with BrowserFS and Filer.

<script src="https://unpkg.com/@isomorphic-git/lightning-fs"></script>
<script src="https://unpkg.com/isomorphic-git"></script>
<script>
const fs = new LightningFS('fs')
git.plugins.set('fs', fs)
</script>

If you're using ES module syntax, use either a namespace import or named imports to benefit from tree-shaking:

import * as git from 'isomorphic-git'
// or
import {plugins, clone, commit, push} from 'isomorphic-git

View the full Getting Started guide on the docs website.

Then check out the Useful Snippets page, which includes even more sample code written by the community!

CORS support

Unfortunately, due to the same-origin policy by default isomorphic-git can only clone from the same origin as the webpage it is running on. This is terribly inconvenient, as it means for all practical purposes cloning and pushing repos must be done through a proxy.

For this purpose @isomorphic-git/cors-proxy exists which you can clone or npm install. For testing or small projects, you can also use https://cors.isomorphic-git.org - a free proxy sponsored by Clever Cloud.

I'm hoping to get CORS headers added to all the major Git hosting platforms eventually, and will list my progress here:

Service	Supports CORS requests
Gogs (self-hosted)	✔
Gitea (self-hosted)	✔
Azure DevOps	✔ (Usage Note: requires `noGitSuffix: true` and authentication)
Gitlab	❌ My PR was rejected, but the issue is still open!
Bitbucket	❌
Github	❌

It is literally just two lines of code to add the CORS headers!! Easy stuff. Surely it will happen.

Using as an npm module

You can install it from npm.

npm install --save isomorphic-git

In the package.json you'll see there are actually 3 different versions:

  "main": "dist/index.cjs",
  "module": "dist/index.js",
  "unpkg": "dist/bundle.umd.min.js",

This deserves a brief explanation.

the "main" version is for node.
the "module" version is for webpack or other browser bundlers.
the "unpkg" version is the UMD build.

`isogit` CLI

Isomorphic-git comes with a simple CLI tool, named isogit because isomorphic-git is a lot to type. It is really just a thin shell that translates command line arguments into the equivalent JS API commands. So you should be able to run any current or future isomorphic-git commands using the CLI.

It always starts with an the assumption that the current working directory is a git root. E.g. { dir: '.' }.

It uses minimisted to parse command line options and will print out the equivalent JS command and pretty-print the output JSON.

The CLI is more of a lark for quickly testing isomorphic-git and isn't really meant as a git CLI replacement.

Supported Git commands

This project follows semantic versioning, so I may continue to make changes to the API but they will always be backwards compatible unless there is a major version bump.

commands

plugins

Community

Share your questions and ideas with us! We love that. You can find us in our Gitter chatroom or just create an issue here on Github! We are also @IsomorphicGit on Twitter.

Contributing to `isomorphic-git`

The development setup is similar to that of a large web application. The main difference is the ridiculous amount of hacks involved in the tests. We use Facebook's Jest for testing, which make doing TDD fast and fun, but we also used custom hacks so that the same tests will also run in the browser using Jasmine via Karma. We even have our own mock server for serving git repository test fixtures!

You'll need Node.js installed, but everything else is a devDependency.

git clone https://github.com/isomorphic-git/isomorphic-git
cd isomorphic-git
npm install
npm test

Check out the CONTRIBUTING document for more instructions.

Who is using isomorphic-git?

nde - a futuristic next-generation web IDE
git-app-manager - install "unhosted" websites locally by git cloning them
GIT Web Terminal
Next Editor
Clever Cloud
Stoplight Studio - a modern editor for API design and technical writing

Similar projects

Acknowledgments

Isomorphic-git would not have been possible without the pioneering work by @creationix and @chrisdickinson. Git is a tricky binary mess, and without their examples (and their modules!) I would not have been able to come even close to finishing this. They are geniuses ahead of their time.

Cross-browser device testing is provided by:

Contributors

Thanks goes to these wonderful people (emoji key):

_{William Hilton} 📝 🐛 💻 🎨 📖 💡 ⚠️ ✅	_wDhTIG 🐛	_{Marc MacLeod} 🤔 🔍	_{Brett Zamir} 🤔	_{Dan Allen} 🐛 💻 🤔	_{Tomáš Hübelbauer} 🐛 💻	_{Juan Campa} 🐛 💻
_{Ira Miller} 🐛	_{Rhys Arkins} 💻	_{Sean Larkin} 💻	_{Daniel Ruf} 💻	_bokuweb 💻 📖 ⚠️	_{Hiroki Osame} 💻 📖	_{Jakub Jankiewicz} 💬 🐛 💻 💡 ⚠️
_howardgod 🐛 💻	_burningTyger 🐛	_{Melvin Carvalho} 📖	_akaJes 💻	_{Dima Sabanin} 🐛 💻	_{Koutaro Chikuba} 🐛 💻	_{Hubert SABLONNIÈRE} 💻 ⚠️ 🤔 🔍
_{David Duarte} 💻	_{Thomas Pytleski} 🐛 💻	_{Vadim Markovtsev} 🐛	_{Yu Shimura} 🤔 💻 ⚠️	_{Dan Lynch} 💻	_{Jeffrey Wescott} 🐛 💻	_zebzhao 💻
_{Tyler Smith} 🐛	_{Bram Borggreve} 🐛	_{Stefan Guggisberg} 🐛 💻 ⚠️	_{Catalin Pirvu} 💻	_{Nicholas Nelson} 💻 ⚠️	_{Anna Henningsen} 💻	_{Fabian Henneke} 🐛 💻
_djencks 🐛 💻 ⚠️	_{Clemens Wolff} 💻 📖 ⚠️