flatten-gitignores

A simple Node.js tool for flattening nested .gitignore files into a single file.

Useful for supporting tools that expect a single ignore file and don't resolve nested ignore files (e.g. EAS expects .easignore and Prettier expects .prettierignore).

Usage

Run the script with Node, passing optional flags to customize input, output, additions, and excludes.

npx flatten-gitignores [--ignore-file] [--cwd <path>] [--output <file>] [--prepend <path>] [--append <path>] [--exclude <glob> ...] [--no-default-excludes] [--help]

Flags

• --ignore-file <file>: The ignore file name to search for. Defaults to .gitignore.
• --cwd <path>: The search root / working directory; defaults to current CWD (.).
• --output <file>: Output file path; defaults to <cwd>/.gitignore-collated.
• --prepend <path>: Path to an additional ignore file to prepend. Resolved relative to CWD.
• --append <path>: Path to an additional ignore file to append. Resolved relative to CWD.
• --exclude <glob>: Glob pattern(s) to exclude from the search for ignore files. Defaults to **/node_modules/**. Pass one or more --exclude flags to add more. To omit the defaults, pass --no-default-excludes.
• --no-default-excludes: Omit the default excludes (**/node_modules/**).
• --help: Show help and exit.

Examples

• Default behavior:

  npx flatten-gitignores

  • Collates all .gitignore files found into a .gitignore-collated file in the current directory.

• Specify output file (--output):

  npx flatten-gitignores --output ./.easignore

  • Collates all .gitignore files found into a .easignore file in the current directory.

• Exclude certain files from the search for ignore files (--exclude):

  npx flatten-gitignores --exclude **/dist/** --exclude **/build/**

  • Collates all .gitignore files found into a .easignore file in the current directory.
  • --exclude: Excludes **/dist/** and **/build/** from the search. Useful for reducing needless search time.

• Stop excluding node_modules from the search (--no-default-excludes):

  npx flatten-gitignores --no-default-excludes

  • Collates all .gitignore files found into a .easignore file in the current directory.
  • --no-default-excludes: Stops excluding **/node_modules/** (I can't think of a practical use-case for this, but just in case you need it!).

• Prepend (--prepend) or append (--append) extra rules:

  npx flatten-gitignores --output ./.easignore --prepend .easignore-prepend --append .easignore-append

  • Collates all .gitignore files found into a .easignore file in the current directory.
  • --prepend: Prepends the contents of .easignore-prepend into that .easignore file.
  • --append: Appends the contents of .easignore-append into that .easignore file.

• Collate a file other than .gitignore (--ignore-file):

  npx flatten-gitignores --ignore-file _gitignore

  • Collates all _gitignore files found into a .gitignore-collated file in the current directory (possibly useful for ecosystems like npm, which do not support bundling a .gitignore file into your npm package, so people have to work around it with a _gitignore file or similar that they rename to .gitignore after unpacking).

Example output

If you run the following command:

npx flatten-gitignores --output .easignore --prepend .easignore-prepend

Then, given:

1. …a typical monorepo that looks like this:

.
├── .gitignore
├── package.json
├── apps
│   ├── desktop
│   ├── docs
│   └── mobile
│       ├── .gitignore
│       ├── package.json
│       ├── ios
│       └── android
└── packages
    └── react-native-confetti
        ├── .gitignore
        ├── android
        ├── ios
        ├── example
        └── package.json

2. …the following .gitignore file at the root of your monorepo:

.DS_Store

3. …the following .easignore-prepend file:

# Ignore all non-Expo apps:
apps/desktop
apps/docs

# Ignore all example React Native apps:
packages/*/example

4. …and the following apps/mobile/.gitignore file:

node_modules
ios
android

… it will produce the following .easignore file:

################################################################################
### This is a flattened ignore pattern list generated by flatten-gitignores. ###
### See https://shirakaba/flatten-gitignores for documentation.              ###
################################################################################

### START /.easignore-prepend ###
# Ignore all non-Expo apps:
/**/apps/desktop
/**/apps/docs

# Ignore all example React Native apps:
/**/packages/*/example
### END /.easignore-prepend ###

### START /.gitignore ###
/**/.DS_Store
### END /.gitignore ###

### START /apps/mobile/.gitignore ###
/apps/mobile/**/node_modules
/apps/mobile/**/ios
/apps/mobile/**/android
### END /apps/mobile/.gitignore ###

Note how all rules have been normalised with /, /**, and subpaths, as necessary. This prevents nested .gitignore files accidentally applying rules across the whole tree. The collated .easignore should behave equivalently to the multiple .gitignore files, though, to the best of my understanding!

Does it, like, work?

I implemented this in a hurry one day with reference to the .gitignore pattern format docs. I think I've probably covered all cases, i.e. comments, backslashes, **, etc. – but as you can see, there are no tests, so this is all just talk.

All I can say is that this works well enough that it helped me cut 4.55 GB off my EAS archive!