1OPAM ADMIN-FILTER(1)           Opam admin Manual          OPAM ADMIN-FILTER(1)
2
3
4

NAME

6       opam admin-filter - Filters a repository to only keep selected packages
7

SYNOPSIS

9       opam admin filter [OPTION]... [PATTERNS]...
10

DESCRIPTION

12       This command removes all package definitions that don't match the
13       search criteria (specified similarly to 'opam admin list') from a
14       repository.
15

ARGUMENTS

17       PATTERNS
18           Package patterns with globs. matching against NAME or NAME.VERSION
19

OPTIONS

21       --dry-run
22           List the removal commands, without actually performing them
23
24       --environment=VAR=VALUE[;VAR=VALUE]
25           Use the given opam environment, in the form of a list of
26           comma-separated 'var=value' bindings, when resolving variables.
27           This is used e.g. when computing available packages: if undefined,
28           availability of packages will be assumed as soon as it can not be
29           resolved purely from globally defined variables. Note that, unless
30           overridden, variables like 'root' or 'opam-version' may be taken
31           from the current opam installation. What is defined in
32           ~/.opam/config is always ignored.
33
34       --no
35           Answer no to all opam yes/no questions without prompting. See also
36           --confirm-level. This is equivalent to setting $OPAMNO to "true".
37
38       --remove
39           Invert the behaviour and remove the matching packages, keeping the
40           ones that don't match.
41
42       -y, --yes
43           Answer yes to all opam yes/no questions without prompting. See also
44           --confirm-level. This is equivalent to setting $OPAMYES to "true".
45

PACKAGE SELECTION OPTIONS

47       -a, --available
48           List only packages that are available according to the defined
49           environment. Without --environment, this will include any packages
50           for which availability is not resolvable at this point.
51
52       -A, --all
53           Include all, even uninstalled or unavailable packages
54
55       --coinstallable-with=PACKAGES
56           Only list packages that are compatible with all of PACKAGES.
57
58       --conflicts-with=PACKAGES
59           List packages that have declared conflicts with at least one of the
60           given list. This includes conflicts defined from the packages in
61           the list, from the other package, or by a common conflict-class:
62           field.
63
64       --depends-on=PACKAGES
65           List only packages that depend on one of (comma-separated)
66           PACKAGES.
67
68       --depopts
69           Include optional dependencies in dependency requests.
70
71       --dev
72           Include development packages in dependencies.
73
74       --field-match=FIELD:PATTERN
75           Filter packages with a match for PATTERN on the given FIELD
76
77       --has-flag=FLAG
78           Only include packages which have the given flag set. Package flags
79           are one of: light-uninstall verbose plugin compiler conf
80
81       --has-tag=TAG
82           Only includes packages which have the given tag set
83
84       --installable
85           List only packages that are installable according to the defined
86           environment (this calls the solver and may be more costly; a
87           package depending on an unavailable one may be available, but is
88           never installable)
89
90       --nobuild
91           Exclude build dependencies (they are included by default).
92
93       --or
94           Instead of selecting packages that match all the criteria, select
95           packages that match any of them
96
97       --post
98           Include dependencies tagged as post.
99
100       --recursive
101           With `--depends-on' and `--required-by', display all transitive
102           dependencies rather than just direct dependencies.
103
104       --required-by=PACKAGES
105           List only the dependencies of (comma-separated) PACKAGES.
106
107       --resolve=PACKAGES
108           Restrict to a solution to install (comma-separated) PACKAGES, i.e.
109           a consistent set of packages including those. This is subtly
110           different from `--required-by --recursive`, which is more
111           predictable and can't fail, but lists all dependencies
112           independently without ensuring consistency. Without `--installed`,
113           the answer is self-contained and independent of the current
114           installation. With `--installed', it's computed from the set of
115           currently installed packages. `--no-switch` further makes the
116           solution independent from the currently pinned packages,
117           architecture, and compiler version. The combination with
118           `--depopts' is not supported.
119
120       -t, --with-test, --test
121           Include test-only dependencies.
122
123       --with-doc, --doc
124           Include doc-only dependencies.
125

COMMON OPTIONS

