.Dd Feb 25, 2021
.Dt cpt-search 1
.Sh NAME
.Nm cpt-search
.Nd search for cpt packages
.Sh SYNOPSIS
.Nm
.Op Fl ds
.Ar package...
.Nm
.Fl o
.Op Fl ds
.Nm
.Fl q
.Op Fl Fds
.Ar query
.Sh DESCRIPTION
.Nm
can be used to search packages. Glob characters can also be used in the search.
.Pp
The options are as follows:
.Bl -tag -width 14n
.It Fl d
Do not search the installed package database.
.It Fl s , -single
Only show the first instance of a package.
.It Fl q , -query
Search packages making use of package descriptions.
.It Fl F , -fixed
Run query mode interpreting the given pattern as a fixed string
.It Fl o , -others
Use the current directory as the package and show other instances of that
package.
.It Fl -color Ar CPT_COLOR
Enable/disable output color
.Bo
.Sy auto ,
always, never, 1, 0
.Bc
.It Fl h , -help
Show help message
.It Fl v , -version
Print version information
.It Fl -verbose
Be more verbose
.El
.Pp
The program has three modes of operations. The default operation is to search
for the packages given as positional arguments.
.Pp
If the
.Fl o
flag is specified,
.Nm
will use the name of the current directory to search for instances of other
packages with the same name.
.Pp
If the
.Fl q
flag is specified,
.Nm
will search through the name and description of packages using the given
.Ar query ,
and run a case-insensitive search through
.Xr grep 1 .
If additionally the
.Fl F
flag is given, the given
.Ar query
will be considered a fixed string.
.Sh EXAMPLES
Below are usage examples for
.Nm ,
which is a simple yet powerful utility for querying packages.
.Ss Using wildcards
.Nm
expands POSIX shell wildcards when searching for packages.
.Bd -offset indent -literal
$ cpt-search 'emacs*'
/home/cem/repos/main/community/emacs
/home/cem/repos/main/community/emacs-nox
/home/cem/repos/kiss-community/community/emacs
/var/db/cpt/installed/emacs
.Ed
.Ss Limiting search to a single package
When the
.Fl s
flag is given,
.Nm
will only output the first instance of the package.
.Bd -offset indent -literal
$ cpt-search -s emacs
/home/cem/repos/main/community/emacs
.Ed
.Pp
Here is what happens when I don't use the
.Fl s
flag:
.Bd -offset indent -literal
$ cpt-search emacs
/home/cem/repos/main/community/emacs
/home/cem/repos/kiss-community/community/emacs
/var/db/cpt/installed/emacs
.Ed
.Ss Removing installed database from the search results.
When you use the
.Fl d
flag,
.Nm
will omit the installed package database from the result. Using the above
.Em emacs
query with this flag will result in:
.Bd -offset indent -literal
$ cpt-search -d emacs
/home/cem/repos/main/community/emacs
/home/cem/repos/kiss-community/community/emacs
.Ed
.Ss Searching other instances of the current package
Sometimes you want to check whether there are other instances of your package,
especially if you are using multiple repositories from different sources. Let's
say that you are in the
.Pa ~/repos/main/community/emacs
directory and you want to know whether this same package exists in a different
repository. You then run the following command:
.Bd -offset indent -literal
$ cpt-search -od
/home/cem/repos/kiss-community/community/emacs
.Ed
.Sh AUTHOR
.An Cem Keylan Aq Mt cem@ckyln.com
.Sh LICENSE
See LICENSE for copyright information.
.Sh SEE ALSO
.Xr cpt 1