Package Exports

isomorphic-git

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

JavaScript library for interacting with git repositories, circa 2017

(Originally I was going to call it esgit but the name is too similar to another project called es-git.)

Progress

Porcelain:

git clone
- git init
- git config
- git fetch (due to CORS, use https://cors-anywhere.herokuapp.com/https://github.com instead of https://github.com)
  - ref-deltas
  - ofs-deltas
- git checkout
  - update index SHA correctly
git list (ls-files)
git add
git remove
git status
git commit
git push (due to CORS, use https://cors-anywhere.herokuapp.com/https://github.com instead of https://github.com)
git tag
git diff
git merge
esgit CLI

Plumbing:

read-tree
git listCommits (rev-list)
git pack (pack-objects)
git list packed objects (verify-pack)
git unpack-objects

Note: There appears to be no a way to push signed commits back to Github using their API (v3 or v4), so I think we will have to use smart HTTP, packfiles, and an anti-CORS proxy.

High-level API (unstable)

This is analogous to the "porcelain" git commands. There is a single function git() that serves as a fluent command builder.

Examples:

import git from 'isomorphic-git'

// Clone a repository
git('.')
  .depth(1)
  .branch('master')
  .clone('https://cors-anywhere.herokuapp.com/https://github.com/wmhilton/isomorphic-git')

// Setup an new repository
git('.').init()

// Manually add a remote
git('.')
  .setConfig('remote.origin.url', 'https://cors-anywhere.herokuapp.com/https://github.com/wmhilton/isomorphic-git')

// Fetch the latest commit using a shallow clone
git('.')
  .remote('origin')
  .depth(1)
  .fetch('refs/heads/master')

// Checkout a commitish
git('.').checkout('master')

// List files in the index
git('.').list()

// Add files to the index
git('.').add('README.md')

// Remove files from the index
git('.').remove('.env')

// Create a new commit (there's actually several more options for date, committer)
git('.')
  .add('a.txt')
  .author('Mr. Test')
  .email('mrtest@example.com')
  .signingKey('-----BEGIN PGP PRIVATE KEY BLOCK-----...')
  .commit('Added the a.txt file')

// Push a branch back to Github
git('.')
  .githubToken(process.env.GITHUB_TOKEN)
  .remote('origin')
  .push('refs/heads/master')

// TODO: git.merge(), git.pull(), git.status(), git.diff(), git.tag(), git.branch(), etc

// And if you need to work with bare repos there are
// equivalents to the `--git-dir` and `--work-tree` options
git().gitdir('my-bare-repo').workdir('/var/www/website')

CLI

I realized I could "translate" command line options into JavaScript chained commands without hard-coding any knowledge of the API if I kept the chained commands very predictable. I built a purely a generic translator and it worked surprisingly well. So you can do any current or future isomorphic-git commands using the included esgit CLI. It always starts with an implicit git('.') so it defaults to working in the current working directory.

// Create a new empty repo
esgit --gitdir=test init

// Clone from a Github repository to the current working directory.
// Just like it's counterpart, clone is really just shorthand for git.init(); git.fetch(); git.checkout();
esgit clone https://github.com/wmhilton/isomorphic-git

// Checkout a commitish
esgit checkout master

// List files in the index
esgit list

// Add files to the index
esgit add README.md

// Remove files from the index
esgit remove .env

// Create a new commit (there's actually several more options for date, committer)
esgit add a.txt
esgit --author='Mr. Test' --email=mrtest@example.com --signingKey="$(cat private.key)" commit 'Added the a.txt file'

// And if you need to work with bare repos there are
// equivalents to the `--git-dir` and `--work-tree` options
esgit --gitdir=my-bare-repo --workdir=/var/www/website

Low-level API (also unstable)

The high-level makes some assumptions (like you have a file-system and network access) that might not be well suited to your embedded git-based concept thingy. Fear not! I am purposefully building this library as a series of small modules so you can pick and choose features as you need them.

Commands

import * as managers from 'isomorphic-git/src/commands'

Each command is available as its own file, so hopefully with a bit of finagling you will be able to import individual commands if you only need a few and can benefit from tree-shaking.

Managers

import * as managers from 'isomorphic-git/src/managers'

Managers are a level above models. They take care of implementation performance details like

batching reads to and from the file system
in-process concurrency locks
lockfiles
caching files and invalidating cached results
reusing objects
object memory pools

Models

import * as models from 'isomorphic-git/src/models'

Models are the lowest level building blocks. They generally have very few or no dependencies except for 'buffer'. This makes them portable to many different environments so they can be a useful lowest common denominator.

Utils

import * as utils from 'isomorphic-git/src/utils'

I lied. Utils are actually the lowest level building blocks.