copy-file-util

_Copy or rename a file with optional package version number (CLI tool designed for use in npm package.json scripts)_


copy-file-util takes a source file and copies it to a new destination. 
The command's console output includes a timestamp and formatting helpful in build systems.

width=800 alt=screenshot>

A) Setup

Install package for node:
``shell
$ npm install --save-dev copy-file-util
`

B) Usage

$3

`
copy-file [SOURCE] [TARGET]
`
Parameters:
The first parameter is the source* file.
The second parameter is the target* file or folder (use the --folder flag).

$3

Run copy-file from the "scripts" section of your package.json file.

Example package.json scripts:
`json
"scripts": {
"pub-license": "copy-file src/LICENSE doc/license.txt",
"backup-license": "copy-file src/LICENSE --folder backup",
},
`

$3


Example terminal commands:
`shell
$ npm install --save-dev copy-file-util
$ copy-file src/web/api.html docs/api-manual.html
`
You can also install copy-file-util globally (--global) and then run it anywhere directly from the terminal.

$3

Command-line flags:
| Flag | Description | Values |
| ------------------ | ------------------------------------------------ | ---------- |
| --cd | Change working directory before starting copy. | string |
| --folder | Indicates the target is a folder. | N/A |
| --move | Delete the source file after copying it. | N/A |
| --no-overwrite | Abort if target file already exists. | N/A |
| --note | Place to add a comment only for humans. | string |
| --platform-eol | Save target file with OS dependent line endings. | N/A |
| --quiet | Suppress informational messages. | N/A |
| --remove-sem-ver | Deletes text like 'v1.2.3' to avoid noisy diffs. | N/A |

$3

- copy-file app.js app.mjs --quiet

Displays no output.

- copy-file app.js --folder dist

Copies app.js into the dist folder.

- copy-file 'src/Legal Notice.md' --folder dist

Copies a file that has a space in its filename.

- copy-file node_modules/ui-xlib/colors.less --folder src/css --platform-eol

Copies colors.less into your project and converts the file's EOL characters to \n for LF
on Unix and \r\n for CRLF on Windows.

- copy-file app.js --move --folder dist

Like the mv Unix command.

- copy-file default-config.json settings/config.json --no-overwrite

Performs a safe copy that aborts if the settings/config.json file already exists.

> [!NOTE]
> _Single quotes in commands are normalized so they work cross-platform and avoid the errors often encountered on Microsoft Windows._

$3


The target parameter can contain template variables, like {{package.version}} and {{package.name}}, which will be replaced with values with values from your project's package.json file.

Example:
- copy-file build/app.js dist/app-v{{package.version}}.js

Creates a copy of app.js named something like app-v1.2.3.js based on the version of your project.

C) Application Code

Even though copy-file-util is primarily intended for build scripts, the package can be used programmatically in ESM and TypeScript projects.

Example:
` typescript
import { copyFile } from 'copy-file-util';

const result = copyFile.cp('src/web/api.html' { targetFile: 'docs/api-manual.html' });
console.info('Execution time:', result.duration, 'ms');
``

See the TypeScript Declarations at the top of copy-file.ts for documentation.

---
CLI Build Tools for package.json
- 🎋 add-dist-header:  _Prepend a one-line banner comment (with license notice) to distribution files_
- 📄 copy-file-util:  _Copy or rename a file with optional package version number_
- 📂 copy-folder-util:  _Recursively copy files from one folder to another folder_
- 🪺 recursive-exec:  _Run a command on each file in a folder and its subfolders_
- 🔍 replacer-util:  _Find and replace strings or template outputs in text files_
- 🔢 rev-web-assets:  _Revision web asset filenames with cache busting content hash fingerprints_
- 🚆 run-scripts-util:  _Organize npm package.json scripts into groups of easy to manage commands_
- 🚦 w3c-html-validator:  _Check the markup validity of HTML files using the W3C validator_

Feel free to submit questions at:

github.com/center-key/copy-file-util/issues

MIT License