{"id":13239,"library":"gitlog","title":"Git Log Parser","description":"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.","status":"active","version":"5.1.0","language":"javascript","source_language":"en","source_url":"git://github.com/domharrington/node-gitlog","tags":["javascript","git","log","parser","typescript"],"install":[{"cmd":"npm install gitlog","lang":"bash","label":"npm"},{"cmd":"yarn add gitlog","lang":"bash","label":"yarn"},{"cmd":"pnpm add gitlog","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"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.","wrong":"const gitlog = require('gitlog');","symbol":"gitlog","correct":"import gitlog from 'gitlog';"},{"note":"This TypeScript type is crucial for strongly typing the options object passed to the `gitlog` function, enabling type-safety and auto-completion.","symbol":"GitlogOptions","correct":"import { GitlogOptions } from 'gitlog';"}],"quickstart":{"code":"import gitlog, { GitlogOptions } from \"gitlog\";\nimport * as path from \"path\";\nimport { fileURLToPath } from 'url';\n\n// Resolve __dirname equivalent for ES Modules\nconst __filename = fileURLToPath(import.meta.url);\nconst __dirname = path.dirname(__filename);\n\n// Define an interface for the expected commit structure\ninterface MyCommitFields {\n  hash: string;\n  abbrevHash: string;\n  subject: string;\n  authorName: string;\n  authorDateRel: string;\n}\n\nasync function getCommits() {\n  // Adjust 'repo' to point to a valid .git directory in your project\n  const repoPath = path.resolve(__dirname, '..', '.git'); \n  console.log(`Attempting to read git log from: ${repoPath}`);\n\n  const options: GitlogOptions<keyof MyCommitFields> = {\n    repo: repoPath,\n    number: 5, // Get the last 5 commits\n    // Fields must be 'as const' for proper TypeScript return type inference\n    fields: [\"hash\", \"abbrevHash\", \"subject\", \"authorName\", \"authorDateRel\"] as const,\n    execOptions: { maxBuffer: 1024 * 1024 * 5 }, // Increase buffer for large repos/logs (5MB)\n  };\n\n  try {\n    const commits = await gitlog<MyCommitFields>(options); // Explicitly type the returned commits\n    console.log(`Found ${commits.length} commits:`)\n    commits.forEach((commit) => {\n      console.log(`- ${commit.abbrevHash} by ${commit.authorName} (${commit.authorDateRel}): ${commit.subject}`);\n    });\n  } catch (error) {\n    console.error(\"Failed to get git log:\", error instanceof Error ? error.message : String(error));\n    console.error(\"Please ensure 'git' is installed and in your PATH, and the 'repo' path is correct.\");\n  }\n}\n\ngetCommits();","lang":"typescript","description":"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."},"warnings":[{"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)); } }`.","message":"Errors thrown by the library are now instances of `Error` instead of raw strings. This requires updating error handling logic in existing applications.","severity":"breaking","affected_versions":">=4.0.8"},{"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.","message":"The 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.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"Upgrade `gitlog` to version 4.0.4 or higher immediately: `npm install gitlog@latest`.","message":"A 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.","severity":"gotcha","affected_versions":"<4.0.4"},{"fix":"Add `as const` to your `fields` array definition: `fields: ['hash', 'subject', 'authorName'] as const`.","message":"When 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.","severity":"gotcha","affected_versions":">=3.x"},{"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).","message":"For 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.","severity":"gotcha","affected_versions":">=3.x"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Increase the `maxBuffer` option in `execOptions`: `execOptions: { maxBuffer: 1024 * 1024 * 5 }` (for 5MB, adjust as necessary).","cause":"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.","error":"Error: stdout maxBuffer exceeded"},{"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.","cause":"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.","error":"Error: spawn git ENOENT"},{"fix":"Append `as const` to your `fields` array definition to provide literal type inference: `fields: ['hash', 'subject', 'authorName'] as const`.","cause":"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.","error":"Argument of type '{ fields: string[]; repo: string; }' is not assignable to parameter of type 'GitlogOptions<\"hash\" | \"abbrevHash\" | \"subject\" | \"authorName\">'."}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":""}