@push.rocks/smartgit

smart wrapper for nodegit

Install

To install @push.rocks/smartgit, use the following command with npm:

npm install @push.rocks/smartgit --save

Or if you prefer using yarn:

yarn add @push.rocks/smartgit

Make sure you have node installed on your system to use this package.

Usage

This guide assumes familiarity with TypeScript and basic Git operations. The @push.rocks/smartgit module offers a sophisticated, promise-based interface to interact with Git repositories in a Node.js environment, abstracting over the isomorphic-git library and adding additional functionality.

Setting Up

First, you need to import Smartgit and other necessary classes from the package. This is also when you'd typically configure any additional settings or dependencies required by your project.

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

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

Creating, Cloning, and Opening Repositories

With Smartgit, you can easily manage local repositories by creating new ones, cloning existing repositories, or opening an already existing local repository.

Creating a New Repository

const pathToNewRepo = '/path/to/your/new/repo';
const newRepo = await smartgit.createRepoByInit(pathToNewRepo);

Cloning a Repository

const cloneUrl = 'https://github.com/yourusername/your-repo.git';
const pathToClone = '/path/to/clone/repo';
const clonedRepo = await smartgit.createRepoByClone(cloneUrl, pathToClone);

Opening an Existing Repository

const pathToExistingRepo = '/path/to/your/existing/repo';
const existingRepo = await smartgit.createRepoByOpen(pathToExistingRepo);

Working with Git Operations

Smartgit simplifies common Git operations, making it easy to execute commands like add, commit, push, and more programmatically.

Adding Changes

To stage changes, you can add all changes or specify particular files.

// Add all changes to staging
await existingRepo.addAll();

// Or specify particular files
await existingRepo.add(['file1.txt', 'path/to/file2.txt']);

Committing Changes

Once changes are staged, you can commit them.

await existingRepo.commit('Your commit message');

Pushing to a Remote

Before pushing, ensure a remote is set up correctly, then push your changes.

await existingRepo.ensureRemote('origin', 'https://github.com/yourusername/your-repo.git');
await existingRepo.pushBranchToRemote('main', 'origin');

Advanced Features

Smartgit also supports more advanced Git functionalities, such as dealing with branches, managing remotes, and checking repository status.

Listing Remotes

const remotes = await existingRepo.listRemotes();
console.log(remotes);

Working with Branches

Branch management such as creating new branches or checking out existing ones can be done through the underlying isomorphic-git functions, with Smartgit making the setup and usage straightforward.

Practical Tips

When dealing with asynchronous operations, especially in sequences that depend on the outcome of previous steps (e.g., staging, committing, and pushing), ensure proper error handling, either using .then().catch() chains or try/catch blocks with async/await.
For complex Git workflows, consider combining Smartgit's capabilities with other Node.js modules or scripts to automate and streamline your processes.

Conclusion

@push.rocks/smartgit provides a versatile and powerful toolkit for Git operations in Node.js applications. By abstracting the complexities of interacting with Git repositories, it enables developers to focus more on developing their logic and less on the intricacies of Git commands. Whether you're managing local repositories, automating deployment workflows, or integrating Git operations into your applications, Smartgit offers a comprehensive set of features to address your needs.

For further examples, contributions, and issues, please refer to the project's repository and consider contributing to or starring the project if you find it useful.

License and Legal Information

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.