Changeset 129060


Ignore:
Timestamp:
Dec 4, 2014, 8:20:09 PM (5 years ago)
Author:
cal@…
Message:

base: document port search, #44530

File:
1 copied

Legend:

Unmodified
Added
Removed
  • trunk/base/doc/port-search.1.txt

    r129052 r129060  
    11// vim: set et sw=4 ts=8 ft=asciidoc tw=80:
    2 port-installed(1)
    3 =================
     2port-search(1)
     3==============
    44$Id$
    55
    66NAME
    77----
    8 port-installed - List installed versions of a given port, or all installed ports
     8port-search - Search for a port using keywords
    99
    1010SYNOPSIS
    1111--------
    1212[cmdsynopsis]
    13 *port* [*-vq*] *installed*
    14      [['portname' | 'pseudo-portname' | 'port-expressions' | 'port-url']]
     13*port* [*-dq*] *search*
     14     [--case-sensitive] [--line] [--exact|--glob|--regex] [--'field' ...]
     15     'keyword' ...
    1516
    1617DESCRIPTION
    1718-----------
    18 *port installed* can be used in two separate ways: Either without arguments, in
    19 which case it will print a list of all installed ports (both active and
    20 inactive), or with arguments, which will return a list of installed ports that
    21 match the argument expression.
     19*port search* helps you find ports by partial matches of the name or description
     20(or other fields, depending on the given options). It is the tool of choice if
     21you are looking for software in MacPorts.
    2222
    23 The output of *port installed* contains the name, version and variants of the
    24 installed ports and whether the port is active or inactive. See the PORT IMAGES
    25 section for an explanation of the active/inactive state.
     23*search* works by searching for your given keyword(s) in a set of fields of all
     24available ports. By default, a port's name and short description are searched,
     25as if you had specified both *--name* and *--description*. See *OPTIONS* for
     26possible values for 'field'.
     27
     28Note that you can specify multiple fields to be searched. A port will be printed
     29when any of the fields matches your keyword(s). If you specify multiple
     30keywords, *search* will run multiple separate searches, one for each given
     31keyword.
     32
     33OPTIONS
     34-------
     35
     36Search behavior
     37~~~~~~~~~~~~~~~
     38
     39*--case-sensitive*::
     40    Do not ignore case when searching for the given keyword.
     41
     42*--exact*::
     43    Search for the given string exactly. Disables *--glob* (the default) and
     44    *--regex*.
     45
     46*--glob*::
     47    Treat the keyword(s) as wildcard (i.e., expand '\*', '?' and '[sets]'). This
     48    is the default. See the *string match* section of man:string[n] for
     49    a detailed syntax description.
     50
     51*--regex*::
     52    Treat the given string as a Tcl regular expression. See man:re_syntax[n] for
     53    a description of Tcl regular expressions.
     54
     55Output behavior
     56~~~~~~~~~~~~~~~
     57
     58*--line*::
     59    Print one match per line, where a line consists of name, version, categories
     60    and short description.
     61
     62See also *-q* in the *GLOBAL OPTIONS* section below.
     63
     64Field selection
     65~~~~~~~~~~~~~~~
     66
     67*--category*, *--categories*::
     68    Search the category. You can use this to list all ports in a given category.
     69    For example, *port search --category haskell* will print all Haskell ports
     70    in MacPorts. If you don't need the description it's usually faster to use
     71    the pseudo-portname selector *category:haskell* with man:port-echo[1] (i.e.,
     72    *port echo category:haskell*) instead. See man:port[1] for more information
     73    on pseudo-port selectors.
     74
     75*--depends*, *--depends_build*, *--depends_extract*, *--depends_fetch*, *--depends_lib*, *--depends_run*::
     76    Search for ports that depend on the port given as keyword. *--depends* is an
     77    alias for all other *--depends_* options combined. Note that only
     78    dependencies present in default variants will be found by this search. As
     79    with *--category*, there also are pseudo-portname selectors available for
     80    dependencies.
     81
     82*--description*, *--long_description*::
     83    Test the search string against ports' descriptions.
     84
     85*--homepage*::
     86    Search for the keyword(s) in the homepage property.
     87
     88*--maintainer*::
     89    Search for ports maintained by a specific maintainer. Note that there also
     90    is a pseudo-portname selector available for maintainer addresses. See
     91    man:port[1] for more information.
     92
     93*--name*::
     94    Search in ports' names. Since this is the default (together with
     95    *--description*), this flag is only useful when you to search 'only' in the
     96    name, but not the description.
     97
     98*--portdir*::
     99    Test the search string against the path of the directory that contains the
     100    port.
     101
     102*--variant*, *--variants*::
     103    Search for variant names.
    26104
    27105include::global-flags.txt[]
    28106
    29 *-v*::
    30     Print the platform at install time (i.e., your OS X version) and the
    31     architecture(s) of the installed port.
     107*-q*::
     108    Only print the name of the port that matched your query. Print one match per
     109    line.
    32110
    33 *-q*::
    34     Do not print the header line. This is useful when parsing the output of
    35     *port installed* in scripts for further processing.
     111EFFICIENT SEARCHING
     112-------------------
     113The output of *search* can be overwhelming and confusing, especially with
     114a large number of results. Here are a few tips to improve your search efficiency
     115with MacPorts.
    36116
    37 include::archives.txt[]
     117Suppose you are looking for PHP in MacPorts. You might start with
     118----
     119$> port search php
     120----
     121and notice your query produces a lot of output. In fact, at the time of writing
     122this, this search produces 763 matches. By default, *search* searches both name
     123and description of a port. While we're looking for PHP, we can reduce the number
     124of hits by using the *--name* flag. Furthermore, we only want ports whose name
     125starts with “php”, so we add the *--glob* flag (actually, we could leave it out
     126because it is the default) and modify the search term to *php**. Note that the
     127asterisk needs to be escaped or quoted to prevent the shell from interpreting
     128it:
     129----
     130$> port search --name --glob 'php*'
     131----
     132Since that still produces 689 results, we can activate compressed output using
     133the *--line* flag
     134----
     135$> port search --line --name --glob 'php*'
     136----
     137Scrolling over the output, we see a large number of PHP modules starting with
     138php<version>-<modulename>. That tells us the main PHP ports might be named
     139php<version>. Using regex we can further narrow down the results:
     140----
     141$> port search --line --name --regex '^php\d+$'
     142----
     143
     144Note it is not always necessary to drill down to reduce the amount of output.
     145For example, if you're looking for *rrdtool*, a popular system to store and
     146graph time-series data, the simple approach works well, with only 12 ports being
     147returned:
     148----
     149$> port search rrd
     150----
     151
    38152
    39153SEE ALSO
    40154--------
    41 man:port[1], man:port-activate[1]
     155man:port[1], man:string[n], man:re_syntax[n], man:port-install[1]
    42156
    43157AUTHORS
Note: See TracChangeset for help on using the changeset viewer.