view-ignored


Retrieve list of files ignored/included
by Git, NPM, Yarn, JSR, VSCE or other tools.

Requirements

- Node.js 18 or later for production
- Node.js 20 or later for production type definitions
- Node.js 22 or later for development type definitions

Highlights

- Native. Get a list of included files using configuration file
readers, not command-line wrappers.
- Plugins. Built-in targets for popular tools. Use custom
targets by implementing the Target interface.
- TypeScript. Written in TypeScript with type definitions included.
- Lightweight. Minimal dependencies for fast performance and small bundle size.
- Easy-to-modify. Well-written and MIT-licensed.

> [!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.

Usage

$3

``ts
import * as vign from "view-ignored";
import { Git } from "view-ignored/targets";

const results = await vign.scan({ target: Git });
results.paths.has(".git/HEAD");
`

$3

`ts
import * as vign from "view-ignored";
import {
type SourceExtractor,
type SignedPattern,
extractGitignore
findAndExtract,
signedPatternIgnores,
} from "view-ignored/patterns";
import type { Target } from "view-ignored/targets";

const gitSources = ['.gitignore'];
const gitSourceMap = new Map([
['.gitignore', extractGitignore]
]);
const gitPattern: SignedPattern = {
exclude: [
'.git',
'.DS_Store',
],
include: []
};

export const Git: Target = {
async matcher(entry, isDir, ctx) {
if (isDir) {
await findAndExtract(entry, gitSources, gitSourceMap, ctx);
return true;
}
return await signedPatternIgnores(gitPattern, entry, gitSources, gitSourceMap, ctx);
}
};
`

`ts
vign.scan({ target: Git });
`

Targets

> [!NOTE]
> Each scanner expects minimal configurations, but the actual tool can have
> more/less complex rules. Refer to the documentation of each tool for details.

The following built-in scanners are available:

- Git
- Reads .gitignore files but does not consider global settings.
- Check this scanner by running git ls-tree -r HEAD --name-only.
- See the implementation of Git target for details.
- NPM (compatible with Bun, PNPM, and others)
- Reads .npmignore and package.json files field.
- No additional checks for name, version or publishConfig.
- Check this scanner by running npm pack --dry-run.
- See the implementation of NPM target for details.
- Yarn
- Same behavior as npm, but also reads .yarnignore.
- See the implementation of Yarn target for details.
- VSCE
- Reads .vscodeignore and package.json files field.
- Check this scanner by running vsce ls.
- See the implementation of VSCE target for details.
- JSR (compatible with Deno)
- Reads jsr.json(c) and deno.json(c) include and exclude` fields.
- See the implementation of JSR target for details.

License

MIT License. See LICENSE.txt for details.