Registry / devops / gitlog

gitlog

JSON →
library0.1.0jsnpmunverified

gitlog is a Node.js library designed to parse output from the `git log` command into structured JavaScript objects. Currently at version 5.1.0, it provides a comprehensive programmatic interface to execute `git log` with various options and efficiently process the results. The library supports a wide array of filtering and formatting options, mirroring the capabilities of the native Git CLI. It ships with full TypeScript support, offering type-safe interaction and an enhanced developer experience, particularly with its `GitlogOptions` type for configuration and type inference for the returned commit objects based on selected fields. Releases occur periodically with a mix of patch and minor versions, indicating active maintenance. Its primary differentiator is the direct execution of the `git` CLI, ensuring high fidelity with Git's robust features and providing detailed commit information including changed files, authors, dates, and custom log fields.

npm install gitlog
INSTALL
IMPORT
SIG · GITLOG
G
gitlog
devopsjavascriptv0.1.0
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

gitlog
import gitlog from 'gitlog';
const gitlog = require('gitlog');
Since v4.0.0, `gitlog` primarily targets ES Modules (ESM). While CommonJS `require()` might still work in some environments, ESM is the recommended and best-supported import pattern for new development.
GitlogOptions
import { GitlogOptions } from 'gitlog';
This TypeScript type is crucial for strongly typing the options object passed to the `gitlog` function, enabling type-safety and auto-completion.

This quickstart demonstrates fetching the last 5 commits from a local Git repository, specifying custom fields and leveraging TypeScript for type safety, including handling potential errors.

import gitlog, { GitlogOptions } from "gitlog"; import * as path from "path"; import { fileURLToPath } from 'url'; // Resolve __dirname equivalent for ES Modules const __filename = fileURLToPath(import.meta.url); const __dirname = path.dirname(__filename); // Define an interface for the expected commit structure interface MyCommitFields { hash: string; abbrevHash: string; subject: string; authorName: string; authorDateRel: string; } async function getCommits() { // Adjust 'repo' to point to a valid .git directory in your project const repoPath = path.resolve(__dirname, '..', '.git'); console.log(`Attempting to read git log from: ${repoPath}`); const options: GitlogOptions<keyof MyCommitFields> = { repo: repoPath, number: 5, // Get the last 5 commits // Fields must be 'as const' for proper TypeScript return type inference fields: ["hash", "abbrevHash", "subject", "authorName", "authorDateRel"] as const, execOptions: { maxBuffer: 1024 * 1024 * 5 }, // Increase buffer for large repos/logs (5MB) }; try { const commits = await gitlog<MyCommitFields>(options); // Explicitly type the returned commits console.log(`Found ${commits.length} commits:`) commits.forEach((commit) => { console.log(`- ${commit.abbrevHash} by ${commit.authorName} (${commit.authorDateRel}): ${commit.subject}`); }); } catch (error) { console.error("Failed to get git log:", error instanceof Error ? error.message : String(error)); console.error("Please ensure 'git' is installed and in your PATH, and the 'repo' path is correct."); } } getCommits();
Debug
Known issues
breakingErrors thrown by the library are now instances of `Error` instead of raw strings. This requires updating error handling logic in existing applications.
fix
Update `catch` blocks to check for `Error` instances, e.g., `try { /* ... */ } catch (error) { if (error instanceof Error) { console.error(error.message); } else { console.error(String(error)); } }`.
affects: >=4.0.8
breakingThe package now primarily targets ES Modules (ESM). While CommonJS (CJS) might still function in some environments, official examples and best practices strongly recommend ESM usage. Older CJS `require` statements may need adjustment or specific Node.js configuration.
fix
Refactor CommonJS `require()` statements to ES Module `import` statements. Ensure your project is configured for ESM, typically by setting `"type": "module"` in `package.json` or using `.mjs` file extensions.
affects: >=4.0.0
gotchaA critical command injection vulnerability (CVE-2022-24810) was patched in version 4.0.4. It is essential to upgrade to at least this version or newer to prevent potential remote code execution by specially crafted git commit inputs.
fix
Upgrade `gitlog` to version 4.0.4 or higher immediately: `npm install gitlog@latest`.
affects: <4.0.4
gotchaWhen using TypeScript, the `fields` array passed in the options object should be cast `as const` to enable proper literal type inference for the returned commit objects. Without `as const`, the return type for fields will be `string` or `string[]` instead of a precise tuple type matching your specified fields, reducing type-safety.
fix
Add `as const` to your `fields` array definition: `fields: ['hash', 'subject', 'authorName'] as const`.
affects: >=3.x
gotchaFor repositories with a very large number of commits or extensive log output (e.g., with `nameStatus` enabled), the default `execOptions.maxBuffer` (200KB) might be insufficient, leading to 'stdout maxBuffer exceeded' errors and premature termination of the git command.
fix
Increase `maxBuffer` in `execOptions` to accommodate larger outputs: `execOptions: { maxBuffer: 1024 * 1024 * 5 }` (for 5MB, adjust value as needed based on your repository size).
affects: >=3.x
Errors
Common errors & fixes
Error: stdout maxBuffer exceeded
The `git log` command produced more output than the default `maxBuffer` allocated for the child process by Node.js, often occurring in large repositories or when requesting many commits/detailed file status.
fix
Increase the `maxBuffer` option in `execOptions`: `execOptions: { maxBuffer: 1024 * 1024 * 5 }` (for 5MB, adjust as necessary).
Error: spawn git ENOENT
The `git` command-line tool is not installed on the system or is not found in the system's PATH environment variable, preventing `gitlog` from executing the underlying `git` commands.
fix
Install Git on your operating system and ensure its executable is accessible from your shell's PATH. Restart your application or development environment after installation.
Argument of type '{ fields: string[]; repo: string; }' is not assignable to parameter of type 'GitlogOptions<"hash" | "abbrevHash" | "subject" | "authorName">'.
TypeScript cannot infer the literal string types for the `fields` array without an explicit `as const` assertion, leading to a generic `string[]` type instead of a precise tuple of literal field names.
fix
Append `as const` to your `fields` array definition to provide literal type inference: `fields: ['hash', 'subject', 'authorName'] as const`.
Upgrade
Version history
0.1.0latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
2 hits · last 30 days
node
2
Resources