simple-ignore

One .gitignore file to rule them all.

Background

• Some tools do not consistently follow the rules outlined in the .gitignore file. While a few of these tools may offer the option to enforce .gitignore rules, this feature is not universally compatible. For example, there might be a necessity to exclude specific files from version control without modifying their formatting, such as autogenerated files like CHANGELOG.md.
• Certain tools exhibit suboptimal performance within the VSCode workspace environment. For instance, eslint may encounter issues when used within a subfolder of a monorepo.
• Different ignore files, such as .dockerignore, employ distinct syntax conventions. For instance, while specifying package.json in .gitignore is equivalent to **/package.json in .dockerignore, specifying /package.json in .gitignore equates to specifying package.json in .dockerignore.

Features

• Generate ignore files for multiple tools.
• Add extra rules for files that should not undergo formatting.
• Structure ignore files for packages within monorepositories.
• Translate rules into .dockerignore syntax.

Usage

When embarking on a new project, it's advisable to procure the .gitignore file from github/gitignore.

Alternatively, you can obtain one from Toptal by using the following command:

curl -o .gitignore https://www.toptal.com/developers/gitignore/api/node

If your repository is not a node project, you can generate a tailored .gitignore file for your needs on Toptal's gitignore generator.

It's strongly encouraged to employ project-specific .gitignore files exclusively within the repository. Any environment-specific ignore files, such as those for operating systems or editors, should be stored directly within your user directory.

To obtain such files for macOS and Visual Studio Code, you can use the following command:

curl -o ~/.gitignore https://www.toptal.com/developers/gitignore/api/macos,visualstudiocode

If you're already working within a project, you can employ the following command to delete the ignore files:

rm .*ignore packages/*/.*ignore
git checkout .gitignore

If you wish to lint the dotfiles using tools such as eslint, you can prepend it to the .gitignore file:

!.*

You only need to maintain .gitignore, so you can remove all other files and append the following rules to it:

.*ignore
!/.gitignore

Add the following to your package.json:

{
  "scripts": {
    "postinstall": "npx simple-ignore"
  }
}

Each time you run npm install, the required ignore files will be generated automatically, following the specifications outlined in the .gitignore file. Additionally, simple-ignore will detect monorepos and generate ignore files for each package by locating the package.json files.

If you prefer to run it locally or are concerned about potential breaking changes, we highly recommend installing and running it locally:

npm install simple-ignore
npm exec simple-ignore

Configuration

To customize the ignore files, simply add a simple-ignore.config.ts file to the root directory of your project.

// simple-ignore.config.ts
import { defineConfig } from "simple-ignore";

export default defineConfig({
  // ...
});

You can also utilize other methods supported by cosmiconfig, like adding a simple-ignore field to your package.json file.

To view all available options, you can refer to the default configuration.

CLI

# Default Usage
npx simple-ignore

# Help Command
npx simple-ignore -h

# Using Specific Configuration File
npx simple-ignore -c simple-ignore.config.ts

# Dry Run Mode
npx simple-ignore -d

# Overriding Rules
npx simple-ignore -lr __snapshots__,/package-lock.json,/pnpm-lock.yaml,/yarn.lock,CHANGELOG.md

# Override Root Directory
# By default, the rootDir is the directory where the configuration file resides.
# If the configuration file is absent, the rootDir defaults to the directory where the command is executed.
# You can specify a different rootDir using the -r flag.
npx simple-ignore -r ..

API

import { generateIgnoreFiles } from "simple-ignore";

await generateIgnoreFiles({
  // configuration
});

License

MIT

Copyright (c) 2024 ViPro vdustr@gmail.com (http://vdustr.dev)