0.70.7

Edit

'emitter' plugin

You opt to initialize isomorphic-git with a EventEmitter so you can receive 'message' and 'progress' events. The clone, fetch, push, and pull commands all emit events.

event type description
message string

'message' events are for messages generated by the remote server and sent during fetch and push requests. They are particularly useful if the remote server has custom git-hooks that print to the console.

progress

ProgressEvent

'progress' events are numerical events that could be used to drive progress bar-style animations.

Note: 'progress' events are not guaranteed to be in order or always incrementing. Many git commands (like clone) actually consist of multiple sub-commands (fetch + indexPack + checkout) which makes computing a single progress percentage tricky. This will be solved one day by providing new fine-grained progress events that more accurately represent the different phases of complex tasks.

Note: only one emitter plugin can be registered at a time.

Usage Example 1:

You are writing a console application, and you want to simply print any server messages to standard out.

// This example is for Node.js
const EventEmitter = require('events')
const git = require('isomorphic-git')
const emitter = new EventEmitter()
git.plugins.set('emitter', emitter)

emitter.on('message', message => {
  console.log(message)
})

Usage Example 2:

You are writing a web application, and want to display both the latest message and a progress bar. In the real world, you would probably be using the latest JS framework like React or Vue, but for this example I will stick with the DOM API.

Note: This is not a working example. It focuses only on the parts related to the emitter plugin.

<html>
  <div id="cloning-message"></div>
  <div>
    <span id="cloning-percent"></span>
    <progress id="cloning-progress-bar" value="0" max="100"/>
  </div>
  <script type="module">
    // Note: Webpack automatically polyfills Node's builtin `events` module
    //       with the npm module https://www.npmjs.com/package/events
    import EventEmitter from 'events'
    import { plugins, clone } from 'isomorphic-git'
    plugins.set('emitter', emitter)

    // (In a working example you would also have to set up an 'fs' plugin.)

    const doClone = async () => {
      const onMessage = message => {
        let el = document.getElementById('cloning-message')
        el.innerText = message
      }
      const onProgress = progress => {
        let el = document.getElementById('cloning-progress-bar')
        el.setAttribute('max', progress.total)
        el.setAttribute('value', progress.loaded)
        let span = document.getElementById('cloning-percent')
        span.innerText = Math.floor(100 * progress.loaded / progress.total) + '%'
      }
      emitter.on('message', onMessage)
      emitter.on('progress', onProgress)

      // (In a working example you'd fill in the clone command arguments)
      await clone({...})

      emitter.off('message', onMessage)
      emitter.off('progress', onProgress)
    }
  </script>
</html>

Implementing your own emitter plugin

Isomorphic-git does not listen to events, it only emits them. So your emitter object technically only needs to implement the emit method.

interface GitEmitterPlugin {
  emit (event: string, data: any): void;
}

Note: This means you could rewrite the first example like this if you wanted:

const git = require('isomorphic-git')
// No need to use a full EventEmitter object here!
const emitter = {
  emit (event, message) {
    if (event === 'message') {
      console.log(message)
    }
  }
}
git.plugins.set('emitter', emitter)
← PreviousNext →