isomorphic-git

What is isomorphic-git?

isomorphic-git is a pure JavaScript implementation of Git that works in both Node.js and browser environments. It provides a wide range of Git functionalities, allowing developers to perform Git operations without relying on native Git installations.

What are isomorphic-git's main functionalities?

Clone a Repository

This feature allows you to clone a Git repository. The code sample demonstrates how to clone the isomorphic-git repository into a local directory named '/tutorial'.

const git = require('isomorphic-git');
const fs = require('fs');

(async () => {
  await git.clone({
    fs,
    dir: '/tutorial',
    url: 'https://github.com/isomorphic-git/isomorphic-git',
    singleBranch: true,
    depth: 1
  });
  console.log('Cloned the repository!');
})();

Commit Changes

This feature allows you to commit changes to a repository. The code sample demonstrates how to commit changes in the '/tutorial' directory with a commit message 'Initial commit'.

const git = require('isomorphic-git');
const fs = require('fs');

(async () => {
  await git.commit({
    fs,
    dir: '/tutorial',
    author: {
      name: 'Your Name',
      email: '[e-mail]'
    },
    message: 'Initial commit'
  });
  console.log('Committed changes!');
})();

Push to Remote

This feature allows you to push changes to a remote repository. The code sample demonstrates how to push changes from the '/tutorial' directory to the 'main' branch of the remote repository 'origin'.

const git = require('isomorphic-git');
const fs = require('fs');

(async () => {
  await git.push({
    fs,
    dir: '/tutorial',
    remote: 'origin',
    ref: 'main',
    token: 'your-github-token'
  });
  console.log('Pushed to remote!');
})();

Fetch from Remote

This feature allows you to fetch changes from a remote repository. The code sample demonstrates how to fetch changes from the 'origin' remote repository into the '/tutorial' directory.

const git = require('isomorphic-git');
const fs = require('fs');

(async () => {
  await git.fetch({
    fs,
    dir: '/tutorial',
    remote: 'origin'
  });
  console.log('Fetched from remote!');
})();

List Files in a Commit

This feature allows you to list files in a specific commit. The code sample demonstrates how to read the commit object for the 'HEAD' commit and log the tree of files.

const git = require('isomorphic-git');
const fs = require('fs');

(async () => {
  const commit = await git.readCommit({
    fs,
    dir: '/tutorial',
    oid: 'HEAD'
  });
  console.log(commit.commit.tree);
})();

Other packages similar to isomorphic-git

nodegit

NodeGit is a native Node.js binding to the libgit2 library, providing a comprehensive set of Git functionalities. Unlike isomorphic-git, NodeGit relies on native bindings and is not designed to work in browser environments.

simple-git

Simple-git is a lightweight wrapper around the Git command line interface, providing a simple API for common Git operations. It requires Git to be installed on the system and is not designed to work in browser environments, unlike isomorphic-git.

dugite

Dugite provides a simplified interface for using Git in Node.js applications. It bundles a specific version of Git with the package, ensuring consistent behavior across different environments. However, it does not support browser environments like isomorphic-git.

README

isomorphic-git

A pure JavaScript implementation of git for node and browsers!

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

Unlike earlier git-in-js solutions that were hypermodular, isomorphic-git aims to be a complete solution with no assembly required. The high-level API is a fluent interface modeled after the git CLI and should feel natural to read and write. However, one size does not always fit. That's why isomorphic-git also has a layered API that frees you to build a solution using only the exact features you need.

---

Table of Contents generated with DocToc

• Getting Started
  • Set up your filesystem
  • Using a CDN script tag
  • Using as an npm module
  • isogit CLI
• High-level git() API
  • git(dir) vs .gitdir(dir) and .workdir(dir)
  • .init()
  • .clone(url)
  • .fetch(branch)
  • .checkout(branch)
  • .list()
  • .log(ref)
  • .add(file)
  • .remove(file)
  • .status(file)
  • .commit(msg)
  • .push(branch)
  • .findRoot(dir)
  • .listBranches()
  • .config(path)
  • .config(path, value)
  • .auth(username, password_or_token)
  • .oauth2(company, token)
  • .version()
• Lower-level API
  • Commands
  • Managers
  • Models and Utils
• Who is using isomorphic-git?
• Similar projects
• Acknowledgments
• License

---

Getting Started

Set up your filesystem

If you're only using isomorphic-git in Node, you already have a fs module, so you can skip this step. If you're writing code for the browser though, you'll need something that emulates the fs API. isomorphic-git will look for a global "fs" variable. At the time of writing, the most complete option is BrowserFS.

