view-ignored

Retrieve list of files ignored/included by Git, NPM, Yarn, JSR, Deno, Bun, VSCode extension CLI and other tools.

Highlights

• Reader. Get a list of included files using configuration file readers, not command-line wrappers.
• Reasoning. Understand why certain files are included or excluded.
• Fast. Optimized for performance with minimal memory overhead.
• Plugins. Built-in targets for popular tools. Use custom targets by implementing/extending the Target interface.
• Streaming. Native scanStream support for processing massive file trees with minimal memory overhead.
• Execution Control. Use fastDepth and fastInternal options to fine-tune traversal depth and skip unnecessary directory checks. You can also enable them if you don't care about stats.
• Abortable. Full support for AbortSignal to cancel long-running scans instantly.
• Lightweight. Minimal dependencies for fast performance and small bundle size.
• Browser. Can be bundled for browser use.
• Windows. Windows paths are converted to Unix paths for compatibility with memfs based tests and browsers.

Note

Despite the name of the package being "view-ignored", the primary purpose is to get the list of included files, i.e., files that are not ignored. You can invert the results if you need the ignored files by setting the invert option to true.

v1 Roadmap

• Works for common use cases.
• Follow .gitignore spec. (ignore does.)
• Handle Git config.
• Include node_modules bundled dependencies correctly. Missing: NPM, Yarn + Classic, Bun, Deno, JSR.
• *Move targets into separate packages (or not).
• Import and pass upstream source tests.
• *Make it standard: NPM cli, VS Code file tree, VSCE, GitHub.
• *Upstream to Bun, PNPM and other package managers.

_{* - Optional.}

Why this library exists?

Incorrect VS Code file tree git status, huge npm-packlist package, missing Git's wildmatch algorithm in JS ecosistem, and the fact that there's no lightweight way to get a list of ignored files, which would explain why specific files are being included or excluded.

Usage

Basic example

import * as vign from "view-ignored"
// also available:
// "/scan", "/stream"
// "/browser", "/browser/scan", "/browser/stream"
import { Git as target } from "view-ignored/targets"
import { RuleMatchKind } from "view-ignored/patterns"

const ctx = await vign.scan({ target })
ctx.paths.has(".git/HEAD") // false
ctx.paths.has("src") // true

const match = ctx.paths.get("src")!
if (match.kind === RuleMatchKind.external) {
	console.log(match.source.path) // ".gitignore"
	console.log(match.pattern) // "src/**"
}

Using custom target

This is the internal implementation for the Git target:

import type { Target } from "view-ignored/targets"

import {
	type Extractor,
	extractGitignore,
	ruleTest,
	ruleCompile,
	type Rule,
} from "view-ignored/patterns"

const extractors: Extractor[] = [
	{
		extract: extractGitignore,
		path: ".gitignore",
	},
	{
		extract: extractGitignore,
		path: ".git/info/exclude",
	},
]

const internal: Rule[] = [
	ruleCompile({
		compiled: null,
		excludes: true,
		pattern: [".git", ".DS_Store"],
	}),
]

export const Git: Target = <Target>{
	extractors,
	// TODO: Git should read configs
	ignores: ruleTest,
	internalRules: internal,
	root: "/",
}

Streaming results

import * as vign from "view-ignored"
// or import * as vign from "view-ignored/stream"
import { NPM as target } from "view-ignored/targets"

const stream = vign.scanStream({ target })

stream.addEventListener("dirent", console.log)
stream.addEventListener(
	"end",
	({ detail: ctx }) => {
		ctx.paths.has(".git/HEAD")
		// false
		ctx.paths.has("node_modules/")
		// false
		ctx.paths.has("package.json")
		// true
	},
	{ once: true },
)
stream.start() // important

Browser and custom FS

To avoid imports from node:fs and node:process modules, use the browser submodule, which requires some additional options.

import * as vign from "view-ignored/browser"
// or "/browser/scan"
import { Git as target } from "view-ignored/targets"
import { readFile, readdir } from "original-fs"

