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: 'you@example.com'
},
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.
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 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.
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>
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.
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:
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/",
"browser": "dist/for-browserify/",
"module": "dist/for-future/",
"unpkg": "dist/bundle.umd.min.js",
This 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.
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
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:
Contributors
Thanks goes to these wonderful people (emoji key):
This project follows the all-contributors specification. Contributions of any kind welcome!
Backers
Thank you to all our backers! π [Become a backer]
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