Skip to content

Commit 20c9ae5

Browse files
cap-Bernarditocap-Bernardito
authored
docs: import documentation for the from option (#468)
1 parent bfb4f0e commit 20c9ae5

File tree

1 file changed

+202
-34
lines changed

1 file changed

+202
-34
lines changed

‎README.md‎

Lines changed: 202 additions & 34 deletions
Original file line numberDiff line numberDiff line change
@@ -79,7 +79,7 @@ module.exports = {
7979
| [`from`](#from) | `{String}` | `undefined` | Glob or path from where we сopy files. |
8080
| [`to`](#to) | `{String}` | `compiler.options.output` | Output path. |
8181
| [`context`](#context) | `{String}` | `options.context \|\| compiler.options.context` | A path that determines how to interpret the `from` path. |
82-
| [`globOptions`](#globoptions) | `{Object}` | `undefined` | [Options][glob-options] passed to the glob pattern matching library, including `ignore` option |
82+
| [`globOptions`](#globoptions) | `{Object}` | `undefined` | [Options][glob-options] passed to the glob pattern matching library including `ignore` option. |
8383
| [`toType`](#totype) | `{String}` | `undefined` | Determinate what is `to` option - directory, file or template. |
8484
| [`test`](#test) | `{String\|RegExp}` | `undefined` | Pattern for extracting elements to be used in `to` templates. |
8585
| [`force`](#force) | `{Boolean}` | `false` | Overwrites files already in `compilation.assets` (usually added by other plugins/loaders). |
@@ -97,9 +97,9 @@ Glob or path from where we сopy files.
9797
Globs accept [fast-glob pattern-syntax](https://github.com/mrmlnc/fast-glob#pattern-syntax).
9898
Glob can only be a `string`.
9999

100-
> ⚠️ Don't use directly `\\` in `from` (i.e `path\to\file.ext`) option because on UNIX the backslash is a valid character inside a path component, i.e., it's not a separator.
100+
> ⚠️ Don't use directly `\\` in `from` option if it is a `glob` (i.e `path\to\file.ext`) option because on UNIX the backslash is a valid character inside a path component, i.e., it's not a separator.
101101
> On Windows, the forward slash and the backward slash are both separators.
102-
> Instead please use `/` or `path` methods.
102+
> Instead please use `/`.
103103
104104
**webpack.config.js**
105105

@@ -109,13 +109,18 @@ module.exports = {
109109
new CopyPlugin({
110110
patterns: [
111111
'relative/path/to/file.ext',
112-
'/absolute/path/to/file.ext',
113112
'relative/path/to/dir',
114-
'/absolute/path/to/dir',
113+
path.resolve(__dirname, 'src', 'file.ext'),
114+
path.resolve(__dirname, 'src', 'dir'),
115115
'**/*',
116116
{
117117
from: '**/*',
118118
},
119+
// If absolute path is a `glob` we replace backslashes with forward slashes, because only forward slashes can be used in the `glob`
120+
path.posix.join(
121+
path.resolve(__dirname, 'src').replace(/\\/g, '/'),
122+
'*.txt'
123+
),
119124
],
120125
}),
121126
],
@@ -124,15 +129,15 @@ module.exports = {
124129

125130
##### `For windows`
126131

127-
If you define `from` as file path or folder path on `Windows`, you can use windows path segment (`\\`)
132+
If you define `from` as absolute file path or absolute folder path on `Windows`, you can use windows path segment (`\\`)
128133

129134
```js
130135
module.exports = {
131136
plugins: [
132137
new CopyPlugin({
133138
patterns: [
134139
{
135-
from: path.resolve('__dirname', 'file.txt'),
140+
from: path.resolve(__dirname, 'file.txt'),
136141
},
137142
],
138143
}),
@@ -144,45 +149,25 @@ But you should always use forward-slashes in `glob` expressions
144149
See [fast-glob manual](https://github.com/mrmlnc/fast-glob#how-to-write-patterns-on-windows).
145150

146151
```js
147-
const FIXTURES_DIR_NORMALIZED = path
148-
.resolve(__dirname, 'fixtures')
149-
.replace(/\\/g, '/');
150-
151152
module.exports = {
152153
plugins: [
153154
new CopyPlugin({
154155
patterns: [
155156
{
156-
from: path.posix.join(FIXTURES_DIR_NORMALIZED, 'file.txt'),
157+
// If absolute path is a `glob` we replace backslashes with forward slashes, because only forward slashes can be used in the `glob`
158+
from: path.posix.join(
159+
path.resolve(__dirname, 'fixtures').replace(/\\/g, '/'),
160+
'*.txt'
161+
),
157162
},
158163
],
159164
}),
160165
],
161166
};
162167
```
163168

164-
##### `For exclude files`
165-
166-
To exclude files from the selection, you should use [globOptions.ignore option](https://github.com/mrmlnc/fast-glob#ignore)
167-
168-
**webpack.config.js**
169-
170-
```js
171-
module.exports = {
172-
plugins: [
173-
new CopyPlugin({
174-
patterns: [
175-
{
176-
from: '**/*',
177-
globOptions: {
178-
ignore: ['**/file.*', '**/ignored-directory/**'],
179-
},
180-
},
181-
],
182-
}),
183-
],
184-
};
185-
```
169+
The `context` behaves differently depending on what the `from` is (`glob`, `file` or `dir`).
170+
More [`examples`](#examples)
186171

187172
#### `to`
188173

@@ -249,12 +234,27 @@ module.exports = {
249234
};
250235
```
251236

237+
The `context` option can be an absolute or relative path. If `context` is a relative, then it is converted to absolute based to `compiler.options.context`
238+
239+
Also, `context` indicates how to interpret the search results. Further, he is considered in this role.
240+
241+
To determine the structure from which the found resources will be copied to the destination folder, the `context` option is used.
242+
243+
If `from` is a file, then `context` is equal to the directory in which this file is located. Accordingly, the result will be only the file name.
244+
245+
If `from` is a directory, then `context` is the same as `from` and is equal to the directory itself. In this case, the result will be a hierarchical structure of the found folders and files relative to the specified directory.
246+
247+
If `from` is a glob, then regardless of the `context` option, the result will be the structure specified in the `from` option
248+
249+
More [`examples`](#examples)
250+
252251
#### `globOptions`
253252

254253
Type: `Object`
255254
Default: `undefined`
256255

257256
Allows to configute the glob pattern matching library used by the plugin. [See the list of supported options][glob-options]
257+
To exclude files from the selection, you should use [globOptions.ignore option](https://github.com/mrmlnc/fast-glob#ignore)
258258

259259
**webpack.config.js**
260260

@@ -268,6 +268,7 @@ module.exports = {
268268
globOptions: {
269269
dot: true,
270270
gitignore: true,
271+
ignore: ['**/file.*', '**/ignored-directory/**'],
271272
},
272273
},
273274
],
@@ -585,6 +586,173 @@ module.exports = {
585586
};
586587
```
587588

589+
### Examples
590+
591+
#### Different variants `from` (`glob`, `file` or `dir`).
592+
593+
Take for example the following file structure:
594+
595+
```
596+
src/directory-nested/deep-nested/deepnested-file.txt
597+
src/directory-nested/nested-file.txt
598+
```
599+
600+
##### From is a Glob
601+
602+
Everything that you specify in `from` will be included in the result:
603+
604+
**webpack.config.js**
605+
606+
```js
607+
module.exports = {
608+
plugins: [
609+
new CopyPlugin({
610+
patterns: [
611+
{
612+
from: 'src/directory-nested/**/*',
613+
},
614+
],
615+
}),
616+
],
617+
};
618+
```
619+
620+
Result:
621+
622+
```txt
623+
src/directory-nested/deep-nested/deepnested-file.txt,
624+
src/directory-nested/nested-file.txt
625+
```
626+
627+
If you want only content `src/directory-nested/`, you should only indicate `glob` in `from`. The path to the folder in which the search should take place, should be moved to `context`.
628+
629+
**webpack.config.js**
630+
631+
```js
632+
module.exports = {
633+
plugins: [
634+
new CopyPlugin({
635+
patterns: [
636+
{
637+
from: '**/*',
638+
context: path.resolve(__dirname, 'src', 'directory-nested'),
639+
},
640+
],
641+
}),
642+
],
643+
};
644+
```
645+
646+
Result:
647+
648+
```txt
649+
deep-nested/deepnested-file.txt,
650+
nested-file.txt
651+
```
652+
653+
##### From is a Dir
654+
655+
**webpack.config.js**
656+
657+
```js
658+
module.exports = {
659+
plugins: [
660+
new CopyPlugin({
661+
patterns: [
662+
{
663+
from: path.resolve(__dirname, 'src', 'directory-nested'),
664+
},
665+
],
666+
}),
667+
],
668+
};
669+
```
670+
671+
Result:
672+
673+
```txt
674+
deep-nested/deepnested-file.txt,
675+
nested-file.txt
676+
```
677+
678+
Technically, this is `**/*` with a predefined context equal to the specified directory.
679+
680+
**webpack.config.js**
681+
682+
```js
683+
module.exports = {
684+
plugins: [
685+
new CopyPlugin({
686+
patterns: [
687+
{
688+
from: '**/*',
689+
context: path.resolve(__dirname, 'src', 'directory-nested'),
690+
},
691+
],
692+
}),
693+
],
694+
};
695+
```
696+
697+
Result:
698+
699+
```txt
700+
deep-nested/deepnested-file.txt,
701+
nested-file.txt
702+
```
703+
704+
##### From is a File
705+
706+
```js
707+
module.exports = {
708+
plugins: [
709+
new CopyPlugin({
710+
patterns: [
711+
{
712+
from: path.resolve(
713+
__dirname,
714+
'src',
715+
'directory-nested',
716+
'nested-file.txt'
717+
),
718+
},
719+
],
720+
}),
721+
],
722+
};
723+
```
724+
725+
Result:
726+
727+
```txt
728+
nested-file.txt
729+
```
730+
731+
Technically, this is a filename with a predefined context equal to `path.dirname(pathToFile)`.
732+
733+
**webpack.config.js**
734+
735+
```js
736+
module.exports = {
737+
plugins: [
738+
new CopyPlugin({
739+
patterns: [
740+
{
741+
from: 'nested-file.txt',
742+
context: path.resolve(__dirname, 'src', 'directory-nested'),
743+
},
744+
],
745+
}),
746+
],
747+
};
748+
```
749+
750+
Result:
751+
752+
```txt
753+
nested-file.txt
754+
```
755+
588756
## Contributing
589757

590758
Please take a moment to read our contributing guidelines if you haven't yet done so.

0 commit comments

Comments
 (0)