diff options
author | Michael Garvin <gar+gh@danger.computer> | 2021-01-13 20:29:13 +0300 |
---|---|---|
committer | Michael Garvin <gar+gh@danger.computer> | 2021-01-15 00:23:09 +0300 |
commit | 35559201a4a0a5b111ce58d6824e5b4030eb4496 (patch) | |
tree | 0c7677b46e1aa3aafbe5b77b8199fa4cec30048a /docs | |
parent | 23df96d3394ba0b69a37f416d7f0c26bb9354975 (diff) |
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
Diffstat (limited to 'docs')
-rw-r--r-- | docs/content/commands/npm-search.md | 85 |
1 files changed, 54 insertions, 31 deletions
diff --git a/docs/content/commands/npm-search.md b/docs/content/commands/npm-search.md index 991bfe9e1..33864d472 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 |