@eldrforge/git-tools

Git utilities for automation - secure process execution and comprehensive Git operations.

Features

• Secure Process Execution - Shell injection prevention with validated arguments
• Comprehensive Git Operations - 20+ Git utilities for automation
• Semantic Version Support - Intelligent tag finding and version comparison
• Branch Management - Sync checking, safe syncing, and status queries
• NPM Link Management - Link detection, compatibility checking, and problem diagnosis
• Flexible Logging - Bring your own logger or use the built-in console logger

Installation

npm install @eldrforge/git-tools

Quick Start

import { getCurrentBranch, getGitStatusSummary, findPreviousReleaseTag } from '@eldrforge/git-tools';

// Get current branch
const branch = await getCurrentBranch();
console.log(`Current branch: ${branch}`);

// Get comprehensive status
const status = await getGitStatusSummary();
console.log(`Status: ${status.status}`);

// Find previous release tag
const previousTag = await findPreviousReleaseTag('1.2.3', 'v*');
console.log(`Previous release: ${previousTag}`);

Custom Logger

By default, git-tools uses a console-based logger. You can provide your own logger implementation (e.g., Winston):

import { setLogger } from '@eldrforge/git-tools';
import winston from 'winston';

// Create Winston logger
const logger = winston.createLogger({
    level: 'info',
    format: winston.format.json(),
    transports: [new winston.transports.Console()]
});

// Use Winston with git-tools
setLogger(logger);

Core Modules

Process Execution (child.ts)

Secure command execution with shell injection prevention:

import { runSecure, runSecureWithDryRunSupport } from '@eldrforge/git-tools';

// Secure execution with argument array
const { stdout } = await runSecure('git', ['status', '--porcelain']);

// With dry-run support
const result = await runSecureWithDryRunSupport('git', ['commit', '-m', 'message'], isDryRun);

Git Operations (git.ts)

Comprehensive Git utilities:

Branch Operations:

import {
    getCurrentBranch,
    localBranchExists,
    remoteBranchExists,
    isBranchInSyncWithRemote,
    safeSyncBranchWithRemote
} from '@eldrforge/git-tools';

const branch = await getCurrentBranch();
const exists = await localBranchExists('main');
const syncStatus = await isBranchInSyncWithRemote('main');

Tag & Version Operations:

import {
    findPreviousReleaseTag,
    getCurrentVersion,
    getDefaultFromRef
} from '@eldrforge/git-tools';

const currentVersion = await getCurrentVersion();
const previousTag = await findPreviousReleaseTag('1.2.3', 'v*');
const defaultRef = await getDefaultFromRef(false, 'working');

Status Operations:

import { getGitStatusSummary } from '@eldrforge/git-tools';

const status = await getGitStatusSummary();
// {
//   branch: 'main',
//   hasUnstagedFiles: false,
//   hasUncommittedChanges: false,
//   hasUnpushedCommits: true,
//   unstagedCount: 0,
//   uncommittedCount: 0,
//   unpushedCount: 2,
//   status: '2 unpushed'
// }

NPM Link Operations:

import {
    getGloballyLinkedPackages,
    getLinkedDependencies,
    getLinkCompatibilityProblems,
    isNpmLinked
} from '@eldrforge/git-tools';

const globalPackages = await getGloballyLinkedPackages();
const linkedDeps = await getLinkedDependencies('/path/to/package');
const problems = await getLinkCompatibilityProblems('/path/to/package');
const isLinked = await isNpmLinked('/path/to/package');

Validation (validation.ts)

Runtime type validation utilities:

import {
    safeJsonParse,
    validateString,
    validatePackageJson
} from '@eldrforge/git-tools';

const data = safeJsonParse(jsonString, 'context');
const validated = validateString(value, 'fieldName');
const packageJson = validatePackageJson(data, 'package.json');

API Documentation

Git Functions

| Function | Description | |----------|-------------| | isValidGitRef(ref) | Tests if a git reference exists and is valid | | findPreviousReleaseTag(version, pattern?) | Finds the highest tag less than current version | | getCurrentVersion() | Gets current version from package.json | | getDefaultFromRef(forceMain?, branch?) | Gets reliable default for release comparison | | getRemoteDefaultBranch() | Gets default branch name from remote | | localBranchExists(branch) | Checks if local branch exists | | remoteBranchExists(branch, remote?) | Checks if remote branch exists | | getBranchCommitSha(ref) | Gets commit SHA for a branch | | isBranchInSyncWithRemote(branch, remote?) | Checks if local/remote branches match | | safeSyncBranchWithRemote(branch, remote?) | Safely syncs branch with remote | | getCurrentBranch() | Gets current branch name | | getGitStatusSummary(workingDir?) | Gets comprehensive git status | | getGloballyLinkedPackages() | Gets globally linked npm packages | | getLinkedDependencies(packageDir) | Gets linked dependencies for package | | getLinkCompatibilityProblems(packageDir) | Finds version compatibility issues | | isNpmLinked(packageDir) | Checks if package is globally linked | | getBranchNameForVersion(version) | Gets branch name for a version |

Process Execution Functions

| Function | Description | |----------|-------------| | runSecure(cmd, args, opts?) | Securely executes command with argument array | | runSecureWithInheritedStdio(cmd, args, opts?) | Secure execution with inherited stdio | | run(command, opts?) | Executes command string (less secure) | | runWithDryRunSupport(cmd, dryRun, opts?) | Run with dry-run support | | runSecureWithDryRunSupport(cmd, args, dryRun, opts?) | Secure run with dry-run support | | validateGitRef(ref) | Validates git reference for injection | | validateFilePath(path) | Validates file path for injection | | escapeShellArg(arg) | Escapes shell arguments |

Validation Functions

| Function | Description | |----------|-------------| | safeJsonParse<T>(json, context?) | Safely parses JSON with error handling | | validateString(value, fieldName) | Validates non-empty string | | validateHasProperty(obj, property, context?) | Validates object has property | | validatePackageJson(data, context?, requireName?) | Validates package.json structure |

Security

This library prioritizes security in command execution:

• Shell Injection Prevention: All runSecure* functions use argument arrays without shell execution
• Input Validation: Git references and file paths are validated before use
• No Shell Metacharacters: Commands are executed directly without shell interpretation
• Escaped Arguments: Shell argument escaping utilities provided

Development

# Install dependencies
npm install

# Build
npm run build

# Run tests
npm run test

# Lint
npm run lint

# Watch mode
npm run watch

License

Apache-2.0 - see LICENSE file for details.

Author

Calen Varek [email protected]

Related Projects

This library was extracted from kodrdriv, an AI-powered Git workflow automation tool.