Changeset 123962


Ignore:
Timestamp:
Aug 16, 2014, 4:54:15 PM (5 years ago)
Author:
cal@…
Message:

base: document port list, #44530

File:
1 copied

Legend:

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

    r123943 r123962  
    66NAME
    77----
    8 port-echo - Print the list of ports the argument expands to
     8port-list - List the latest available version for the given ports
    99
    1010SYNOPSIS
    1111--------
    1212[cmdsynopsis]
    13 *port* *echo*
     13*port* *list*
    1414     [['portname' | 'pseudo-portname' | 'port-expressions' | 'port-url']]
    1515
    1616DESCRIPTION
    1717-----------
    18 *port echo* expands its argument list according to MacPorts' rules and prints
    19 a list of ports that match the expression given as argument. It can be useful to
    20 see what a pseudo-portname or a pseudo-portname selector (see man:port[1])
    21 expands to.
     18*port list* prints the latest version of the given port(s) that is available
     19through MacPorts. It prints name, version number and the relative path of the
     20port in the port tree, i.e. the name of the primary category followed by the
     21port name.
    2222
    23 If *port echo* doesn't recognize an argument as port, it will still print it
    24 as-is. You cannot use *port echo* to check whether a port exists:
     23[NOTE]
     24====
     25*port list* will always print the latest *available* version, which is not
     26necessarily the version you have installed.
    2527
    26 ----
    27 $ port echo nonexistentport
    28 nonexistentport
    29 ----
     28This leads to the common mistake that *port list installed* lists the same port
     29multiple times in the same version. This happens because *installed* expands to
     30a list of installed ports and their versions, but *port list* ignores the
     31version and prints the latest available version for each occurrence of a port in
     32*installed*. In these cases, you should use man:port-installed[1] or
     33man:port-echo[1] instead. *port installed* and *port echo* also have the
     34advantage of being much faster.
     35====
    3036
    31 EXAMPLES
    32 --------
    33 Common use cases are:
    34 
    35 ----
    36 port echo depends:zlib
    37 port echo inactive
    38 port echo obsolete
    39 port echo requested
    40 port echo leaves
    41 port echo category:^mail$
    42 ----
    43 
    44 Note that *echo* is usually 'not' used to list outdated ports, since a separate
    45 action man:port-outdated[1] exists for that. *port outdated* has the advantage
    46 compared to *port echo outdated* that it gives the reason why MacPorts considers
    47 the port outdated.
     37Pretty much the only use case for *port list* is checking which version of
     38a specific port is current in MacPorts, or if a port exists at all. Do *not* use
     39*port list* to print *outdated*, *inactive*, *installed*, *requested*, *leaves*,
     40or other pseudo-ports. Use man:port-outdated[1], man:port-installed[1], or
     41man:port-echo[1] instead.
    4842
    4943SEE ALSO
    5044--------
    51 man:port[1], man:port-outdated[1]
     45man:port[1], man:port-installed[1], man:port-echo[1], man:port-outdated[1]
    5246
    5347AUTHORS
Note: See TracChangeset for help on using the changeset viewer.