Skip to content

Commit

Permalink
Browse files Browse the repository at this point in the history
fix(docs): clean up npm search docs
In which the "note on caching" is finally populated after
all these years

PR-URL: #2487
Credit: @wraithgar
Close: #2487
Reviewed-by: @darcyclarke
  • Loading branch information
wraithgar committed Jan 14, 2021
1 parent 23df96d commit 3555920
Show file tree
Hide file tree
Showing 2 changed files with 55 additions and 32 deletions.
85 changes: 54 additions & 31 deletions docs/content/commands/npm-search.md
Expand Up @@ -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

Expand All @@ -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

Expand All @@ -84,27 +91,43 @@ 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

* [npm registry](/using-npm/registry)
* [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
2 changes: 1 addition & 1 deletion lib/search.js
Expand Up @@ -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)
Expand Down

0 comments on commit 3555920

Please sign in to comment.