Here's a quick config that works well in most cases:

<script src="https://unpkg.com/browserfs"></script>
<script>
BrowserFS.configure({ fs: "IndexedDB", options: {} }, err => {
  if (err) {
    alert(err);
  } else {
    window.fs = BrowserFS.BFSRequire("fs");
  }
});
</script>

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 filesystems 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 in the IndexedDB backend I suggested above.

Using a CDN script tag

If you want, you can just throw in a script tag with the UMD build directly from unpkg. This will result in three global variables: BrowserFS, fs, and git.

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

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/",
  "browser": "dist/for-browserify/",
  "module": "dist/for-future/",
  "unpkg": "dist/bundle.umd.min.js",

This probably deserves a brief explanation.

• the "main" version is for node.
• the "browser" version is for browserify.
• the "module" version is for native ES6 module loaders when they arrive.
• the "unpkg" version is the UMD build.

For more details about each build see ./dist/README.md

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 implicit git('.') so it defaults to working in the current working directory. (Note I may change that soon, now that I have a findRoot function. I may change the default to git(git().findRoot(process.cwd())).)

High-level git() API

I may continue to make small changes to the API until the 1.0 release, after which I promise not to make any breaking changes.

git(dir) vs .gitdir(dir) and .workdir(dir)

Setting the working directory and git directory

For regular repositories (with a .git directory inside them) you simply pass the directory as the initial argument to git(). In this case, the git directory is set implicitly to path.join(workdir, '.git').

However, if you are working with bare repositories, that assumption is wrong. In this case, you can use the second version to specify the directories explicitly.

// JS example
import git from 'isomorphic-git'
git('./path/to/repo')
// second way
git()
  .gitdir('my-bare-repo')
  .workdir('/var/www/website')

# CLI example
cd ./path/to/repo
isogit
# second way
isogit --gitdir=my-bare-repo --workdir=/var/www/website

// Complete API
git(workdir)
// second way
git()
  .gitdir(gitdir)
  .workdir(workdir)

• @param {string} workdir - The path to the working directory.

The working directory is where your files are checked out. Usually this is the parent directory of ".git" but it doesn't have to be.

• @param {string} gitdir - The path to the git directory.

The git directory is where your git repository history is stored. Usually this is a directory called ".git" inside your working directory.

.init()

Initialize a new repository

// JS example
import git from 'isomorphic-git'
git('.').init()

# CLI example
isogit init

// Complete API
git()
  .gitdir(gitdir)
  .init()

• @param {string} gitdir - The path to the git directory.
• @returns Promise<void>

.clone(url)

Clone a repository

// JS example
import git from 'isomorphic-git'
git('.')
  .depth(1)
  .clone('https://cors-buster-jfpactjnem.now.sh/github.com/wmhilton/isomorphic-git')

# CLI example
isogit --depth=1 clone https://github.com/wmhilton/isomorphic-git

// Complete API
git()
  .workdir(workdir)
  .gitdir(gitdir)
  .branch(ref)
  .auth(authUsername, authPassword)
  .remote(remote)
  .depth(depth)
  .since(since)
  .exclude(exclude)
  .relative(relative)
  .onprogress(progressHandler)
  .clone(url)

• @param {string} workdir - The path to the working directory.
• @param {string} gitdir - The path to the git directory.
• @param {string} [ref=undefined] - Which branch to clone. By default this is the designated "main branch" of the repository.
• @param {string} [authUsername=undefined] - The username to use with Basic Auth
• @param {string} [authPassword=undefined] - The password to use with Basic Auth
• @param {string} [remote='origin'] - What to name the remote that is created. The default is 'origin'.
• @param {string} url - The URL of the remote repository.
• @param {integer} [depth=undefined] - Determines how much of the git repository's history to retrieve.
• @param {Date} [since=undefined] - Only fetch commits created after the given date. Mutually exclusive with depth.
• @param {string[]} [exclude=[]] - A list of branches or tags. Instructs the remote server not to send us any commits reachable from these refs.
• @param {boolean} [relative=false] - Changes the meaning of depth to be measured from the current shallow depth rather than from the branch tip.
• @param {Function} [progressHandler=undefined] - Callback to receive ProgressEvents for the operation.
• @returns Promise<void>

.fetch(branch)

Fetch commits

// JS example
import git from 'isomorphic-git'
git('.')
  .remote('origin')
  .depth(1)
  .fetch('master')

# CLI example
isogit --remote=origin --depth=1 fetch master