export const cwd = process.cwd()
const customFs = { readFile, readdir }
await vign.scan({ cwd, fs: customFs, target })

Watching for changes

You can use patchers to update the MatcherContext without rescanning the entire tree. This is useful for implementing file watchers.

Important

Directory paths must have a trailing slash.

import {
	matcherContextAddPath,
	matcherContextRemovePath,
} from "view-ignored/patterns"

// Handle "created"
await matcherContextAddPath(ctx, options, "src/new-file.ts")

// Handle "removed"
await matcherContextRemovePath(ctx, options, "src/old-file.ts")

// Handle "changed"
// Best approach: remove and re-add
await matcherContextRemovePath(ctx, options, "src/file.ts")
await matcherContextAddPath(ctx, options, "src/file.ts")

Edge Cases and Limitations

• Idempotency: Patcher functions for files are not idempotent. Calling matcherContextAddPath multiple times for the same path without removing it first will corrupt the totalFiles and totalMatchedFiles counts in ctx.total. Always call matcherContextRemovePath before matcherContextAddPath if the path might already exist in the context.
• Directories: Directory paths must end with a slash (e.g., src/). If you omit the slash, it will be treated as a file, and its contents will not be tracked or updated correctly.
• Renames: To handle a file or directory rename, first call matcherContextRemovePath on the old path, then matcherContextAddPath on the new path.
• Source Files: If a file that acts as an ignore source (like .gitignore or package.json) is added or changed, the patcher will automatically rescan the directory containing that source file to update the matching rules and state for all affected files.
• Depth: Patchers respect the depth option provided in the ScanOptions. If you add a path deeper than the specified depth, it might not be fully processed or added to ctx.paths.

Targets

The following built-in scanners are available:

• Git (our implementation)
  • view-ignored handles Git-specific ignoring almost identically to Git: does not consider config.
  • Reads .gitignore and .git/info/exclude.
  • Searches from /. (system's root)
  • Check this scanner by running git ls-files --others --exclude-standard --cached.
• NPM (our implementation)
  • view-ignored should be compatible with NPM, PNPM, and others.
  • Reads package.json files field or .npmignore or .gitignore.
  • Searches from . (current working directory).
  • Requires package.json: name, version.
  • Check this scanner by running npm pack --dry-run.
• Bun (our implementation)
  • Bun tries to mimic NPM, but that does not mean it behaves the same way.
  • Searches from . (current working directory).
  • Requires package.json: name, version. Forces paths from bin to be included.
  • Check this scanner by running bun pm pack --dry-run.
• Yarn (our implementation)
  • Modern Berry and ZPM behavior. YarnClassic is available. (our implementation)
  • Reads package.json files field or .npmignore or .gitignore.
  • Searches from . (current working directory).
  • Requires package.json: name, version. Forces paths from main, module, browser and bin to be included.
• VSCE (our implementation)
  • Reads package.json files field or .vscodeignore or .gitignore.
  • Searches from . (current working directory).
  • Requires package.json: name, version, engines.vscode.
  • Check this scanner by running vsce ls.
• JSR (our implementation)
  • Searches from . (current working directory).
  • Requires jsr.json or jsr.jsonc.
  • Validates publish.include and publish.exclude or include and exclude fields.
• Deno (our implementation)
  • Searches from . (current working directory).
  • Requires jsr.json or jsr.jsonc or deno.json or deno.jsonc.
  • Validates publish.include and publish.exclude or include and exclude fields.

See also

• There are references in our implementations.
• https://jsr.io/@m234/path - Utility to sort, convert and format paths.
• https://github.com/git/git/blob/master/wildmatch.c - The original wildmatch implementation.
• https://npmx.dev/package/ignore-walk - A Node.js module for walking directories while respecting ignore files. (It does it incorrectly for Git).
• https://npmx.dev/package/npm-packlist - A Node.js module for listing files to be included in an npm package. (Heavy)

Benchmarks

See benchmarks directory.

License

MIT License. See LICENSE.txt for details.