From 35559201a4a0a5b111ce58d6824e5b4030eb4496 Mon Sep 17 00:00:00 2001 From: Michael Garvin Date: Wed, 13 Jan 2021 09:29:13 -0800 Subject: [PATCH] fix(docs): clean up `npm search` docs In which the "note on caching" is finally populated after all these years PR-URL: https://github.com/npm/cli/pull/2487 Credit: @wraithgar Close: #2487 Reviewed-by: @darcyclarke --- docs/content/commands/npm-search.md | 85 ++++++++++++++++++----------- lib/search.js | 2 +- 2 files changed, 55 insertions(+), 32 deletions(-) diff --git a/docs/content/commands/npm-search.md b/docs/content/commands/npm-search.md index 991bfe9e131f2..33864d472d4a2 100644 --- a/docs/content/commands/npm-search.md +++ b/docs/content/commands/npm-search.md @@ -16,35 +16,42 @@ aliases: s, se, find Search the registry for packages matching the search terms. `npm search` performs a linear, incremental, lexically-ordered search through package -metadata for all files in the registry. If color is enabled, it will further -highlight the matches in the results. +metadata for all files in the registry. If your terminal has color +support, it will further highlight the matches in the results. This can +be disabled with the config item `color` -Additionally, using the `--searchopts` and `--searchexclude` options paired with -more search terms will respectively include and exclude further patterns. The -main difference between `--searchopts` and the standard search terms is that the -former does not highlight results in the output and can be used for more -fine-grained filtering. Additionally, both of these can be added to `.npmrc` for -default search filtering behavior. +Additionally, using the `--searchopts` and `--searchexclude` options +paired with more search terms will include and exclude further patterns. +The main difference between `--searchopts` and the standard search terms +is that the former does not highlight results in the output and you can +use them more fine-grained filtering. Additionally, you can add both of +these to your config to change default search filtering behavior. Search also allows targeting of maintainers in search results, by prefixing their npm username with `=`. -If a term starts with `/`, then it's interpreted as a regular expression and -supports standard JavaScript RegExp syntax. A trailing `/` will be ignored in -this case. (Note that many regular expression characters must be escaped or -quoted in most shells.) - -### A Note on caching +If a term starts with `/`, then it's interpreted as a regular expression +and supports standard JavaScript RegExp syntax. In this case search will +ignore a trailing `/` . (Note you must escape or quote many regular +expression characters in most shells.) ### Configuration +All of the following can be defined in a `.npmrc` file, or passed as +parameters to the cli prefixed with `--` (e.g. `--json`) + #### description * Default: true * Type: Boolean -Used as `--no-description`, disables search matching in package descriptions and -suppresses display of that field in results. +#### color + + * Default: true + * Type: Boolean + +Used as `--no-color`, disables color highlighting of matches in the +results. #### json @@ -66,9 +73,9 @@ Output search results as lines with tab-separated columns. * Type: Boolean Display full package descriptions and other long text across multiple -lines. When disabled (default) search results are truncated to fit -neatly on a single line. Modules with extremely long names will -fall on multiple lines. +lines. When disabled (which is the default) the output will +truncate search results to fit neatly on a single line. Modules with +extremely long names will fall on multiple lines. #### searchopts @@ -84,23 +91,37 @@ Space-separated options that are always passed to search. Space-separated options that limit the results from search. -#### searchstaleness - -* Default: 900 (15 minutes) -* Type: Number - -The age of the cache, in seconds, before another registry request is made. - #### registry * Default: https://registry.npmjs.org/ * Type: url -Search the specified registry for modules. If you have configured npm to point -to a different default registry, such as your internal private module -repository, `npm search` will default to that registry when searching. Pass a -different registry url such as the default above in order to override this -setting. +Search the specified registry for modules. If you have configured npm to +point to a different default registry (such as your internal private +module repository), `npm search` will also default to that registry when +searching. + +### A note on caching + +The npm cli caches search results with the same terms and options +locally in its cache. You can use the following to change how and when +the cli uses this cache. See [`npm cache`](/commands/npm-cache) for more +on how the cache works. + +#### prefer-online + +Forced staleness checks for cached searches, making the cli look for +updates immediately even for fresh search results. + +#### prefer-offline + +Bypasses staleness checks for cached. Missing data will still be +requested from the server. To force full offline mode, use `offline`. + +#### offline + +Forces full offline mode. Any searches not locally cached will result in +an error. ### See Also @@ -108,3 +129,5 @@ setting. * [npm config](/commands/npm-config) * [npmrc](/configuring-npm/npmrc) * [npm view](/commands/npm-view) +* [npm cache](/commands/npm-cache) +* https://npm.im/npm-registry-fetch diff --git a/lib/search.js b/lib/search.js index 38f5a1d77b322..a3d806d2f1507 100644 --- a/lib/search.js +++ b/lib/search.js @@ -12,7 +12,7 @@ const completion = require('./utils/completion/none.js') const usage = usageUtil( 'search', - 'npm search [--long] [search terms ...]' + 'npm search [-l|--long] [--json] [--parseable] [--no-description] [search terms ...]' ) const cmd = (args, cb) => search(args).then(() => cb()).catch(cb)