How do I include a .gitignore file as part of my npm module?

Question

I am building an npm module that will generate a specific project template for certain software projects. As such, when a developer installs my npm module and runs it, I would like the program to create files and folders in a certain way.

One such file I would like to include in the project template is a .gitignore file because the software project is going to assume it will be tracked via git. However, when I call "npm install" on my module, npm renames all my .gitignore files to .npmignore files. How can I ensure that my .gitignore files are not tampered with by npm when I distribute my module?

Answer 1

https://github.com/npm/npm/issues/1862

Looks like this is a known issue. The answer at the bottom seems like the recommended approach. In case the issue or link ever gets destroyed:

For us, I think a better solution is going to be clear documentation that if authors wish to use .gitignore in their generators, they will need to name their files .##gitignore##, which will be a value gitignore set to the same string gitignore.

In this way, the file that gets published as a template file to npm is called .##gitignore## and won't get caught by npm, but then later it gets replaced with the string to be .gitignore.

Answer 2

You can see multiple commits dealing with npm issue 1862 :

• this project adds a rename.json :

   lib/init-template/rename.json { ".npmignore": ".gitignore", }

• this one renames the .gitignore :

   templates/default/.gitignore → templates/default/{%=gitignore%} index.js @@ -114,6 +114,10 @@ generator._pkgData = function (pkg) { + // npm will rename .gitignore to .npmignore: + // [ref](https://github.com/npm/npm/issues/1862) + pkg.gitignore = '.gitignore';

Answer 3

Currently npm doesn't allow .gitignore files to be included as part of an npm package and will instead rename it to .npmignore .

A common workaround is to rename it the .gitignore to gitignore before publishing. Then as part of an init script, rename the gitignore to .gitignore . This approach is used in Create React App

Here's how to do it in Node, code from Create React App init script

  const gitignoreExists = fs.existsSync(path.join(appPath, '.gitignore'));
  if (gitignoreExists) {
    // Append if there's already a `.gitignore` file there
    const data = fs.readFileSync(path.join(appPath, 'gitignore'));
    fs.appendFileSync(path.join(appPath, '.gitignore'), data);
    fs.unlinkSync(path.join(appPath, 'gitignore'));
  } else {
    // Rename gitignore after the fact to prevent npm from renaming it to .npmignore
    // See: https://github.com/npm/npm/issues/1862
    fs.moveSync(
      path.join(appPath, 'gitignore'),
      path.join(appPath, '.gitignore'),
      []
    );
  }

Answer 4

Edit: even though this answer causes .gitignore to be included in the published package (proven by unpkg ), upon running npm install the .gitignore file is simply removed ! So even getting NPM to include the file is not enough.

Another solution (simpler imo):

Include both .gitignore and .npmignore in the repo. Add the following to your .npmignore file:

!.gitignore
!.npmignore

Now that .npmignore will already exist in the published package, NPM won't rename .gitignore .