version-everything

Use npm to version all kinds of projects, not just javascript.

Usage no npm install needed!

<script type="module">
  import versionEverything from 'https://cdn.skypack.dev/version-everything';
</script>

README

version-everything

Version: 0.7.4

Use npm to version all kinds of projects, not just JavaScript

npm codecov Coverage Status Maintainability styled with prettier

Synchronize the package.json version string into additional text or structured data files. When called from npm's version script, all versioned files in a project will be updated and committed with a single command.

    npm install --save version-everything

How to version everything

There are several ways version-everything can be used, the only requirement is an array of files to synchronize versions into. The files can be text (php, css, markdown, whatever) or structured data (JSON or yaml).

The file list is an array specified in one of the following forms, in order of precedence:

  1. Command line arguments
  2. files key in a version-everything.config.js file
  3. version-everything.files key in the parent project's package.json file

npm lifecycle script in package.json

The simplest way to use version-everything is to hook into npm's version event. Once set up, a single npm command will update, commit and tag all versioned files in a project.

Add something like the following to your project's package.json file:

{
  "version": "1.3.6",
  "scripts": {
    "version": "version-everything && git add -u"
  },
  "version-everything": {
    "files": [
      "README.md",
      "example_wordpress_plugin.php",
      "styles.css",
      "manifest.json",
      "sadness.xml"
    ]
  }
}

Then run a command like npm version minor to bump the version and update version strings in all listed files. It's that easy!

Some structured data files may be formatted using default settings.

Replacing version strings

In text files, the following version strings will be updated.

  • Version: 1.2.34
  • ### Version: 2.34.5 (Markdown headings)
  • * @version 4.5.67
  • v0.6.0 (At end-of-line)
  • LABEL version="1.2.34" (Dockerfiles)

Notes: Colons are optional. Simple v-prefixed, git-tag style version strings must appear at the end of a line.

Additional Prefixes

Additional string or RegExp patterns can be added to the list of default patterns and will match against plain text files. When prefixes are specified, structured data files will be processed first as plain text, then again as structured data if no versions are found.

version-everything config files

This project uses cosmiconfig to load config files. The file-key should be version-everything, so files like .version-everythingrc or .version-everythingrc.js will work.

Config files should export a simple JS object and look something like this:

module.exports = {
  files: ["README.md", "example_wordpress_plugin.php", "styles.css"],
  prefix: /* a string, regexp literal or mixed array of either */
  json: {
    /* optional json config object, keys pass directly to JSON.stringify */
  },
  yaml: {
    /* optional yaml config object, passes directly to js-yaml */
  },
  xml: {
    /* optional xml config object, passes directly to xml2js */
  },
};

CommonJS module requires

Version-everything can also be used like any other Node module. The version string will be pulled from package.json and should be treated as a global constant or envvar.

const version = require("version-everything");

version(["README.md", "manifest.json"], { json: { space: 4 } });

Command Line Interface (CLI)

When run from the command line, all arguments following the command are assumed to be file paths. This command would sync versions into readme.md and manifest.json:

$ version-everything readme.md manifest.json

Other CLI flags

The following additional flags map to version-everything settings. Run version-everything -h for full usage info.

  • -p, --package-json <path to package.json file>
    Loads a specific package.json file. When present, this will able be used as the starting location for Cosmiconfig.

  • n, --dry-run
    Runs the command without modifying any files.

  • q, --quiet
    Run the command silently, without showing update messages.

  • --prefix <prefixes...>
    One or more additional pattern prefixes to match against.

Conflicting arguments

If a package.json is specified, it will be loaded first, then any subsequent args will be applied on top. So if package.json were to contain a version-everything.files array, that array would be overwritten by any list of files provided to the command line.

Recognized File Extensions

Files with the following extensions will be recognized as structured text and parsed accordingly.

  • JSON - .json
  • XML - .xml
  • YAML - .yml, .yaml

API

versionEverything(files, [options])

All keys are optional. Files is practically required, without a list of files there's nothing to do.

files

Type: array

An array containing the files which will be versioned.

prefix

Type: string|RegExp|[string|RegExp]

A string, RegExp, or a mixed array of either. Will be added to the list of standard version patterns to be replaced in plain-text files.

options

Type: object All keys are optional.

json

Type: object Three keys from the json object will be passed directly to JSON.parse or JSON.stringify: space which sets indentation from an integer or string, a reviver function and a replacer function/array. See the JSON docs for more info.

Default JSON Options:

{
  space: 2,
  replacer: null,
  reviver: null,
}

xml

Type: object Merged with a minimal set of defaults, then passed to the xml-js js2xml converter. See [xml-js docs][] for available options.

Default XML Options:

{
  compact: false,
  spaces: 2,
  indentCdata: true,
}
yaml

Type: object Passed directly to the js-yaml safeDump method. See js-yaml docs for available options.

Notes

npm may fail to commit/tag files when package.json is nested below the git repository root. Ref: npm#18795

Enabling push.followTags in Git's global config is highly recommended: git config --global push.followTags true

While this module strongly encourages the use of true SemVer versions, these are not enforced. Just about any wacky version string without a whitespace character should work.

Empty CData blocks <![CDATA[]]> will be removed from processed XML Documents. To preserve empty blocks, add one or more spaces: <![CDATA[ ]]>

For some reason I can't remember, most test fixtures are in test/fixture/deep/dotfile. Ref #28