steveukx/git-js
Git Js
git-js is a programmatic Node.js library and version control wrapper that provides a structured JavaScript API for executing Git commands. It serves as a Git automation framework and process manager, allowing developers to chain version control tasks and parse raw command output into structured data objects.
The project distinguishes itself through a dedicated Git process manager capable of spawning binaries with custom environment variables, specific process ownership, and concurrency throttling to prevent system resource exhaustion. It includes specialized system-level monitoring such as command execution tracing, progress tracking, and the ability to terminate hanging processes that stop producing output.
The library covers a comprehensive range of repository management capabilities, including branching, merging, and rebasing, as well as remote synchronization via cloning, mirroring, and pushing. It provides tools for repository state analysis, commit history retrieval, tag management, and working tree operations such as stashing, cleaning, and applying patches. Additionally, it includes utilities for object analysis, submodule management, and codebase text searching.
The library supports the specification of custom binary paths and working directories to manage version control environments across different system configurations.
Features
- Git Workflow Automation - Provides a comprehensive framework for automating version control tasks like cloning, committing, and branching within Node.js.
- Version Control Wrappers - Provides a promise-based JavaScript API that wraps system-level Git operations.
- Branch Management - Provides programmatic operations to create, list, and delete local branches.
- Branch Merging Strategies - Integrates changes from one branch into another using merging or rebasing strategies.
- Git Configuration - Provides a utility to read, add, and append Git configuration properties across local, global, and system scopes.
- Git Node.js Libraries - Provides a programmatic Node.js library for executing Git commands and managing version control workflows.
- Git Process Managers - Provides a dedicated process manager for spawning Git binaries with concurrency throttling and custom environment variables.
- Process Lifecycle Managers - Manages the complete lifecycle of Git processes, including timeouts, binary paths, and concurrency limits.
- Remote Configuration Managers - Adds, removes, and lists remote repository configurations to track external sources.
- Remote Repository Cloning - Duplicates a remote repository to a local directory to create a complete working copy.
- Remote Repository Operations - Sends local commits and tags to specified remote repositories.
- Repository State Parsers - Parses raw Git output into structured data objects to programmatically inspect branches, commits, and file differences.
- Repository Initialization - Creates new version control repositories, including support for bare repository setup.
- Automation Frameworks - Acts as a toolkit for chaining version control tasks and parsing raw command output into structured data objects.
- Git Command Execution - Provides a programmatic interface to run Git operations using promise-based chains.
- Git Process Management - Executes Git binaries with controlled concurrency, custom environment variables, and system-level process monitoring.
- Local-Remote Branch Synchronizers - Updates local databases from remote repositories and aligns branches.
- Automated Repository Maintenance - Enables scripting routine Git chores such as cleaning working directories, mirroring repositories, and updating submodules.
- Working Directory Inspections - Analyzes the working directory to identify modified, deleted, staged, or untracked files.
- Raw Command Executors - Runs arbitrary system commands and returns trimmed raw output for further processing.
- Repository Type Verifiers - Determines if a directory is a bare repository, a root directory, or inside a repository tree.
- Version Control Integrations - Provides a programmatic interface for building software tools that interact with Git repositories to manage source code.
- Version Tag Management - Supports the creation and listing of lightweight and annotated tags for release marking.
- Working Tree Restorations - Supports reverting files to previous states using soft or hard reset modes.
- Commit Reverts - Allows undoing changes by reverting specific commits or resetting the repository state.
- Process Output Streamers - Implements a system to intercept and process standard output and error streams from child processes in real-time.
- Operation Cancellation Signals - Provides a mechanism to halt running child processes by sending termination signals before tasks complete.
- System Binary Execution - Executes any version control command by passing an array of arguments directly to the system binary.
- Concurrent Task Limiters - Limits the number of parallel processes to prevent system resource exhaustion.
- Exit Code Evaluators - Provides custom logic to evaluate exit codes and stream output to trigger specific error handlers.
- Repository History Retrieval - Enables retrieval of commit lists using summary, name-only, or numerical formats.
- Concurrency Flows - Runs version control tasks in serial chains or parallel requests with managed concurrency.
- Execution Progress Tracking - Monitors long-running operations and triggers handlers with current stage and percentage progress.
- Version Difference Analysis - Generates diffs between commits or files to track changes and similarity scores.
- Task Execution Tracing - Outputs detailed logs of internal tasks and raw process data for debugging via environment variables.
- Process Termination Controls - Ships a system to automatically terminate processes that stop producing output on standard streams for a specified duration.
- Git Utilities - Interface for running Git commands.
