Neighborly Package Megalodon

    isomorphic-git
    TypeScript icon, indicating that this package has built-in type declarations

    1.0.0-beta.3 • Public • Published

    isomorphic-git

    A pure JavaScript implementation of git for node and browsers!

    Latest release:

    current npm version required node version written in ECMAScript 2017+ license gzip size install size

    Master branch status:

    semantic-release Build Status dependencies Known Vulnerabilities FOSSA Status

    Social:

    Gitter chat Backers on Open Collective Sponsors on Open Collective

    Browser Support:

    Sauce Labs Test Status (for master branch)

    Most recent build:

    Build Status Build Status BrowserStack Status

    isomorphic-git is a pure JavaScript implementation of git that works in node and browser environments (including WebWorkers and ServiceWorkers). This means it can be used to read and write to git repositories, as well as fetch from and push to git remotes like Github.

    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.

    isomorphic-git aims to be a complete solution with no assembly required. I've tried carefully to design the API so it is easy to use all the features, without paying a penalty in bundle size. By providing functionality as separate functions instead of an object oriented API, code bundlers like Webpack will only include the functionality your application actually uses. (Or at least that's the goal.)

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

    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.

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

    1. The supported browser versions will be bumped.
    2. The checkout command will be removed, and the safer and faster fastCheckout command renamed to checkout.
    3. The walkBeta1 command will be removed, and the walkBeta2 command renamed to walk.
    4. The deprecated commands sign, utils.auth, and utils.oauth2 will be removed.
    5. Support for the deprecated fs function argument will be removed.
    6. Support for the deprecated emitter function argument will be removed.
    7. Support for the signing function argument of log will be removed, and log will simply always return a payload. The payload property will be renamed to gpgmsg so its purpose is more obvious. (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.)

    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. At the time of writing, the most complete option is BrowserFS. Compared to Node, there is an extra setup step to configure BrowserFS, as seen below:

    <script src="https://unpkg.com/browserfs"></script>
    <script src="https://unpkg.com/isomorphic-git"></script>
    <script>
    BrowserFS.configure({ fs: "IndexedDB", options: {} }, function (err) {
      if (err) return console.log(err);
      window.fs = BrowserFS.BFSRequire("fs");
      git.plugins.set('fs', window.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

    Besides IndexedDB, BrowserFS supports many different backends with different performance characteristics, as well as advanced configurations such as: multiple mounting points, and overlaying a writeable filesystem on top of a read-only filesystem. You don't need to know about all these features, but familiarizing yourself with the different options may be necessary if you hit a storage limit or performance bottleneck using the IndexedDB backend I suggested above.

    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 4 different versions:

      "main": "dist/for-node/isomorphic-git/index.js",
      "module": "dist/for-future/isomorphic-git/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 karma plugin 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?

    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:

    BrowserStack

    SauceLabs

    Contributors

    Thanks goes to these wonderful people (emoji key):

    William Hilton
    William Hilton

    📝 🐛 💻 🎨 📖 💡 ⚠️
    wDhTIG
    wDhTIG

    🐛
    Marc MacLeod
    Marc MacLeod

    🤔 🔍
    Brett Zamir
    Brett Zamir

    🤔
    Dan Allen
    Dan Allen

    🐛 💻 🤔
    Tomáš Hübelbauer
    Tomáš Hübelbauer

    🐛 💻
    Juan Campa
    Juan Campa

    🐛 💻
    Ira Miller
    Ira Miller

    🐛
    Rhys Arkins
    Rhys Arkins

    💻
    Sean Larkin
    Sean Larkin

    💻
    Daniel Ruf
    Daniel Ruf

    💻
    bokuweb
    bokuweb

    💻 📖 ⚠️
    Hiroki Osame
    Hiroki Osame

    💻 📖
    Jakub Jankiewicz
    Jakub Jankiewicz

    💬 🐛 💻 💡 ⚠️
    howardgod
    howardgod

    🐛 💻
    burningTyger
    burningTyger

    🐛
    Melvin Carvalho
    Melvin Carvalho

    📖
    akaJes
    akaJes
    💻
    Dima Sabanin
    Dima Sabanin

    🐛 💻
    Koutaro Chikuba
    Koutaro Chikuba

    🐛 💻
    Hubert SABLONNIÈRE
    Hubert SABLONNIÈRE

    💻 ⚠️ 🤔 🔍
    David Duarte
    David Duarte

    💻
    Thomas Pytleski
    Thomas Pytleski

    🐛 💻
    Vadim Markovtsev
    Vadim Markovtsev

    🐛
    Yu Shimura
    Yu Shimura

    🤔 💻 ⚠️
    Dan Lynch
    Dan Lynch

    💻
    Jeffrey Wescott
    Jeffrey Wescott

    🐛 💻
    zebzhao
    zebzhao

    💻
    Tyler Smith
    Tyler Smith

    🐛
    Bram Borggreve
    Bram Borggreve

    🐛
    Stefan Guggisberg
    Stefan Guggisberg

    🐛 💻 ⚠️
    Catalin Pirvu
    Catalin Pirvu

    💻
    Nicholas Nelson
    Nicholas Nelson

    💻 ⚠️
    Anna Henningsen
    Anna Henningsen

    💻
    Fabian Henneke
    Fabian Henneke

    🐛 💻
    djencks
    djencks

    🐛 💻 ⚠️
    Clemens Wolff
    Clemens Wolff

    💻 📖 ⚠️

    This project follows the all-contributors specification. Contributions of any kind welcome!

    Backers

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

    Sponsors

    Support this project by becoming a sponsor. Your logo will show up here with a link to your website. [Become a sponsor]

    License

    This work is released under The MIT License

    FOSSA Status

    Install

    npm i isomorphic-git@1.0.0-beta.3

    Version

    1.0.0-beta.3

    License

    MIT

    Unpacked Size

    4.08 MB

    Total Files

    16

    Last publish

    Collaborators

    • mojavelinux
    • jcubic
    • wmhilton