Package Exports

isomorphic-git
isomorphic-git/dist/http.cjs
isomorphic-git/dist/http.js
isomorphic-git/dist/index.js

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 Breaking Changes

TODO:

I should probably normalize on timestamps and get rid of the date options.
I should probably remove username, password, token, and oauth2format and make everyone use onAuth callback for that.
Update the Useful Snippets.

Big changes

The supported node & browser versions have been bumped. (See beautiful table above.)
The plugin system has been eliminated and we're back to plain old dependency injection via function arguments! The plugin cores created a mysterious "global state" that makes it easy to trip up (I myself sometimes forgot to unset plugins after running tests). The old style of passing fs as a function argument was less aesthetic and more verbose, but it is a much simpler model than the plugin core model, and much safer because it makes it impossible for dependencies to accidentally share the default plugin core.
There is an additional setup step to choose which http client to use, and functions that make HTTP requests have a new required http parameter. Previously I used a mix of bundler and runtime magic to try and pick between a build that used fetch and one that used require('http') but that didn't always work. For instance, if you were bundling a Node application using Webpack, it would pick the wrong build (#938). Another example: in an Electron renderer thread, both options could work (if the window is launched with nodeIntegration: true) but in a Web Worker thread only the fetch option should work (unless you have nodeIntegrationInWorker: true set). See "Getting Started" below to see the extra line of code you need.

Some functions have been renamed or removed:

The walkBeta2 function was renamed to walk.
The walkBeta1 function was removed.
The fastCheckout function has been renamed checkout and the old checkout has been removed.
The (previously deprecated) sign function was removed.
The (previously deprecated) utils.auth function was removed.
The (previously deprecated) utils.oauth2 was removed.
The config function has been removed and replaced by getConfig, getConfigAll, and setConfig.
The verify function has been removed, but log, readCommit, and readTag all return the gpgsig and signing payload now. This actually makes verification simpler and more efficient, because it can be done in batch on git.log output and the gpgsig itself can be parsed and used to lookup the public key. See onSign for complete code examples.

Some function parameters have been removed or replaced:

The undocumented parameter aliases authUsername and authPassword were removed.
The emitter parameter was removed and replaced with the onMessage and onProgress callbacks. (Note that onMessage emits un-trimmed strings, so you get those \rs.)
The fast parameter of pull was removed, since there is no "slow" implementation anymore.
The signing parameter of log was removed, since log will always return a payload.
The pattern parameter was removed from statusMatrix and replaced with a new filter function. (This is so we can drop the dependencies on globalyzer and globrex.)
The newSubmoduleBehavior parameter was removed and is now the default and only behavior, because it makes much more sense to have non-destructive defaults!
The noSubmodules parameter was removed because with the new submodule behavior it is no longer necessary to print console warnings about how submodules aren't supported. (When submodule support IS added to isomorphic-git, it will be opt-in using recurseSubmodules: true or something like that.)
The autoTranslateSSH feature was removed, since it is trivial to implement your own version using just the UnknownTransportError.data.suggestion
The writeObject function when used to write a tree now expects a plain array rather than an object with a property called entries which is the array. (This is so that argument to writeObject has the same shame as the arguments to writeBlob/writeCommit/writeTag/writeTree.)
The noOverwrite parameter was removed from init and is the new behavior.

The return types of some functions have changed:

Functions that used to return Buffer objects now return Uint8Array objects. (This is so we can eventually remove all internal dependencies on the Buffer browser polyfill, which is quite heavy!)
The log function now returns an array of the same kind of objects that readCommit returns. (This change simplifies the type signature of log so we don't need function overloading; that function overloading was the one thing preventing me from auto-generating index.d.ts.)
The readObject function returns a proper discriminated union so TypeScript can infer the type of .object once you establish the value of .format and .type. Also .object has the same shape as as the return value of readBlob/readCommit/readTag/readTree. (Meaning trees are now plain arrays rather than objects with a .entries property that is the array.)

Some functions behavior changed

The push function now pushes to the remote tracking branch (rather than a branch with the same name) by default.

Docs and DX improvements

The docs/alphabetic.md and function list in README.md are auto-generated from the filenames in src/api.
The entire docs website is auto-generated from the JSDoc actually so from now on the docs website and source code will always be in sync.
All the example code in JSDoc is now type-checked during CI tests.
The live code examples on the website are displayed in a full-blown mobile-friendly code editor (CodeMirror 6).
Each page with live code examples includes a code snippet at the bottom to reset the browser file system.
The Getting Started guide has been updated.
All the example code in JSDoc has been updated.

Miscellaneous stuff

Update the README to recommend LightningFS rather than BrowserFS.
The internal-apis bundle is no longer included in the published package. Those were only exposed so I could run unit tests and no one should have been using them I hope.

Getting Started

The "isomorphic" in isomorphic-git means that the same code runs in either the server or the browser. That's tricky to do since git uses the file system and makes HTTP requests. Browsers don't have an fs module. And node and browsers have different APIs for making HTTP requests!

So rather than relying on the fs and http modules, isomorphic-git lets you bring your own file system and HTTP client.

If you're using isomorphic-git in Node, you use the native fs module and the include Node HTTP client.

// node.js example
const path = require('path')
const git = require('isomorphic-git');
const http = require('isomorphic-git/dist/http.cjs') // NOTE THE FILE EXTENSION IS .cjs
const fs = require('fs');

const dir = path.join(process.cwd(), 'test-clone')
git.clone({ fs, http, dir, url: 'https://github.com/isomorphic-git/lightning-fs' }).then(console.log)

If you're using isomorphic-git in the browser, you'll need something that emulates the fs API. The easiest to setup and most performant library is LightningFS which is written and maintained by the same author and is 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 type="module">
import http from 'https://unpkg.com/isomorphic-git@beta/dist/http.js' // NOTE THE FILE EXTENSION IS .js
const fs = new LightningFS('fs')

const dir = '/test-clone'
git.clone({ fs, http, dir, url: 'https://github.com/isomorphic-git/lightning-fs', corsProxy: 'https://cors.isomorphic-git.org' }).then(console.log)
</script>

If you're using ES module syntax, you can use either the default import for convenience, or named imports to benefit from tree-shaking if you are using a bundler:

import 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 a CommonJS build
the "module" version is an ES Module build
the "unpkg" version is a minified UMD build with dependencies already bundled

`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

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} 💻 📖 ⚠️