https://github.com/isomorphic-git/isomorphic-git

A pure JavaScript implementation of git for node and browsers!
https://github.com/isomorphic-git/isomorphic-git

browser git hacktoberfest isomorphic-javascript javascript nodejs vcs

Last synced: 3 months ago
JSON representation

A pure JavaScript implementation of git for node and browsers!

Host: GitHub
URL: https://github.com/isomorphic-git/isomorphic-git
Owner: isomorphic-git
License: mit
Created: 2017-07-30T02:26:00.000Z (almost 9 years ago)
Default Branch: main
Last Pushed: 2026-02-12T21:59:10.000Z (3 months ago)
Last Synced: 2026-02-20T17:30:47.173Z (3 months ago)
Topics: browser, git, hacktoberfest, isomorphic-javascript, javascript, nodejs, vcs
Language: JavaScript
Homepage: https://isomorphic-git.org
Size: 43 MB
Stars: 8,091
Watchers: 60
Forks: 451
Open Issues: 333
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE.md
- Code of conduct: CODE_OF_CONDUCT.md

Awesome Lists containing this project

awesome-nodejs - isomorphic-git - A pure JavaScript implementation of git for node and browsers! ![](https://img.shields.io/github/stars/isomorphic-git/isomorphic-git.svg?style=social&label=Star) (Repository / Git)
awesome-github-projects - isomorphic-git - A pure JavaScript implementation of git for node and browsers! ⭐8,194 `JavaScript` 🔥 (🛠️ Developer Tools)
awesome-nodejs-cn - isomorphic-git - Git的纯JavaScript实现. (目录 / 逼格项目)
awesome-nodejs - isomorphic-git - A pure JavaScript implementation of git for node and browsers! - ★ 3447 (Mad science)
awesome-github-star - isomorphic-git - git | 7033 | (JavaScript)
awesome - isomorphic-git - A pure JavaScript implementation of git for node and browsers! (JavaScript)
awesome-nodejs-cn - isomorphic-git - 纯 JavaScript 实现的 Git (包 / 黑科技)
awesome-nodejs - isomorphic-git - Pure JavaScript implementation of Git. (Packages / Mad science)
awesome-nodejs - isomorphic-git - Pure JavaScript implementation of Git. (Packages / Mad science)
awesome-list - isomorphic-git - git | 5852 | (JavaScript)
awesome-starred - isomorphic-git/isomorphic-git - A pure JavaScript implementation of git for node and browsers! (git)
awesome-starred - isomorphic-git/isomorphic-git - A pure JavaScript implementation of git for node and browsers! (JavaScript)
awesome-nodejs-cn - isomorphic-git - **star:7588** 纯 JavaScript 实现的 Git ![star > 2000][Awesome] (包 / 黑科技)
awesome-nodejs - isomorphic-git - Pure JavaScript implementation of Git. (Packages / Mad science)
awesome-atwoods-law - isomorphic-git - Pure JavaScript implementation of Git — clone, commit, push, pull in the browser. (8.1k stars) (Version Control)
fucking-awesome-nodejs - isomorphic-git - Pure JavaScript implementation of Git. (Packages / Mad science)

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](https://codesandbox.io).

## Project status

The original author of the project ([Billie Hilton](https://github.com/billiegoose)) left the project, but the project is still maintained by two volunteers:

* [@jcubic](https://github.com/jcubic) (most active)

* [@mojavelinux](https://github.com/mojavelinux)

But they don't write much code, mainly do code review and try to answer to issues and on Gitter, they just don't want the project to die. So you can say that this project is community driven (as jcubic always reply to issues). Which means that if you want a feature to be implemented you need to do this yourself or find someone that is willing to write the code for you. The project have some money on [OpenCollective](https://opencollective.com/isomorphic-git) and we can spend it on some development, if you find someone that is willing to code in exchange to some bucks (it may be you), but we don't have a lot so don't expect to have full sallary.

If you want to help this project you're more than welcome to do so.

## 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

## Upgrading from version 0.x to version 1.x?

See the full [Release Notes](https://github.com/isomorphic-git/isomorphic-git/releases/tag/v1.0.0) on GitHub and the release [Blog Post](https://isomorphic-git.org/blog/2020/02/25/version-1-0-0).

## Install

You can install it from npm:

```

npm install --save isomorphic-git

```

## 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 provided node HTTP client.

```js

// node.js example

const path = require('path')

const git = require('isomorphic-git')

const http = require('isomorphic-git/http/node')

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](https://github.com/isomorphic-git/lightning-fs) 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 [ZenFS](https://github.com/zen-fs/core) and [Filer](https://github.com/filerjs/filer).

Instead of `isomorphic-git/http/node` this time import `isomorphic-git/http/web`:

```html

import http from 'https://unpkg.com/isomorphic-git@beta/http/web/index.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)

```

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:

```js

import git from 'isomorphic-git'

// or

import * as git from 'isomorphic-git'

// or

import {plugins, clone, commit, push} from 'isomorphic-git'

```

View the full [Getting Started guide](https://isomorphic-git.github.io/docs/quickstart.html) on the docs website.

Then check out the [Useful Snippets](https://isomorphic-git.org/docs/en/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](https://github.com/isomorphic-git/cors-proxy) exists; which you can clone it or [`npm install`](https://www.npmjs.com/package/@isomorphic-git/cors-proxy) it. Alternatively, use CloudFlare workers, which can be setup without leaving the browser ([instructions](https://gist.github.com/tomlarkworthy/cf1d4ceabeabdb6d1628575ab3a83acf)).

For testing or small projects, you can also use [https://cors.isomorphic-git.org](https://cors.isomorphic-git.org) - a free proxy sponsored by [Clever Cloud](https://www.clever-cloud.com/?utm_source=ref&utm_medium=link&utm_campaign=isomorphic-git).

We hope to get CORS headers added to all the major Git hosting platforms eventually, and will list the progress made here:

| Service             | Supports CORS requests                                                                                                                                                       |

| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

| Gogs (self-hosted)  | [✔](https://isomorphic-git.github.io/blog/2018/04/07/gogs-adds-cors-headers-for-isomorphic-git.html)                                                                         |

| Gitea (self-hosted) | [✔](https://github.com/go-gitea/gitea/pull/5719)                                                                                                                             |

| Azure DevOps        | [✔](https://github.com/isomorphic-git/isomorphic-git/issues/678#issuecomment-452402740) (Usage Note: requires authentication)                        |

| Gitlab              | ❌ Our [PR](https://gitlab.com/gitlab-org/gitlab-workhorse/merge_requests/219) was rejected, but the [issue](https://gitlab.com/gitlab-org/gitlab/issues/20590) is still open! |

| Bitbucket           | ❌                                                                                                                                                                            |

| Github              | ❌                                                                                                                                                                            |

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

### `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 we may continue to make changes to the API but they will always be backwards compatible

unless there is a major version bump.

### commands

- [abortMerge](https://isomorphic-git.github.io/docs/abortMerge.html)

- [add](https://isomorphic-git.github.io/docs/add.html)

- [addNote](https://isomorphic-git.github.io/docs/addNote.html)

- [addRemote](https://isomorphic-git.github.io/docs/addRemote.html)

- [annotatedTag](https://isomorphic-git.github.io/docs/annotatedTag.html)

- [branch](https://isomorphic-git.github.io/docs/branch.html)

- [checkout](https://isomorphic-git.github.io/docs/checkout.html)

- [clone](https://isomorphic-git.github.io/docs/clone.html)

- [commit](https://isomorphic-git.github.io/docs/commit.html)

- [currentBranch](https://isomorphic-git.github.io/docs/currentBranch.html)

- [deleteBranch](https://isomorphic-git.github.io/docs/deleteBranch.html)

- [deleteRef](https://isomorphic-git.github.io/docs/deleteRef.html)

- [deleteRemote](https://isomorphic-git.github.io/docs/deleteRemote.html)

- [deleteTag](https://isomorphic-git.github.io/docs/deleteTag.html)

- [expandOid](https://isomorphic-git.github.io/docs/expandOid.html)

- [expandRef](https://isomorphic-git.github.io/docs/expandRef.html)

- [fastForward](https://isomorphic-git.github.io/docs/fastForward.html)

- [fetch](https://isomorphic-git.github.io/docs/fetch.html)

- [findMergeBase](https://isomorphic-git.github.io/docs/findMergeBase.html)

- [findRoot](https://isomorphic-git.github.io/docs/findRoot.html)

- [getConfig](https://isomorphic-git.github.io/docs/getConfig.html)

- [getConfigAll](https://isomorphic-git.github.io/docs/getConfigAll.html)

- [getRemoteInfo](https://isomorphic-git.github.io/docs/getRemoteInfo.html)

- [getRemoteInfo2](https://isomorphic-git.github.io/docs/getRemoteInfo2.html)

- [hashBlob](https://isomorphic-git.github.io/docs/hashBlob.html)

- [indexPack](https://isomorphic-git.github.io/docs/indexPack.html)

- [init](https://isomorphic-git.github.io/docs/init.html)

- [isDescendent](https://isomorphic-git.github.io/docs/isDescendent.html)

- [isIgnored](https://isomorphic-git.github.io/docs/isIgnored.html)

- [listBranches](https://isomorphic-git.github.io/docs/listBranches.html)

- [listFiles](https://isomorphic-git.github.io/docs/listFiles.html)

- [listNotes](https://isomorphic-git.github.io/docs/listNotes.html)

- [listRefs](https://isomorphic-git.github.io/docs/listRefs.html)

- [listRemotes](https://isomorphic-git.github.io/docs/listRemotes.html)

- [listServerRefs](https://isomorphic-git.github.io/docs/listServerRefs.html)

- [listTags](https://isomorphic-git.github.io/docs/listTags.html)

- [log](https://isomorphic-git.github.io/docs/log.html)

- [merge](https://isomorphic-git.github.io/docs/merge.html)

- [packObjects](https://isomorphic-git.github.io/docs/packObjects.html)

- [pull](https://isomorphic-git.github.io/docs/pull.html)

- [push](https://isomorphic-git.github.io/docs/push.html)

- [readBlob](https://isomorphic-git.github.io/docs/readBlob.html)

- [readCommit](https://isomorphic-git.github.io/docs/readCommit.html)

- [readNote](https://isomorphic-git.github.io/docs/readNote.html)

- [readObject](https://isomorphic-git.github.io/docs/readObject.html)

- [readTag](https://isomorphic-git.github.io/docs/readTag.html)

- [readTree](https://isomorphic-git.github.io/docs/readTree.html)

- [remove](https://isomorphic-git.github.io/docs/remove.html)

- [removeNote](https://isomorphic-git.github.io/docs/removeNote.html)

- [renameBranch](https://isomorphic-git.github.io/docs/renameBranch.html)

- [resetIndex](https://isomorphic-git.github.io/docs/resetIndex.html)

- [resolveRef](https://isomorphic-git.github.io/docs/resolveRef.html)

- [setConfig](https://isomorphic-git.github.io/docs/setConfig.html)

- [stash](https://isomorphic-git.github.io/docs/stash.html)

- [status](https://isomorphic-git.github.io/docs/status.html)

- [statusMatrix](https://isomorphic-git.github.io/docs/statusMatrix.html)

- [tag](https://isomorphic-git.github.io/docs/tag.html)

- [updateIndex](https://isomorphic-git.github.io/docs/updateIndex.html)

- [version](https://isomorphic-git.github.io/docs/version.html)

- [walk](https://isomorphic-git.github.io/docs/walk.html)

- [writeBlob](https://isomorphic-git.github.io/docs/writeBlob.html)

- [writeCommit](https://isomorphic-git.github.io/docs/writeCommit.html)

- [writeObject](https://isomorphic-git.github.io/docs/writeObject.html)

- [writeRef](https://isomorphic-git.github.io/docs/writeRef.html)

- [writeTag](https://isomorphic-git.github.io/docs/writeTag.html)

- [writeTree](https://isomorphic-git.github.io/docs/writeTree.html)

## Community

Share your questions and ideas with us! We love that.

You can find us in our [Gitter chatroom](https://gitter.im/isomorphic-git/Lobby) or just create an issue here on Github!

We are also [@IsomorphicGit](https://twitter.com/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](https://jestjs.io) 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](https://jasmine.github.io/) via [Karma](https://karma-runner.github.io).

We even have our own [mock server](https://github.com/isomorphic-git/git-http-mock-server) for serving

git repository test fixtures!

You'll need [node.js](https://nodejs.org) installed, but everything else is a devDependency.

```sh

git clone https://github.com/isomorphic-git/isomorphic-git

cd isomorphic-git

npm install

npm test

```

The new release happens automatically after every PR merge. We use [semantic release](https://github.com/semantic-release/semantic-release).

Check out the [`CONTRIBUTING`](./CONTRIBUTING.md) document for more instructions.

## Who is using isomorphic-git?

- [nde](https://nde.now.sh) - a futuristic next-generation web IDE

- [git-app-manager](https://git-app-manager.now.sh/) - install "unhosted" websites locally by git cloning them

- [GIT Web Terminal](https://jcubic.github.io/git/)

- [Next Editor](https://next-editor.app/)

- [Clever Cloud](https://www.clever-cloud.com/?utm_source=ref&utm_medium=link&utm_campaign=isomorphic-git)

- [Stoplight Studio](https://stoplight.io/studio/?utm_source=ref&utm_medium=link&utm_campaign=isomorphic-git) - a modern editor for API design and technical writing

## Similar projects

- [js-git](https://github.com/creationix/js-git)

- [es-git](https://github.com/es-git/es-git)

## 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!) we 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:

[![BrowserStack](https://user-images.githubusercontent.com/587740/39730261-9c65c4d8-522e-11e8-9f12-16b349377a35.png)](http://browserstack.com/)

[![SauceLabs](https://saucelabs.com/content/images/logo.png)](https://saucelabs.com)

## Contributors

Thanks goes to these wonderful people ([emoji key](https://github.com/kentcdodds/all-contributors#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}
💻 📖 ⚠️

    
_{Sojin Park}
💻

    
_{Edward Faulkner}
💻

    
_Khải
🐛

    
_{Corbin Crutchley}
💻 📖 ⚠️

    
_{Riceball LEE}
💻 📖 ⚠️

  

  

    
_{lin onetwo}
💻

    
_林法鑫
🐛

    
_{Will Stott}
💻 ⚠️

    
_{Seth Nickell}
🐛

    
_{Alex Titarenko}
💻

    
_{Misha Kaletsky}
💻

    
_{Richard C. Zulch}
💻 📖

  

  

    
_mkizka
💻

    
_RyotaK
🐛

    
_{Noah Hummel}
💻 ⚠️

    
_{Mike Lewis}
📖

    
_{Sam Verschueren}
💻

    
_{Vitor Luiz Cavalcanti}
📖

    
_{Shane McLaughlin}
💻 📖 ⚠️

  

  

    
_{Sean Poulter}
🚧 💻 📖 ⚠️

    
_araknast
💻 ⚠️ 📖

    
_{Rafael Raab}
💻 📖

    
_{Lukáš Cezner}
💻 📖 ⚠️ 🐛

    
_dead-end
💻 📖 ⚠️

    
_Barry
💻 📖 ⚠️

    
_{Alireza Mirian}
💻 📖 ⚠️ 🐛

  

  

    
_DanilKazanov
💻 📖 ⚠️

    
_{Eyal Hisco}
🐛

    
_Sebastien
💻

    
_{Yaroslav Halchenko}
📖

    
_{Alex Villarreal}
💻

    
_{Modesty Zhang}
💻 📖 ⚠️

    
_{Ben Morrow}
💻

  

  

    
_jayree
💻 ⚠️

    
_{Lucas Martin Segurado}
📖 🐛

    
_{Leon Kaucher}
💻 ⚠️

    
_{Gili Shohat}
💻 📖 ⚠️

    
_Habib
💻 📖 ⚠️

    
_Vinzent
💻

    
_{James Prevett}
💻 ⚠️ 🚧

  

  

    
_{Patrick Kranz}
💻 📖 ⚠️

    
_{Luke Cotter}
💻

    
_{Tom Larkworthy}
📖

    
_{Mostafa Mahmoud}
💻 ⚠️ 💬

    
_{Aniket Bhosale}
💻 📖 ⚠️

    
_{Mathias Nisted Velling}
💻 ⚠️

    
_acandoo
📦 📓

  

  

    
_{Patrick Kranz}
💻 📖 ⚠️

    
_{Luke Cotter}
💻

    
_{Tom Larkworthy}
📖

    
_{Mostafa Mahmoud}
💻 ⚠️ 💬

    
_{Aniket Bhosale}
💻 📖 ⚠️

    
_{Mathias Nisted Velling}
💻 ⚠️

    
_acandoo
📦 📓

  

  

    
_{Bekatan Satyev}
💻 ⚠️

    
_{Hemanth Kini}
💻

    
_{Anish Awasthi}
💻 📖 ⚠️

    
_fetsorn
📖

    
_xiaoboost
💻 📖 ⚠️

    
_{Mateusz Burzyński}
💻 ⚠️

    
_iamssh
💻 📖 ⚠️

  

This project follows the [all-contributors](https://github.com/kentcdodds/all-contributors) specification. Contributions of any kind welcome!

### Backers

Thank you to all our backers! 🙏 [[Become a backer](https://opencollective.com/isomorphic-git#backer)]



### Sponsors

Support this project by becoming a sponsor. Your logo will show up here with a link to your website. [[Become a sponsor](https://opencollective.com/isomorphic-git#sponsor)]





















## License

This work is released under [The MIT License](https://opensource.org/licenses/MIT)

[![FOSSA Status](https://app.fossa.io/api/projects/git%2Bgithub.com%2Fisomorphic-git%2Fisomorphic-git.svg?type=large)](https://app.fossa.io/projects/git%2Bgithub.com%2Fisomorphic-git%2Fisomorphic-git?ref=badge_large)

ecosyste.ms

Data

Tools

Indexes

Applications

Experiments

Awesome

https://github.com/isomorphic-git/isomorphic-git

Awesome Lists containing this project

README