@push.rocks/smartgit

A smart wrapper for nodegit that simplifies Git operations in Node.js.

readme.md for @push.rocks/smartgit

🚀 Modern Git operations for Node.js - A powerful TypeScript wrapper around isomorphic-git that makes repository management and analysis a breeze

npm version TypeScript

✨ What is SmartGit?

SmartGit is a sophisticated, promise-based Git toolkit designed for Node.js applications. Built on top of isomorphic-git, it provides a clean, intuitive API for repository management, diff analysis, and commit history exploration. Perfect for automation tools, CI/CD pipelines, and any application that needs to interact with Git repositories programmatically.

🎯 Key Features

📦 Installation

# Using pnpm (recommended)
pnpm install @push.rocks/smartgit

# Using npm
npm install @push.rocks/smartgit

# Using yarn
yarn add @push.rocks/smartgit

🚀 Quick Start

import { Smartgit } from '@push.rocks/smartgit';

// Initialize SmartGit
const smartgit = new Smartgit();
await smartgit.init();

// Clone a repository
const repo = await smartgit.createRepoByClone(
  'https://github.com/username/repo.git',
  './local-repo'
);

console.log('🎉 Repository cloned successfully!');

📖 Usage Guide

🏗️ Repository Operations

Creating a New Repository

const repo = await smartgit.createRepoByInit('./my-new-repo');

Cloning from Remote

const repo = await smartgit.createRepoByClone(
  'https://github.com/octocat/Hello-World.git',
  './hello-world'
);

Opening Existing Repository

const repo = await smartgit.createRepoByOpen('./existing-repo');

🌐 Working with Remotes

List All Remotes

const remotes = await repo.listRemotes();
console.log(remotes);
// Output: [{ remote: 'origin', url: 'https://github.com/...' }]

Ensure Remote Exists

await repo.ensureRemote('origin', 'https://github.com/username/repo.git');

Get Remote URL

const originUrl = await repo.getUrlForRemote('origin');
console.log(`📡 Origin URL: ${originUrl}`);

Push to Remote

await repo.pushBranchToRemote('main', 'origin');
console.log('✅ Changes pushed successfully!');

📊 Diff Analysis

Get a detailed diff of uncommitted changes (perfect for code review automation):

const diffs = await repo.getUncommittedDiff(['node_modules/*', '*.log']);

diffs.forEach(diff => {
  console.log('📝 File changes:');
  console.log(diff);
});

📚 Commit History Analysis

Extract commit history with package.json version tracking:

const history = await repo.getAllCommitMessages();

history.forEach(commit => {
  console.log(`🕐 ${commit.date} | v${commit.version} | ${commit.message}`);
});

// Example output:
// 🕐 2024-01-15 | v1.2.3 | feat: add new authentication method
// 🕐 2024-01-14 | v1.2.2 | fix: resolve memory leak in parser

🛠️ Advanced Usage

Error Handling

try {
  const repo = await smartgit.createRepoByClone(invalidUrl, './test');
} catch (error) {
  console.error('❌ Clone failed:', error.message);
}

Working with Multiple Repositories

const smartgit = new Smartgit();
await smartgit.init();

const repositories = [
  await smartgit.createRepoByOpen('./repo1'),
  await smartgit.createRepoByOpen('./repo2'),
  await smartgit.createRepoByOpen('./repo3')
];

// Analyze all repositories
for (const repo of repositories) {
  const remotes = await repo.listRemotes();
  console.log(`📂 Repository has ${remotes.length} remotes`);
}

🏗️ Architecture

SmartGit is built with a clean, modular architecture:

🎯 Use Cases

🔧 Requirements

🤝 API Reference

Smartgit Class

Method Description Returns
init() Initialize the SmartGit instance Promise<void>
createRepoByInit(dir) Create new repository Promise<GitRepo>
createRepoByClone(url, dir) Clone repository Promise<GitRepo>
createRepoByOpen(dir) Open existing repository Promise<GitRepo>

GitRepo Class

Method Description Returns
listRemotes() List all remotes Promise<{remote: string, url: string}[]>
ensureRemote(name, url) Ensure remote exists Promise<void>
getUrlForRemote(name) Get URL for remote Promise<string>
pushBranchToRemote(branch, remote) Push branch to remote Promise<void>
getUncommittedDiff(excludeFiles?) Get uncommitted changes Promise<string[]>
getAllCommitMessages() Get commit history Promise<CommitInfo[]>

💡 Pro Tips

This repository contains open-source code that is licensed under the MIT License. A copy of the MIT License can be found in the license file within this repository.

Please note: The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.

Trademarks

This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH and are not included within the scope of the MIT license granted herein. Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines, and any usage must be approved in writing by Task Venture Capital GmbH.

Company Information

Task Venture Capital GmbH
Registered at District court Bremen HRB 35230 HB, Germany

By using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.

changelog.md for @push.rocks/smartgit

2025-11-04 - 3.3.1 - fix(getUncommittedDiff)

Avoid false-positive diffs in getUncommittedDiff by detecting symlinked directories and skipping identical files

2025-11-04 - 3.3.0 - feat(GitRepo)

Add glob-pattern exclusions for getUncommittedDiff and add minimatch; bump dependencies

2025-01-04 - 3.2.0 - feat(core)

Enhanced error handling, type safety, and documentation

2024-06-23 - 3.1.1 - fix(documentation)

Remove outdated changelog entries

2024-06-23 - 3.1.0 - gitrepo

Enhancements and fixes to GitRepo

2024-06-22 - 3.0.3 to 3.0.4 - core & GitRepo

General updates and new feature addition

2023-11-15 - 3.0.1 to 3.0.2 - core, tsconfig, npmextra

Minor updates and fixes

2023-07-10 - 3.0.0 - core

Structural changes to organization scheme

2023-07-27 - 3.0.0 to 3.0.1 - core

Structural changes and updates

2022-07-31 - 2.0.2 to 3.0.0 - core

Breaking changes and updates

2021-10-22 - 1.0.18 to 2.0.1 - dependencies, core

Breaking changes and updates

2020-08-15 - 1.0.14 to 1.0.18 - core

Fixes

2019-06-18 - 1.0.5 to 1.0.10 - core

Fixes

2016-06-23 - 0.0.10 to 0.1.11 - gitlab & other fixes

Initial implementations and setup