127       These options are common to all commands.
128
129       --best-effort
130           Don't fail if all requested packages can't be installed: try to
131           install as many as possible. Note that not all external solvers may
132           support this option (recent versions of aspcud or mccs should).
133           This is equivalent to setting $OPAMBESTEFFORT environment variable.
134
135       --cli=MAJOR.MINOR (absent=2.1)
136           Use the command-line interface syntax and semantics of MAJOR.MINOR.
137           Intended for any persistent use of opam (scripts, blog posts,
138           etc.), any version of opam in the same MAJOR series will behave as
139           for the specified MINOR release. The flag was not available in opam
140           2.0, so to select the 2.0 CLI, set the OPAMCLI environment variable
141           to 2.0 instead of using this parameter.
142
143       --color=WHEN
144           Colorize the output. WHEN must be one of `always', `never' or
145           `auto'.
146
147       --confirm-level=LEVEL
148           Confirmation level, LEVEL must be one of `ask', `no', `yes' or
149           `unsafe-yes'. Can be specified more than once. If --yes or --no are
150           also given, the value of the last --confirm-level is taken into
151           account. This is equivalent to setting  $OPAMCONFIRMLEVEL`.
152
153       --criteria=CRITERIA
154           Specify user preferences for dependency solving for this run.
155           Overrides both $OPAMCRITERIA and $OPAMUPGRADECRITERIA. For details
156           on the supported language, and the external solvers available, see
157           http://opam.ocaml.org/doc/External_solvers.html. A general guide to
158           using solver preferences can be found at
159           http://www.dicosmo.org/Articles/usercriteria.pdf.
160
161       --cudf=FILENAME
162           Debug option: Save the CUDF requests sent to the solver to
163           FILENAME-<n>.cudf.
164
165       --debug
166           Print debug message to stderr. This is equivalent to setting
167           $OPAMDEBUG to "true".
168
169       --debug-level=LEVEL
170           Like --debug, but allows specifying the debug level (--debug sets
171           it to 1). Equivalent to setting $OPAMDEBUG to a positive integer.
172
173       --git-version
174           Print the git version of opam, if set (i.e. you are using a
175           development version), and exit.
176
177       --help[=FMT] (default=auto)
178           Show this help in format FMT. The value FMT must be one of `auto',
179           `pager', `groff' or `plain'. With `auto', the format is `pager` or
180           `plain' whenever the TERM env var is `dumb' or undefined.
181
182       --ignore-pin-depends
183           Ignore extra pins required by packages that get pinned, either
184           manually through opam pin or through opam install DIR. This is
185           equivalent to setting IGNOREPINDEPENDS=true.
186
187       --json=FILENAME
188           Save the results of the opam run in a computer-readable file. If
189           the filename contains the character `%', it will be replaced by an
190           index that doesn't overwrite an existing file. Similar to setting
191           the $OPAMJSON variable.
192
193       --no-aspcud
194           Removed in 2.1.
195
196       --no-auto-upgrade
197           When configuring or updating a repository that is written for an
198           earlier opam version (1.2), opam internally converts it to the
199           current format. This disables this behaviour. Note that
200           repositories should define their format version in a 'repo' file at
201           their root, or they will be assumed to be in the older format. It
202           is, in any case, preferable to upgrade the repositories manually
203           using opam admin upgrade [--mirror URL] when possible.
204
205       -q, --quiet
206           Disables --verbose.
207
208       --root=ROOT
209           Use ROOT as the current root path. This is equivalent to setting
210           $OPAMROOT to ROOT.
211
212       --safe, --readonly
213           Make sure nothing will be automatically updated or rewritten.
214           Useful for calling from completion scripts, for example. Will fail
215           whenever such an operation is needed ; also avoids waiting for
216           locks, skips interactive questions and overrides the $OPAMDEBUG
217           variable. This is equivalent to set environment variable $OPAMSAFE.
218
219       --solver=CMD
220           Specify the CUDF solver to use for resolving package installation
221           problems. This is either a predefined solver (this version of opam
222           supports builtin-mccs+lp(), builtin-mccs+glpk,
223           builtin-dummy-z3-solver, builtin-dummy-0install-solver, aspcud,
224           mccs, aspcud-old, packup), or a custom command that should contain
225           the variables %{input}%, %{output}%, %{criteria}%, and optionally
226           %{timeout}%. This is equivalent to setting $OPAMEXTERNALSOLVER.
227
228       --strict
229           Fail whenever an error is found in a package definition or a
230           configuration file. The default is to continue silently if
231           possible.
232
233       --switch=SWITCH
234           Use SWITCH as the current compiler switch. This is equivalent to
235           setting $OPAMSWITCH to SWITCH.
236
237       --use-internal-solver
238           Disable any external solver, and use the built-in one (this
239           requires that opam has been compiled with a built-in solver). This
240           is equivalent to setting $OPAMNOASPCUD or $OPAMUSEINTERNALSOLVER.
241
242       -v, --verbose
243           Be more verbose. One -v shows all package commands, repeat to also
244           display commands called internally (e.g. tar, curl, patch etc.)
245           Repeating n times is equivalent to setting $OPAMVERBOSE to "n".
246
247       --version
248           Show version information.
249
250       -w, --working-dir
251           Whenever updating packages that are bound to a local,
252           version-controlled directory, update to the current working state
253           of their source instead of the last committed state, or the ref
254           they are pointing to. As source directory is copied as it is, if it
255           isn't clean it may result on a opam build failure.This only affects
256           packages explicitly listed on the command-line.It can also be set
257           with $OPAMWORKINGDIR.
258

ENVIRONMENT

260       Opam makes use of the environment variables listed here. Boolean
261       variables should be set to "0", "no", "false" or the empty string to
262       disable, "1", "yes" or "true" to enable.
263
264       OPAMALLPARENS surround all filters with parenthesis.
265
266       OPAMASSUMEDEPEXTS see option `--assume-depexts'.
267
268       OPAMAUTOREMOVE see remove option `--auto-remove'.
269
270       OPAMBESTEFFORT see option `--best-effort'.
271
272       OPAMBESTEFFORTPREFIXCRITERIA sets the string that must be prepended to
273       the criteria when the `--best-effort' option is set, and is expected to
274       maximise the `opam-query' property in the solution.
275
276       OPAMBUILDDOC Removed in 2.1.
277
278       OPAMBUILDTEST Removed in 2.1.
279
280       OPAMCLI see option `--cli'.
281
282       OPAMCOLOR when set to always or never, sets a default value for the
283       `--color' option.
284
285       OPAMCONFIRMLEVEL see option `--confirm-level`. OPAMCONFIRMLEVEL has
286       priority over OPAMYES and OPAMNO.
287
288       OPAMCRITERIA specifies user preferences for dependency solving. The
289       default value depends on the solver version, use `config report' to
290       know the current setting. See also option --criteria.
291
292       OPAMCUDFFILE save the cudf graph to file-actions-explicit.dot.
293
294       OPAMCUDFTRIM controls the filtering of unrelated packages during CUDF
295       preprocessing.
296
297       OPAMCURL can be used to select a given 'curl' program. See OPAMFETCH
298       for more options.
299
300       OPAMDEBUG see options `--debug' and `--debug-level'.
301
302       OPAMDEBUGSECTIONS if set, limits debug messages to the space-separated
303       list of sections. Sections can optionally have a specific debug level
304       (for example, CLIENT:2 or CLIENT CUDF:2), but otherwise use
305       `--debug-level'.
306
307       OPAMDIGDEPTH defines how aggressive the lookup for conflicts during
308       CUDF preprocessing is.
309
310       OPAMDOWNLOADJOBS sets the maximum number of simultaneous downloads.
311
312       OPAMDROPWORKINGDIR overrides packages previously updated with
313       --working-dir on update. Without this variable set, opam would keep
314       them unchanged unless explicitly named on the command-line.
315
316       OPAMDRYRUN see option `--dry-run'.
317
318       OPAMEDITOR sets the editor to use for opam file editing, overrides
319       $EDITOR and $VISUAL.
320
321       OPAMERRLOGLEN sets the number of log lines printed when a sub-process
322       fails. 0 to print all.
323
324       OPAMEXTERNALSOLVER see option `--solver'.
325
326       OPAMFAKE see option `--fake'.
327
328       OPAMFETCH specifies how to download files: either `wget', `curl' or a
329       custom command where variables %{url}%, %{out}%, %{retry}%,
330       %{compress}% and %{checksum}% will be replaced. Overrides the
331       'download-command' value from the main config file.
332
333       OPAMFIXUPCRITERIA same as OPAMUPGRADECRITERIA, but specific to fixup.
334
335       OPAMIGNORECONSTRAINTS see install option `--ignore-constraints-on'.
336
337       OPAMIGNOREPINDEPENDS see option `--ignore-pin-depends'.
338
339       OPAMINPLACEBUILD see option `--inplace-build'.
340
341       OPAMJOBS sets the maximum number of parallel workers to run.
342
343       OPAMJSON log json output to the given file (use character `%' to index
344       the files).
345
346       OPAMKEEPBUILDDIR see install option `--keep-build-dir'.
347
348       OPAMKEEPLOGS tells opam to not remove some temporary command logs and
349       some backups. This skips some finalisers and may also help to get more
350       reliable backtraces.
351
352       OPAMLOCKED combination of `--locked' and `--lock-suffix' options.
353
354       OPAMLOGS logdir sets log directory, default is a temporary directory in
355       /tmp
356
357       OPAMMAKECMD set the system make command to use.
358
359       OPAMMERGEOUT merge process outputs, stderr on stdout.
360
361       OPAMNO answer no to any question asked, see options `--no` and
362       `--confirm-level`. OPAMNO is ignored if either OPAMCONFIRMLEVEL or
363       OPAMYES is set.
364
365       OPAMNOAGGREGATE with `opam admin check', don't aggregate packages.
366
367       OPAMNOASPCUD Deprecated.
368
369       OPAMNOAUTOUPGRADE disables automatic internal upgrade of repositories
370       in an earlier format to the current one, on 'update' or 'init'.
371
372       OPAMNOCHECKSUMS enables option --no-checksums when available.
373
374       OPAMNODEPEXTS disables system dependencies handling, see option
375       `--no-depexts'.
376
377       OPAMNOENVNOTICE Internal.
378
379       OPAMNOSELFUPGRADE see option `--no-self-upgrade'
380
381       OPAMPINKINDAUTO sets whether version control systems should be detected
382       when pinning to a local path. Enabled by default since 1.3.0.
383
384       OPAMPRECISETRACKING fine grain tracking of directories.
385
386       OPAMPREPRO set this to false to disable CUDF preprocessing. Less
387       efficient, but might help debugging solver issue.
388
389       OPAMREQUIRECHECKSUMS Enables option `--require-checksums' when
390       available (e.g. for `opam install').
391
392       OPAMRETRIES sets the number of tries before failing downloads.
393
394       OPAMREUSEBUILDDIR see option `--reuse-build-dir'.
395
396       OPAMROOT see option `--root'. This is automatically set by `opam env
397       --root=DIR --set-root'.
398
399       OPAMROOTISOK don't complain when running as root.
400
401       OPAMSAFE see option `--safe'.
402
403       OPAMSHOW see option `--show'.
404
405       OPAMSKIPUPDATE see option `--skip-updates'.
406
407       OPAMSKIPVERSIONCHECKS bypasses some version checks. Unsafe, for
408       compatibility testing only.
409
410       OPAMSOLVERALLOWSUBOPTIMAL (default `true') allows some solvers to still
411       return a solution when they reach timeout; while the solution remains
412       assured to be consistent, there is no guarantee in this case that it
413       fits the expected optimisation criteria. If `true', opam willcontinue
414       with a warning, if `false' a timeout is an error. Currently only the
415       builtin-z3 backend handles this degraded case.
416
417       OPAMSOLVERTIMEOUT change the time allowance of the solver. Default is
418       60.0, set to 0 for unlimited. Note that all solvers may not support
419       this option.
420
421       OPAMSTATS display stats at the end of command.
422
423       OPAMSTATUSLINE display a dynamic status line showing what's currently
424       going on on the terminal. (one of one of `always', `never' or `auto')
425
426       OPAMSTRICT fail on inconsistencies (file reading, switch import, etc.).
427
428       OPAMSWITCH see option `--switch'. Automatically set by `opam env
429       --switch=SWITCH --set-switch'.
430
431       OPAMUNLOCKBASE see install option `--unlock-base'.
432
433       OPAMUPGRADECRITERIA specifies user preferences for dependency solving
434       when performing an upgrade. Overrides OPAMCRITERIA in upgrades if both
435       are set. See also option --criteria.
436
437       OPAMUSEINTERNALSOLVER see option `--use-internal-solver'.
438
439       OPAMUSEOPENSSL force openssl use for hash computing.
440
441       OPAMUTF8 use UTF8 characters in output (one of one of `always', `never'
442       or `auto'). By default `auto', which is determined from the locale).
443
444       OPAMUTF8MSGS use extended UTF8 characters (camels) in opam messages.
445       Implies OPAMUTF8. This is set by default on OSX only.
446
447       OPAMVALIDATIONHOOK if set, uses the `%{hook%}' command to validate an
448       opam repository update.
449
450       OPAMVERBOSE see option `--verbose'.
451
452       OPAMVERSIONLAGPOWER do not use.
453
454       OPAMWITHDOC see install option `--with-doc'.
455
456       OPAMWITHTEST see install option `--with-test.
457
458       OPAMWORKINGDIR see option `--working-dir'.
459
460       OPAMYES see options `--yes' and `--confirm-level`. OPAMYES has has
461       priority over OPAMNO and is ignored if OPAMCONFIRMLEVEL is set.
462
463       OPAMVAR_var overrides the contents of the variable var when
464       substituting `%{var}%` strings in `opam` files.
465
466       OPAMVAR_package_var overrides the contents of the variable package:var
467       when substituting `%{package:var}%` strings in `opam` files.
468

CLI VERSION

470       All scripts and programmatic invocations of opam should use `--cli' in
471       order to ensure that they work seamlessly with future versions of the
472       opam client. Additionally, blog posts or other documentation can
473       benefit, as it prevents information from becoming stale.
474
475       Although opam only supports roots (~/.opam/) for the current version,
476       it does provide backwards compatibility for its command-line interface.
477
478       Since CLI version support was only added in opam 2.1, use OPAMCLI to
479       select 2.0 support (as opam 2.0 will just ignore it), and `--cli=2.1'
480       for 2.1 (or later) versions, since an environment variable controlling
481       the parsing of syntax is brittle. To this end, opam displays a warning
482       if OPAMCLI specifies a valid version other than 2.0, and also if
483       `--cli=2.0' is specified.
484
485       The command-line version is selected by using the `--cli' option or the
486       OPAMCLI environment variable. `--cli' may be specified morethan once,
487       where the last instance takes precedence. OPAMCLI is only inspected if
488       `--cli' is not given.
489

EXIT STATUS

491       As an exception to the following, the `exec' command returns 127 if the
492       command was not found or couldn't be executed, and the command's exit
493       value otherwise.
494
495       0   Success, or true for boolean queries.
496
497       1   False. Returned when a boolean return value is expected, e.g. when
498           running with --check, or for queries like opam lint.
499
500       2   Bad command-line arguments, or command-line arguments pointing to
501           an invalid context (e.g. file not following the expected format).
502
503       5   Not found. You requested something (package, version, repository,
504           etc.) that couldn't be found.
505
506       10  Aborted. The operation required confirmation, which wasn't given.
507
508       15  Could not acquire the locks required for the operation.
509
510       20  There is no solution to the user request. This can be caused by
511           asking to install two incompatible packages, for example.
512
513       30  Error in package definition, or other metadata files. Using
514           --strict raises this error more often.
515
516       31  Package script error. Some package operations were unsuccessful.
517           This may be an error in the packages or an incompatibility with
518           your system. This can be a partial error.
519
520       40  Sync error. Could not fetch some remotes from the network. This can
521           be a partial error.
522
523       50  Configuration error. Opam or system configuration doesn't allow
524           operation, and needs fixing.
525
526       60  Solver failure. The solver failed to return a sound answer. It can
527           be due to a broken external solver, or an error in solver
528           configuration.
529
530       99  Internal error. Something went wrong, likely due to a bug in opam
531           itself.
532
533       130 User interrupt. SIGINT was received, generally due to the user
534           pressing Ctrl-C.
535

FURTHER DOCUMENTATION

537       See https://opam.ocaml.org/doc.
538

AUTHORS

540       Vincent Bernardoff <vb@luminar.eu.org>
541       Raja Boujbel <raja.boujbel@ocamlpro.com>
542       Roberto Di Cosmo <roberto@dicosmo.org>
543       Thomas Gazagnaire <thomas@gazagnaire.org>
544       Louis Gesbert <louis.gesbert@ocamlpro.com>
545       Fabrice Le Fessant <Fabrice.Le_fessant@inria.fr>
546       Anil Madhavapeddy <anil@recoil.org>
547       Guillem Rieu <guillem.rieu@ocamlpro.com>
548       Ralf Treinen <ralf.treinen@pps.jussieu.fr>
549       Frederic Tuong <tuong@users.gforge.inria.fr>
550

BUGS

552       Check bug reports at https://github.com/ocaml/opam/issues.
553
554
555
556Opam admin 2.1.2                                          OPAM ADMIN-FILTER(1)
Impressum