Skip to content

Commit

Permalink
Inject advanced options into README (#1236)
Browse files Browse the repository at this point in the history
  • Loading branch information
@raineorshine
raineorshine authored Dec 6, 2022
1 parent d00532f commit 6f9acf9
Show file tree
Hide file tree
Showing 8 changed files with 397 additions and 149 deletions.
2 changes: 2 additions & 0 deletions .markdownlint.js
View file
Original file line number Diff line number Diff line change
@@ -1,4 +1,6 @@
module.exports = {
// use code indentation rather than code fencing so that extended help can be used for both the CLI and README
'code-block-style': 0,
'first-line-heading': 0,
'line-length': 0,
'no-duplicate-heading': {
Expand Down
263 changes: 226 additions & 37 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -130,6 +130,9 @@ ncu "/^(?!react-).*$/" # windows

## Options

<!-- BEGIN Options -->
<!-- Do not edit this section by hand. It is auto-generated in build-options.ts. Run "npm run build" or "npm run build:options" to build. -->

```text
--cache Cache versions to the cache file
--cacheClear Clear the default cache, or the cache file
Expand Down Expand Up @@ -246,64 +249,250 @@ ncu "/^(?!react-).*$/" # windows
-h, --help display help for command
```

## Interactive Mode
<!-- END Options -->

Choose exactly which upgrades to make in interactive mode:
## Advanced Options

```sh
ncu --interactive
ncu -i
```
Some options have advanced usage, or allow per-package values by specifying a function in your ncurc.js file.

Select which upgrades you want:
Run `ncu --help [OPTION]` to view advanced help for a specific option, or see below:

![ncu --interactive](https://user-images.githubusercontent.com/750276/175337598-cdbb2c46-64f8-44f5-b54e-4ad74d7b52b4.png)
<!-- BEGIN Advanced Options -->
<!-- Do not edit this section by hand. It is auto-generated in build-options.ts. Run "npm run build" or "npm run build:options" to build. -->

Combine with `--format group` for a truly _luxe_ experience:
## doctor

![ncu --interactive --format group](https://user-images.githubusercontent.com/750276/175336533-539261e4-5cf1-458f-9fbb-a7be2b477ebb.png)
Usage:

## Doctor Mode
ncu --doctor
ncu -d

Usage: `ncu --doctor [-u] [options]`
Iteratively installs upgrades and runs tests to identify breaking upgrades. Reverts broken upgrades and updates package.json with working upgrades.

Iteratively installs upgrades and runs tests to identify breaking upgrades. Requires `-u` to execute (modifies your package file, lock file, and node_modules).
Add "-u" to execute (modifies your package file, lock file, and node_modules)

To be more precise:

1. Runs `npm install` (or `yarn`) and `npm test` to ensure tests are currently passing. You can specify your own scripts with `--doctorInstall` and `--doctorTest`.
2. Runs `ncu -u` to optimistically upgrade all dependencies.
1. Runs "npm install" and "npm test" to ensure tests are currently passing.
2. Runs "ncu -u" to optimistically upgrade all dependencies.
3. If tests pass, hurray!
4. If tests fail, restores package file and lock file.
5. For each dependency, install upgrade and run tests.
6. When the breaking upgrade is found, saves partially upgraded package.json (not including the breaking upgrade) and exits.
6. Prints broken upgrades with test error.
7. Saves working upgrades to package.json.

Additional options:

--doctorInstall specify a custom install script (default: "npm install" or "yarn")
--doctorTest specify a custom test script (default: "npm test")

Example:

$ ncu --doctor -u
Running tests before upgrading
npm install
npm run test
Upgrading all dependencies and re-running tests
ncu -u
npm install
npm run test
Tests failed
Identifying broken dependencies
npm install
npm install --no-save react@16.0.0
npm run test
✓ react 15.0.0 → 16.0.0
npm install --no-save react-redux@7.0.0
npm run test
✗ react-redux 6.0.0 → 7.0.0

/projects/myproject/test.js:13
throw new Error('Test failed!')
^

npm install --no-save react-dnd@11.1.3
npm run test
✓ react-dnd 10.0.0 → 11.1.3
Saving partially upgraded package.json

## format

Usage:

ncu --format [value]

Modify the output formatting or show additional information. Specify one or more comma-delimited values.

┌──────────────┬─────────────────────────────────────────────────────────────────────────┐
│ group │ Groups packages by major, minor, patch, and major version zero updates. │
├──────────────┼─────────────────────────────────────────────────────────────────────────┤
│ ownerChanged │ Shows if the package owner has changed. │
├──────────────┼─────────────────────────────────────────────────────────────────────────┤
│ repo │ Infers and displays links to the package's source code repository. │
└──────────────┴─────────────────────────────────────────────────────────────────────────┘

## groupFunction

Usage:

ncu --groupFunction [fn]

Customize how packages are divided into groups when using '--format group'. Only available in .ncurc.js or when importing npm-check-updates as a module:

/**
@param name The name of the dependency.
@param defaultGroup The predefined group name which will be used by default.
@param currentSpec The current version range in your package.json.
@param upgradedSpec The upgraded version range that will be written to your package.json.
@param upgradedVersion The upgraded version number returned by the registry.
@returns A predefined group name ('major' | 'minor' | 'patch' | 'majorVersionZero' | 'none') or a custom string to create your own group.
*/
groupFunction: (name, defaultGroup, currentSpec, upgradedSpec, upgradedVersion} {
if (name === 'typescript' && defaultGroup === 'minor') {
return 'major'
}
if (name.startsWith('@myorg/')) {
return 'My Org'
}
return defaultGroup
}

## packageManager

Usage:

ncu --packageManager [s]
ncu -p [s]

Specifies the package manager to use when looking up version numbers.

┌────────────────┬───────────────────────────────────────────────────────────────────────────────────────────┐
│ npm │ System-installed npm. Default. │
├────────────────┼───────────────────────────────────────────────────────────────────────────────────────────┤
│ yarn │ System-installed yarn. Automatically used if yarn.lock is present. │
├────────────────┼───────────────────────────────────────────────────────────────────────────────────────────┤
│ staticRegistry │ Checks versions from a static file. Must include the --registry option with the path to a │
│ │ JSON registry file. │
│ │ │
│ │ Example: │
│ │ │
│ │ $ ncu --packageManager staticRegistry --registry ./my-registry.json │
│ │ │
│ │ my-registry.json: │
│ │ │
│ │ { │
│ │ "prettier": "2.7.1", │
│ │ "typescript": "4.7.4" │
│ │ } │
└────────────────┴───────────────────────────────────────────────────────────────────────────────────────────┘

## peer

Usage:

ncu --peer

Check peer dependencies of installed packages and filter updates to compatible versions.

Example:

The following example demonstrates how --peer works, and how it uses peer dependencies from upgraded modules.

The package ncu-test-peer-update has two versions published:

- 1.0.0 has peer dependency "ncu-test-return-version": "1.0.x"
- 1.1.0 has peer dependency "ncu-test-return-version": "1.1.x"

Our test app has the following dependencies:

"ncu-test-peer-update": "1.0.0",
"ncu-test-return-version": "1.0.0"

The latest versions of these packages are:

"ncu-test-peer-update": "1.1.0",
"ncu-test-return-version": "2.0.0"

With --peer:

ncu upgrades packages to the highest version that still adheres to the peer dependency constraints:

ncu-test-peer-update 1.0.0 → 1.1.0
ncu-test-return-version 1.0.0 → 1.1.0

Without --peer:

As a comparison: without using the --peer option, ncu will suggest the latest versions, ignoring peer dependencies:

ncu-test-peer-update 1.0.0 → 1.1.0
ncu-test-return-version 1.0.0 → 2.0.0

## registry

Usage:

ncu --registry [uri]
ncu -r [uri]

Specify the registry to use when looking up package version numbers.

When --packageManager staticRegistry is set, --registry must specify a path to a JSON
registry file.

## target

Usage:

ncu --target [value]
ncu -t [value]

Determines the version to upgrade to. (default: "latest")

┌──────────┬──────────────────────────────────────────────────────────────────────────────────────────────┐
│ greatest │ Upgrade to the highest version number published, regardless of release date or tag. Includes │
├──────────┼──────────────────────────────────────────────────────────────────────────────────────────────┤
│ latest │ Upgrade to whatever the package's "latest" git tag points to. Excludes pre is specified. │
├──────────┼──────────────────────────────────────────────────────────────────────────────────────────────┤
│ minor │ Upgrade to the highest minor version without bumping the major version. │
├──────────┼──────────────────────────────────────────────────────────────────────────────────────────────┤
│ newest │ Upgrade to the version with the most recent publish date, even if there are other version │
│ │ numbers that are higher. Includes prereleases. │
├──────────┼──────────────────────────────────────────────────────────────────────────────────────────────┤
│ patch │ Upgrade to the highest patch version without bumping the minor or major versions. │
├──────────┼──────────────────────────────────────────────────────────────────────────────────────────────┤
│ @[tag] │ Upgrade to the version published to a specific tag, e.g. 'next' or 'beta'. │
└──────────┴──────────────────────────────────────────────────────────────────────────────────────────────┘

You can also specify a custom function in your .ncurc.js file, or when importing npm-check-updates as a module:

/** Custom target.
@param dependencyName The name of the dependency.
@param parsedVersion A parsed Semver object from semver-utils.
(See https://git.coolaj86.com/coolaj86/semver-utils.js#semverutils-parse-semverstring)
@returns One of the valid target values (specified in the table above).
*/
target: (dependencyName, [{ semver, version, operator, major, minor, patch, release, build }]) => {
if (major === '0') return 'minor'
return 'latest'
}

<!-- END Advanced Options -->

## Interactive Mode

Choose which packages to update in interactive mode:

```sh
$ ncu --doctor -u
npm install
npm run test
ncu -u
npm install
npm run test
Failing tests found:
/projects/myproject/test.js:13
throw new Error('Test failed!')
^
Now let's identify the culprit, shall we?
Restoring package.json
Restoring package-lock.json
npm install
npm install --no-save react@16.0.0
npm run test
✓ react 15.0.0 → 16.0.0
npm install --no-save react-redux@7.0.0
npm run test
✗ react-redux 6.0.0 → 7.0.0
Saving partially upgraded package.json
ncu --interactive
ncu -i
```

![ncu --interactive](https://user-images.githubusercontent.com/750276/175337598-cdbb2c46-64f8-44f5-b54e-4ad74d7b52b4.png)

Combine with `--format group` for a truly _luxe_ experience:

![ncu --interactive --format group](https://user-images.githubusercontent.com/750276/175336533-539261e4-5cf1-458f-9fbb-a7be2b477ebb.png)

## Config File

Use a `.ncurc.{json,yml,js}` file to specify configuration information.
Expand Down
16 changes: 2 additions & 14 deletions src/bin/cli.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ import cloneDeep from 'lodash/cloneDeep'
import pickBy from 'lodash/pickBy'
import semver from 'semver'
import pkg from '../../package.json'
import cliOptions from '../cli-options'
import cliOptions, { renderExtendedHelp } from '../cli-options'
import ncu from '../index'
import { chalkInit } from '../lib/chalk'
import getNcuRc from '../lib/getNcuRc' // async global contexts are only available in esm modules -> function
Expand Down Expand Up @@ -73,19 +73,7 @@ ${chalk.dim.underline(
const query = arg.replace(/^-*/, '')
const option = cliOptions.find(option => option.long === query || option.short === query)
if (option) {
console.info(`Usage: ncu --${option.long}${option.arg ? ` [${option.arg}]` : ''}`)
if (option.short) {
console.info(` ncu -${option.short}${option.arg ? ` [${option.arg}]` : ''}`)
}
if (option.default !== undefined && !(Array.isArray(option.default) && option.default.length === 0)) {
console.info(`Default: ${option.default}`)
}
if (option.help) {
const helpText = typeof option.help === 'function' ? option.help() : option.help
console.info(`\n${helpText}`)
} else if (option.description) {
console.info(`\n${option.description}`)
}
console.info(renderExtendedHelp(option) + '\n')
} else {
console.info(`Unknown option: ${arg}`)
}
Expand Down
Loading

0 comments on commit 6f9acf9

Please sign in to comment.