source: trip-planner-front/node_modules/npm-packlist/README.md@ 76712b2

Last change on this file since 76712b2 was 6a3a178, checked in by Ema <ema_spirova@…>, 3 years ago

initial commit

  • Property mode set to 100644
File size: 5.9 KB
Line 
1# npm-packlist
2
3[![Build Status](https://travis-ci.com/npm/npm-packlist.svg?token=hHeDp9pQmz9kvsgRNVHy&branch=master)](https://travis-ci.com/npm/npm-packlist)
4
5Get a list of the files to add from a folder into an npm package.
6
7These can be handed to [tar](http://npm.im/tar) like so to make an npm
8package tarball:
9
10```js
11const packlist = require('npm-packlist')
12const tar = require('tar')
13const packageDir = '/path/to/package'
14const packageTarball = '/path/to/package.tgz'
15
16packlist({ path: packageDir })
17 .then(files => tar.create({
18 prefix: 'package/',
19 cwd: packageDir,
20 file: packageTarball,
21 gzip: true
22 }, files))
23 .then(_ => {
24 // tarball has been created, continue with your day
25 })
26```
27
28This uses the following rules:
29
301. If a `package.json` file is found, and it has a `files` list,
31 then ignore everything that isn't in `files`. Always include the
32 readme, license, notice, changes, changelog, and history files, if
33 they exist, and the package.json file itself.
342. If there's no `package.json` file (or it has no `files` list), and
35 there is a `.npmignore` file, then ignore all the files in the
36 `.npmignore` file.
373. If there's no `package.json` with a `files` list, and there's no
38 `.npmignore` file, but there is a `.gitignore` file, then ignore
39 all the files in the `.gitignore` file.
404. Everything in the root `node_modules` is ignored, unless it's a
41 bundled dependency. If it IS a bundled dependency, and it's a
42 symbolic link, then the target of the link is included, not the
43 symlink itself.
444. Unless they're explicitly included (by being in a `files` list, or
45 a `!negated` rule in a relevant `.npmignore` or `.gitignore`),
46 always ignore certain common cruft files:
47
48 1. .npmignore and .gitignore files (their effect is in the package
49 already, there's no need to include them in the package)
50 2. editor junk like `.*.swp`, `._*` and `.*.orig` files
51 3. `.npmrc` files (these may contain private configs)
52 4. The `node_modules/.bin` folder
53 5. Waf and gyp cruft like `/build/config.gypi` and `.lock-wscript`
54 6. Darwin's `.DS_Store` files because wtf are those even
55 7. `npm-debug.log` files at the root of a project
56
57 You can explicitly re-include any of these with a `files` list in
58 `package.json` or a negated ignore file rule.
59
60Only the `package.json` file in the very root of the project is ever
61inspected for a `files` list. Below the top level of the root package,
62`package.json` is treated as just another file, and no package-specific
63semantics are applied.
64
65### Interaction between `package.json` and `.npmignore` rules
66
67For simplicity, it is best to use _either_ a `files` list in `package.json`
68_or_ a `.npmignore` file, and not both. If you only use one of these
69methods, you can skip this documentation section.
70
71The `files` list in `package.json` is used to direct the exploration of the
72tree. In other words, that's all the walker will ever look at when
73exploring that level.
74
75In some cases this can lead to a `.npmignore` file being ignored. If a
76_directory_ is listed in `files`, then any rules in a root or nested
77`.npmignore` files will be honored.
78
79For example, with this package.json:
80
81```json
82{
83 "files": [ "dir" ]
84}
85```
86
87a `.npmignore` file at `dir/.npmignore` (and any subsequent
88sub-directories) will be honored. However, a `.npmignore` at the root
89level will be skipped.
90
91Conversely, with this package.json:
92
93```
94{
95 "files": ["dir/subdir"]
96}
97```
98
99a `.npmignore` file at `dir/.npmignore` will not be honored.
100
101Any specific file matched by a glob or filename in the package.json `files`
102list will be included, and cannot be excluded by any `.npmignore` files in
103nested directories, or by a `.npmignore` file in the root package
104directory, unless that root `.npmignore` file is also in the `files` list.
105
106The previous (v1) implementation used in npm 6 and below treated
107`package.json` as a special sort of "reverse ignore" file. That is, it was
108parsed and handled as if it was a `.npmignore` file with `!` prepended to
109all of the globs in the `files` list. In order to include children of a
110directory listed in `files`, they would _also_ have `/**` appended to them.
111
112This is tricky to explain, but is a significant improvement over the
113previous (v1) implementation used in npm 6 and below, with the following
114beneficial properties:
115
116- If you have `{"files":["lib"]}` in `package.json`, then the walker will
117 still ignore files such as `lib/.DS_Store` and `lib/.foo.swp`. The
118 previous implementation would include these files, as they'd be matched
119 by the computed `!lib/**` ignore rule.
120- If you have `{"files":["lib/a.js","lib/b.js"]}` in `package.json`, and a
121 `lib/.npmignore` containing `a.js`, then the walker will still include
122 the two files indicated in `package.json`, and ignore the
123 `lib/.npmignore` file. The previous implementation would mark these
124 files for inclusion, but then _exclude_ them when it came to the nested
125 `.npmignore` file. (Ignore file semantics dictate that a "closer" ignore
126 file always takes precedence.)
127- A file in `lib/pkg-template/package.json` will be included, and its
128 `files` list will not have any bearing on other files being included or
129 skipped. When treating `package.json` as just Yet Another ignore file,
130 this was not the case, leading to difficulty for modules that aim to
131 initialize a project.
132
133In general, this walk should work as a reasonable developer would expect.
134Matching human expectation is tricky business, and if you find cases where
135it violates those expectations, [please let us
136know](https://github.com/npm/npm-packlist/issues).
137
138## API
139
140Same API as [ignore-walk](http://npm.im/ignore-walk), just hard-coded
141file list and rule sets.
142
143The `Walker` and `WalkerSync` classes take a `bundled` argument, which
144is a list of package names to include from node_modules. When calling
145the top-level `packlist()` and `packlist.sync()` functions, this
146module calls into `npm-bundled` directly.
Note: See TracBrowser for help on using the repository browser.