When copying or moving files, it's common for operating systems to automatically add an increment or 'copy' to duplicate file names. This does that for Node.js applications, with automatic platform detection and support for Linux, MacOs, and Windows conventions.
Please consider following this project's author, Jon Schlinkert, and consider starring the project to show your â¤ï¸ and support.
InstallInstall with npm (requires Node.js >=8):
What does this do?$ npm install --save add-filename-increment
When copying files, it's common for operating systems to append a numerical increment or the word 'copy' to a file name to prevent the existing file from being overwritten.
This library allows you to do the same thing in your Node.js application, using the correct conventions for the most commonly used operating systems.
UsageAll methods automatically detect the platform to use, unless platform is defined on the options.
API incrementconst increment = require('add-filename-increment');
The main export is a function that adds a trailing increment to the stem (basename without extension) of the given file path or object.
Params
file {String|Object}: If the file is an object, it must have a path property.options {Object}: See available options.returns {String|Object}: Returns a file of the same type that was given, with an increment added to the file name.Example
.pathconsole.log(increment('foo/bar.txt', { platform: 'darwin' }));
console.log(increment('foo/bar.txt', { platform: 'linux' }));
console.log(increment('foo/bar.txt', { platform: 'win32' }));
Add a trailing increment to the given filepath.
Params
filepath {String}options {Object}: See available options.returns {String}Example
.fileconsole.log(increment.path('foo/bar.txt', { platform: 'darwin' }));
console.log(increment.path('foo/bar.txt', { platform: 'linux' }));
console.log(increment.path('foo/bar.txt', { platform: 'win32' }));
Add a trailing increment to the file.base of the given file object.
Params
file {String|Object}: If passed as a string, the path will be parsed to create an object using path.parse().options {Object}: See available options.returns {Object}: Returns an object.Example
.ordinalconsole.log(increment.file({ path: 'foo/bar.txt' }, { platform: 'darwin' }));
console.log(increment.file({ path: 'foo/bar.txt' }, { platform: 'linux' }));
console.log(increment.file({ path: 'foo/bar.txt' }, { platform: 'win32' }));
Returns an ordinal-suffix for the given number. This is used when creating increments for files on Linux.
Params
num {Number}returns {String}Example
.toOrdinalconst { ordinal } = require('add-filename-increment');
console.log(ordinal(1));Â
console.log(ordinal(2));Â
console.log(ordinal(3));Â
console.log(ordinal(110));Â
Returns an ordinal for the given number.
Params
num {Number}returns {String}Example
Options options.fsconst { toOrdinal } = require('add-filename-increment');
console.log(toOrdinal(1));Â
console.log(toOrdinal(2));Â
console.log(toOrdinal(3));Â
console.log(toOrdinal(110));Â
Description: Check the file system, and automatically increment the file based on existing files. Thus, if the file name is foo.txt, and foo (2).txt already exists, the file will automatically be renamed to foo (3).txt.
Also uses the correct conventions for Linux, Windows (win32), and MacOS (darwin).
Type: boolean
Default: undefined
Description: Custom function to handling incrementing a file name. This is mostly useful when options.fs is also defined, since this function will only be called if a file name needs to be incremented, allowing you to control how incrementing is done.
Type: function
Default: undefined
Description: Specify the platform conventions to use.
Type: string
Default: Uses process.platform. Valid values are linux, win32, and darwin.
Supported Operating Systems
Currently Windows, Darwin (MacOS), and Linux are supported. This library attempts to automatically use the correct conventions for each operating system. Please create an issue if you ecounter a bug.
If you use an operating system with different conventions, and you would like for this library to add support, please create an issue with a detailed description of those conventions, or feel free to do a pull request.
LinuxWhen a file is copied or moved, and the destination file path already exists, Linux uses the following conventions for incrementing the file name.
Source path Destination path Type Directory1foo.txt foo (copy).txt, foo (another copy).txt, foo (3rd copy).txt, ... file Same directory as source foo foo (copy), foo (another copy), foo (3rd copy), ... directory Same directory as source
1 On Linux, when a file or folder is copied or moved to a different directory and another file or folder with the same name exists in that directory, you are prompted to choose a new name for the file or folder, or to cancel or skip the operation.
MacOSWhen a file is copied or moved, and the destination file path already exists, MacOS uses the following conventions for incrementing the file name.
Source path Destination path Type Directory1foo.txt foo copy.txt, foo copy 2.txt, ... file Same directory as source foo.txt foo 2.txt, foo 3.txt, ... file Different directory than source foo foo copy, foo copy 2, ... directory Same directory as source
1 MacOS uses different conventions for incrementing file names when the source file is copied, moved or renamed to a different directory, versus when the file is copied into the same directory.
WindowsWhen a file is copied or moved, and the destination file path already exists, Windows uses the following conventions for incrementing the file name.
Source path Destination path Type Directory1foo.txt foo - Copy.txt file Same directory as source foo.txt foo (2).txt file Different directory than source foo (2).txt foo (3).txt file Different directory than source foo foo - Copy directory Same directory as source foo - Copy foo - Copy (2) directory Same directory as source
1 Windows uses different conventions for incrementing file names when the source file is copied, moved or renamed to a different directory, versus when the file is copied into the same directory. Also, when a folder is copied to a new directory, and the new directory already has a folder with the same name, Windows just merges the folders automatically.
About ContributingPull requests and stars are always welcome. For bugs and feature requests, please create an issue.
Please read the contributing guide for advice on opening issues, pull requests, and coding standards.
Running TestsRunning and reviewing unit tests is a great way to get familiarized with a library and its API. You can install dependencies and run tests with the following command:
Building docs$ npm install && npm test
(This project's readme.md is generated by verb, please don't edit the readme directly. Any changes to the readme must be made in the .verb.md readme template.)
To generate the readme, run the following command:
Related projects$ npm install -g verbose/verb#dev verb-generate-readme && verb
You might also be interested in these projects:
Jon Schlinkert
LicenseCopyright © 2019, Jon Schlinkert. Released under the MIT License.
This file was generated by verb-generate-readme, v0.8.0, on September 04, 2019.
RetroSearch is an open source project built by @garambo | Open a GitHub Issue
Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo
HTML:
3.2
| Encoding:
UTF-8
| Version:
0.7.4