source: trunk/base/doc/port-search.1.txt @ 129855

Last change on this file since 129855 was 129060, checked in by cal@…, 5 years ago

base: document port search, #44530

  • Property svn:eol-style set to native
  • Property svn:keywords set to Id
File size: 5.3 KB
Line 
1// vim: set et sw=4 ts=8 ft=asciidoc tw=80:
2port-search(1)
3==============
4$Id: port-search.1.txt 129060 2014-12-04 20:20:09Z cal@macports.org $
5
6NAME
7----
8port-search - Search for a port using keywords
9
10SYNOPSIS
11--------
12[cmdsynopsis]
13*port* [*-dq*] *search*
14     [--case-sensitive] [--line] [--exact|--glob|--regex] [--'field' ...]
15     'keyword' ...
16
17DESCRIPTION
18-----------
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.
22
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.
104
105include::global-flags.txt[]
106
107*-q*::
108    Only print the name of the port that matched your query. Print one match per
109    line.
110
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.
116
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
152
153SEE ALSO
154--------
155man:port[1], man:string[n], man:re_syntax[n], man:port-install[1]
156
157AUTHORS
158-------
159 (C) 2014 The MacPorts Project
160 Clemens Lang <cal@macports.org>
Note: See TracBrowser for help on using the repository browser.