universal-git

universal-git is a pure JavaScript implementation of Git that works anywhere. Originally forked from the incredible isomorphic-git, this project was created to provide the community with a stable, actively maintained library that embraces modern JavaScript, fixes long-standing bugs, and offers a clear path forward.

If you've been frustrated by the lack of updates or unresolved issues in isomorphic-git, you've come to the right place.

✨ Why Switch to universal-git?

| Feature | isomorphic-git (Legacy) | ✅ universal-git (Modern) | | :--- | :--- | :--- | | Maintenance | ⚠️ Stagnant, PRs ignored | 🚀 Actively maintained with weekly releases | | Codebase | Old JS, callbacks, mixed promises | ✨ Modern ES Modules & async/await | | TypeScript | External, often outdated types | 📦 Ships with up-to-date types built-in | | Dependencies | Outdated, some legacy cruft | 🛡️ Lean, audited, and modern dependencies | | Bug Fixes | Many long-standing issues remain | ✅ Key bugs fixed (e.g., packfile parsing, auth) | | Community | Unresponsive | 💬 Active community on GitHub Discussions | | Roadmap | None | 🗺️ Public roadmap and clear feature pipeline |

🚀 Quick Start

1. Installation

npm install universal-git
# or
yarn add universal-git
# or
pnpm add universal-git

2. Usage Example: Clone a Repository (Node.js)

The API is designed to be intuitive and powerful. Here’s how you can clone a repository:

// index.mjs
import fs from 'node:fs'
import http from 'node:http' // Use a proper http client in production
import { clone } from 'universal-git'

// This is where we'll clone the repo
const dir = './cloned-repo'

// Let's go!
;(async () => {
  try {
    await clone({
      fs,
      http,
      dir,
      url: 'https://github.com/awesome-os/universal-git',
      onMessage: (message) => console.log(message), // Real-time progress updates
      onProgress: (progress) => console.log(`${progress.phase}: ${progress.loaded}/${progress.total}`),
    })
    console.log('✅ Repository cloned successfully!')
  } catch (error) {
    console.error('❌ Cloning failed:', error)
  }
})()

🚚 Migrating from isomorphic-git

Migrating is designed to be painless. For most projects, it's a simple 2-step process:

1. Uninstall the old package and install the new one:

   npm uninstall isomorphic-git
   npm install universal-git

2. Update your imports: Change all occurrences of 'isomorphic-git' to 'universal-git'.

   Before:

   const git = require('isomorphic-git')
   // or
   import { clone } from 'isomorphic-git'

   After:

   const git = require('universal-git') // CJS still supported
   // or (recommended)
   import { clone } from 'universal-git'

That's it! The core API remains compatible, but you now benefit from all the underlying improvements and a modern async/await-first design.

📚 Documentation

For a full API reference, tutorials, and advanced guides, please visit our official documentation site.

The documentation covers everything from basic commands like commit and push to advanced topics like plugin authoring and using custom backends.

🤝 Contributing

We welcome contributions of all kinds! Whether you're fixing a bug, adding a feature, or improving documentation, your help is appreciated.

1. Fork the repository and create your branch from main.
2. Run npm install to set up the development environment.
3. Make your changes and add tests.
4. Ensure the test suite passes (npm test).
5. Submit a pull request!

Please check our CONTRIBUTING.md for more detailed guidelines and look for issues tagged with good first issue.

❤️ Acknowledgments

This project would not be possible without the foundational work done by the original creators and contributors of isomorphic-git. We are deeply grateful for their contribution to the open-source community and aim to honor their legacy by keeping this powerful tool alive and thriving.

📜 License

This project is licensed under the MIT License.