// Complete API
git()
  .gitdir(gitdir)
  .auth(authUsername, authPassword)
  .url(url)
  .remote(remote)
  .depth(depth)
  .since(since)
  .exclude(exclude)
  .relative(relative)
  .onprogress(progressHandler)
  .fetch(ref)

• @param {string} gitdir - The path to the git directory.
• @param {string} [ref=undefined] - Which branch to fetch from. By default this is the currently checked out branch.
• @param {string} [authUsername=undefined] - The username to use with Basic Auth
• @param {string} [authPassword=undefined] - The password to use with Basic Auth
• @param {string} [url=undefined] - The URL of the remote git server. The default is the value set in the git config for that remote.
• @param {string} [remote='origin'] - If URL is not specified, determines which remote to use.
• @param {integer} [depth=undefined] - Determines how much of the git repository's history to retrieve.
• @param {Date} [since=undefined] - Only fetch commits created after the given date. Mutually exclusive with depth.
• @param {string[]} [exclude=[]] - A list of branches or tags. Instructs the remote server not to send us any commits reachable from these refs.
• @param {boolean} [relative=false] - Changes the meaning of depth to be measured from the current shallow depth rather than from the branch tip.
• @param {Function} [progressHandler=undefined] - Callback to receive ProgressEvents for the operation.
• @returns Promise<void>

.checkout(branch)

Checkout a branch

// JS example
import git from 'isomorphic-git'
git('.')
  .checkout('master')

# CLI example
isogit checkout master

// Complete API
git()
  .workdir(workdir)
  .gitdir(gitdir)
  .remote(remote)
  .checkout(ref)

• @param {string} workdir - The path to the working directory.
• @param {string} gitdir - The path to the git directory.
• @param {string} [ref=undefined] - Which branch to clone. By default this is the designated "main branch" of the repository.
• @param {string} [remote='origin'] - What to name the remote that is created. The default is 'origin'.
• @returns Promise<void>

.list()

List all the tracked files in a repo

// JS example
import git from 'isomorphic-git'
git('.')
  .list()

# CLI example
isogit list

// Complete API
git()
  .gitdir(gitdir)
  .list()

• @param {string} gitdir - The path to the git directory.
• @returns Promise<string[]> - A list of file paths.

.log(ref)

Get commit descriptions from the git history

// JS example
import git from 'isomorphic-git'
let commits = await git('.')
  .depth(5)
  .log('master')
