parse-gitignore-ts

A TypeScript library for parsing .gitignore or .npmignore files into an array of patterns.

English | 中文文档

Introduction

parse-gitignore-ts is a TypeScript version of parse-gitignore, providing complete type definitions and support for modern module formats. This library helps you parse .gitignore or .npmignore files and offers various useful features.

Features

• Complete TypeScript type support
• Support for both ESM and CommonJS module formats
• Parse .gitignore files into pattern arrays
• Support for deduplication and formatting
• Convert gitignore patterns to glob patterns
• Zero dependencies

Installation

Install with npm:

npm install --save parse-gitignore-ts

Or with yarn:

$ yarn add parse-gitignore-ts

Or with pnpm:

pnpm add parse-gitignore-ts

Usage

Basic Usage

import { readFileSync } from 'fs';
import parseGitignore from 'parse-gitignore-ts';

// Pass the contents of a .gitignore file as a string or buffer
console.log(parseGitignore(readFileSync('foo/bar/.gitignore')));
//=> ['*.DS_Store', 'node_modules', ...];

ESM and CommonJS Support

ESM:

import parseGitignore from 'parse-gitignore-ts';

CommonJS:

const parseGitignore = require('parse-gitignore-ts');

Example

Parse the contents of a .gitignore file, like the following:

# Logs
logs
*.log
npm-debug.log*
yarn-debug.log*
yarn-error.log*

# Runtime data
pids
*.pid
*.seed
*.pid.lock

Into an array:

[
  'logs',
  '*.log',
  'npm-debug.log*',
  'yarn-debug.log*',
  'yarn-error.log*',
  'pids',
  '*.pid',
  '*.seed',
  '*.pid.lock',
];

API

parseGitignore(input, options?)

Parse a .gitignore file content into an array of patterns.

Parameters

• input: String, Buffer, or already parsed object
• options: Optional configuration object
  • path: File path
  • dedupe: Whether to deduplicate
  • unique: Whether to deduplicate (same as dedupe)
  • ignore: Additional patterns to ignore
  • unignore: Patterns to unignore
  • formatSection: Custom section formatting function

Return Value

Returns an object with the following properties:

• sections: Array of sections, each with name, comment, and patterns properties
• patterns: Array of all patterns
• path: File path
• input: Input Buffer
• format: Formatting function
• dedupe: Deduplication function
• globs: Function to convert to glob patterns

parseGitignore.file(filepath, options?)

Parse a .gitignore file at the specified path.

import parseGitignore from 'parse-gitignore-ts';

const parsed = parseGitignore.file('.gitignore');
console.log(parsed.patterns);

parseGitignore.dedupe(input, options?)

Remove duplicate sections and patterns.

import parseGitignore from 'parse-gitignore-ts';

const deduped = parseGitignore.dedupe(gitignoreContent);
console.log(deduped.patterns);

parseGitignore.format(input, options?)

Format .gitignore file content.

import parseGitignore from 'parse-gitignore-ts';

const formatted = parseGitignore.format(gitignoreContent);
console.log(formatted);

parseGitignore.globs(input, options?)

Convert .gitignore patterns to glob patterns.

import parseGitignore from 'parse-gitignore-ts';

const globs = parseGitignore.globs(gitignoreContent);
console.log(globs);

parseGitignore.patterns(input)

Extract patterns array from input.

import parseGitignore from 'parse-gitignore-ts';

const patterns = parseGitignore.patterns(gitignoreContent);
console.log(patterns);

Advanced Usage

Custom Formatting

import parseGitignore from 'parse-gitignore-ts';

const customFormat = parseGitignore.format(gitignoreContent, {
  formatSection: (section) => {
    if (!section.name) return '';

    const header = `## ${section.name.toUpperCase()} ##`;
    const border = '#'.repeat(header.length);

    return [border, header, border, '', ...(section.patterns || []), ''].join('\n');
  },
});

Merging Multiple .gitignore Files

import parseGitignore from 'parse-gitignore-ts';

const gitignore1 = '*.log\nnode_modules/';
const gitignore2 = 'dist/\n.DS_Store';

const merged = parseGitignore.dedupe(
  [...parseGitignore(gitignore1).patterns, ...parseGitignore(gitignore2).patterns].join('\n')
);

License

MIT