commits.map(c => console.log(JSON.stringify(c))

# CLI example
isogit --depth=5 log master

// Complete API
git()
  .gitdir(gitdir)
  .depth(depth)
  .since(since)
  .log(ref)

• @param {string} gitdir - The path to the git directory.
• @param {integer} [depth=undefined] - Return at most this many commits.
• @param {Date} [since=undefined] - Return history newer than the given date. Can be combined with depth to get whichever is shorter.
• @param {string} [ref=HEAD] - The commit to begin walking backwards through the history from.
• @returns Promise<CommitDescription[]>

type CommitDescription = {
  oid: string,             // SHA1 oid of this commit
  message: string,         // Commit message
  tree: string,            // SHA1 oid or corresponding file tree
  parent: string[],        // array of zero or more SHA1 oids
  author: {
    name: string,
    email: string,
    timestamp: number,     // UTC Unix timestamp in seconds
    timezoneOffset: number // Timezone difference from UTC in minutes
  },
  committer: {
    name: string,
    email: string,
    timestamp: number,     // UTC Unix timestamp in seconds
    timezoneOffset: number // Timezone difference from UTC in minutes
  },
  gpgsig: ?string          // PGP signature (if present)
}

.add(file)

Add files to the git index (aka staging area)

// JS example
import git from 'isomorphic-git'
git('.')
  .add('README.md')

# CLI example
isogit add README.md

// Complete API
git()
  .workdir(workdir)
  .gitdir(gitdir)
  .add(filepath)

• @param {string} workdir - The path to the working directory.
• @param {string} gitdir - The path to the git directory.
• @param {string} filepath - The path to the file to add to the index.
• @returns Promise<void>

.remove(file)

Remove files from the git index (aka staging area)

// JS example
import git from 'isomorphic-git'
git('.')
  .remove('README.md')

# CLI example
isogit remove README.md

// Complete API
git()
  .gitdir(gitdir)
  .remove(filepath)

• @param {string} gitdir - The path to the git directory.
• @param {string} filepath - The path to the file to add to the index.
• @returns Promise<void>

.status(file)

Tell whether a file has been changed

// JS example
import git from 'isomorphic-git'
git('.')
  .status('README.md')

# CLI example
isogit status README.md

// Complete API
git()
  .workdir(workdir)
  .gitdir(gitdir)
  .status(filepath)

• @param {string} workdir - The path to the working directory.
• @param {string} gitdir - The path to the git directory.
• @param {string} filepath - The path to the file to query.
• @returns Promise<String>

The possible return values are:

• "ignored" file ignored by a .gitignore rule
• "unmodified" file unchanged from HEAD commit
• "*modified" file has modifications, not yet staged
• "*deleted" file has been removed, but the removal is not yet staged
• "*added" file is untracked, not yet staged
• "absent" file not present in HEAD commit, staging area, or working dir
• "modified" file has modifications, staged
• "deleted" file has been removed, staged
• "added" previously untracked file, staged
• "*unmodified" working dir and HEAD commit match, but index differs
• "*absent" file not present in working dir or HEAD commit, but present in the index

.commit(msg)

Create a new commit

// JS example
import git from 'isomorphic-git'
git('.')
  .author('Mr. Test')
  .email('[e-mail]')
  .signingKey('-----BEGIN PGP PRIVATE KEY BLOCK-----...')
  .commit('Added the a.txt file')

# CLI example
isogit --author='Mr. Test' \
       --email=[e-mail] \
       --signingKey="$(cat private.key)" \
       commit 'Added the a.txt file'

// Complete API
git()
  .gitdir(gitdir)
  .author(author.name)
  .email(author.email)
  .timestamp(author.timestamp)
  .datetime(author.date)
  .signingKey(privateKeys)
  .commit(message)

• @param {string} gitdir - The path to the git directory.
• @param {Object} author - The details about the commit author.
• @param {string} [author.name=undefined] - Default is user.name config.
• @param {string} [author.email=undefined] - Default is user.email config.
• @param {Date} [author.date=new Date()] - Set the author timestamp field. Default is the current date.
• @param {integer} [author.timestamp=undefined] - Set the author timestamp field. This is an alternative to using date using an integer number of seconds since the Unix epoch instead of a JavaScript date object.
• @param {Object} [committer=author] - The details about the commit author. If not specified, the author details are used.
• @param {string} message - The commit message to use.
• @param {string} [privateKeys=undefined] - A PGP private key in ASCII armor format.
• @returns Promise<void>

.push(branch)

Push a branch

// JS example
import git from 'isomorphic-git'
git('.')
  .auth(process.env.GITHUB_TOKEN)
  .remote('origin')
  .push('master')

# CLI example
isogit --auth="$GITHUB_TOKEN" --remote=origin push master

// Complete API
git()
  .gitdir(gitdir)
  .depth(depth)
  .remote(remote)
  .url(url)
  .auth(authUsername, authPassword)
  .push(ref)

• @param {string} gitdir - The path to the git directory.
• @param {integer} [depth=0] - Determines how much of the git repository's history to retrieve. If not specified it defaults to 0 which means the entire repo history.
• @param {string} [ref=undefined] - Which branch to push. By default this is the currently checked out branch of the repository.
• @param {string} [authUsername=undefined] - The username to use with Basic Auth
• @param {string} [authPassword=undefined] - The password to use with Basic Auth
• @param {string} [url=undefined] - The URL of the remote git server. The default is the value set in the git config for that remote.
• @param {string} [remote='origin'] - If URL is not specified, determines which remote to use.
• @returns Promise<void>

.findRoot(dir)

Find the root git directory

// JS example
import git from 'isomorphic-git'
git()
  .findRoot('/path/to/some/gitrepo/path/to/some/file.txt')
// returns '/path/to/some/gitrepo'

# CLI example
isogit findRoot /path/to/some/gitrepo/path/to/some/file.txt
# prints /path/to/some/gitrepo

// Complete API
git()
  .findRoot(dir)

• @param {string} dir - Starting at directory {dir}, walk upwards until you find a directory that contains a '.git' directory.
• @returns Promise<rootdir> that directory, which is presumably the root directory of the git repository containing {dir}.

.listBranches()

List all local branches

// JS example
import git from 'isomorphic-git'
git('.').listBranches()

# CLI example
isogit listBranches

// Complete API
git()
  .gitdir(gitdir)
  .listBranches()

• @param {string} gitdir - The path to the git directory.
• @returns Promise<branches[]> an array of branch names.

.config(path)

Reading from git config

// JS example
import git from 'isomorphic-git'
git('.').config('user.name')
// 'Mr. Test'

# CLI example
isogit config user.name
# Mr. Test

// Complete API
git()
  .gitdir(gitdir)
  .config(path)

• @param {string} gitdir - The path to the git directory.
• @param {string} path - The key of the git config entry.
• @returns Promise<value> - the config value

.config(path, value)

Writing to git config

// JS example
import git from 'isomorphic-git'
git('.').config('user.name', 'Mr. Test')

# CLI example
isogit config user.name 'Mr. Test'

// Complete API
git()
  .gitdir(gitdir)
  .config(path, value)

• @param {string} gitdir - The path to the git directory.
• @param {string} path - The key of the git config entry.
• @param {string} value - A value to store at that path.
• @returns Promise<void>

.auth(username, password_or_token)

Authentication is normally required for pushing to a git repository. It may also be required to clone or fetch from a private repository. Git does all its authentication using HTTPS Basic Authentication. Usually this is straightforward, but there are some things to watch out for.

If you have two-factor authentication (2FA) enabled on your account, you probably cannot push or pull using your regular username and password. Instead, you may have to create a Personal Access Token (or an App Password in Bitbucket lingo) and use that to authenticate.

// This works for basic username / password auth, or the newer username / token auth
// that is often required if 2FA is enabled.
git('.').auth('username', 'password')

// a one-argument version is also supported
git('.').auth('username:password')

// Personal Access Token Authentication
// (note Bitbucket calls theirs App Passwords instead for some reason)
git('.').auth('username', 'personal access token')
git('.').auth('username', 'app password')
git('.').auth('personal access token') // Github (only) lets you leave out the username

.oauth2(company, token)

If you are using OAuth2 for token-based authentication, then the form that the Basic Auth headers take is slightly different. To help with those cases, there is an oauth2() method that is available as an alternative to the auth() method.

// OAuth2 Token Authentication
// This for is for *actual* OAuth2 tokens (not "personal access tokens").
// Unfortunately, all the major git hosting companies have chosen different conventions!
// Lucky for you, I already looked up and codified it for you.
//
// - oauth2('github', token) - Github uses `token` as the username, and 'x-oauth-basic' as the password.
// - oauth2('bitbucket', token) - Bitbucket uses 'x-token-auth' as the username, and `token` as the password.
// - oauth2('gitlab', token) - Gitlab uses 'oauth2' as the username, and `token` as the password.
//
// I will gladly accept pull requests for more companies' conventions.
git('.').oauth2('github', 'token')
git('.').oauth2('gitlab', 'token')
git('.').oauth2('bitbucket', 'token')

.version()

// JS example
import git from 'isomorphic-git'
console.log(git().version())

• @returns {string} version - the version string from package.json

Lower-level API

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 have written this library as a series of layers that should tree-shake very well:

• index.js (~5kb uncompressed)
• commands.js (~19kb uncompressed)
• managers.js (~11kb uncompressed)
• models.js (~19kb uncompressed)
• utils.js (~11kb uncompressed)

Commands

import {
  add,
  clone,
  checkout,
  commit,
  fetch,
  init,
  list,
  listCommits,
  listObjects,
  log,
  pack,
  push,
  remove,
  resolveRef,
  config,
  unpack,
  verify,
  status,
  findRoot,
  listBranches,
  version
} from 'isomorphic-git/dist/for-node/commands'

Each command is available as its own file, so you are able to import individual commands if you only need a few and are willing to sacrifice the fluent API in order to optimize your bundle size.

Managers

import {
  GitConfigManager,
  GitShallowManager,
  GitIndexManager,
  GitObjectManager,
  GitRefsManager,
  GitRemoteHTTP
} from 'isomorphic-git/dist/for-node/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 and Utils

import {
  GitCommit,
  GitConfig,
  GitPktLine,
  GitIndex,
  GitTree
} from 'isomorphic-git/dist/for-node/models'

Models and utils are the lowest level building blocks. Models 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. They do not rely on Utils.

import {
  rm,
  flatFileListToDirectoryStructure,
  default,
  lock,
  mkdirs,
  read,
  sleep,
  write,
  pkg
} from 'isomorphic-git/dist/for-node/utils'

Utils are basically miscellaneous functions. Some are convenience wrappers for common filesystem operations.

Who is using isomorphic-git?

• nde - a futuristic next-generation web IDE
• git-app-manager - install "unhosted" websites locally by git cloning them

Similar projects

• js-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!) I would not have been able to come even close to finishing this. They are geniuses ahead of their time.

License

This work is released under The Unlicense