1OPAM-REPOSITORY(1)                Opam Manual               OPAM-REPOSITORY(1)
2
3
4

NAME

6       opam-repository - Manage opam repositories.
7

SYNOPSIS

9       opam repository [OPTION]… [COMMAND] [ARG]…
10

DESCRIPTION

12       This command is used to manage package repositories. Repositories can
13       be registered through subcommands add, remove and set-url, and are
14       updated from their URLs using opam update. Their names are global for
15       all switches, and each switch has its own selection of repositories
16       where it gets package definitions from.
17
18       Main commands add, remove and set-repos act only on the current switch,
19       unless differently specified using options explained in SCOPE
20       SPECIFICATION OPTIONS.
21
22       Without a subcommand, or with the subcommand list, lists selected
23       repositories, or all configured repositories with --all.
24

COMMANDS

26       Without argument, defaults to list.
27
28       add NAME [ADDRESS] [QUORUM] [FINGERPRINTS]
29           Adds under NAME the repository at address ADDRESS to the list of
30           configured repositories, if not already registered, and sets this
31           repository for use in the current switch (or the specified scope).
32           ADDRESS is required if the repository name is not already
33           registered, and is otherwise an error if different from the
34           registered address. The quorum is a positive integer that
35           determines the validation threshold for signed repositories, with
36           fingerprints the trust anchors for said validation.
37
38           Note: By default, the repository is only added to the current
39           switch. To add a repository to other switches, you need to use the
40           --all or --set-default options (see below). If you want to enable a
41           repository only to install its switches, you may be looking for
42           opam switch create --repositories=REPOS.
43
44       remove NAME...
45           Unselects the given repositories so that they will not be used to
46           get package definitions anymore. With --all, makes opam forget
47           about these repositories completely.
48
49       set-repos NAME...
50           Explicitly selects the list of repositories to look up package
51           definitions from, in the specified priority order (overriding
52           previous selection and ranks), according to the specified scope.
53
54       set-url NAME ADDRESS [QUORUM] [FINGERPRINTS]
55           Updates the URL and trust anchors associated with a given
56           repository name. Note that if you don't specify [QUORUM] and
57           [FINGERPRINTS], any previous settings will be erased.
58
59       list
60           Lists the currently selected repositories in priority order from
61           rank 1. With --all, lists all configured repositories and the
62           switches where they are active.
63
64       priority NAME RANK
65           Synonym to add NAME --rank RANK
66

SCOPE SPECIFICATION OPTIONS

68       These flags allow one to choose which selections are changed by add,
69       remove, set-repos. If no flag in this section is specified the updated
70       selections default to the current switch. Multiple scopes can be
71       selected, e.g. --this-switch --set-default.
72
73       -a, --all-switches
74           Act on the selections of all configured switches
75
76       --dont-select
77           Don't update any selections
78
79       --on-switches=SWITCHES
80           Act on the selections of the given list of switches
81
82       --set-default
83           Act on the default repository selection that is used for newly
84           created switches
85
86       --this-switch
87           Act on the selections for the current switch (this is the default)
88

OPTIONS

90       -k KIND, --kind=KIND
91           Specify the kind of the repository to be used (one of http, local,
92           git, darcs or hg).
93
94       --no
95           Answer no to all opam yes/no questions without prompting. See also
96           --confirm-level. This is equivalent to setting $OPAMNO to "true".
97
98       --rank=RANK (absent=1)
99           Set the rank of the repository in the list of configured
100           repositories. Package definitions are looked in the repositories in
101           increasing rank order, therefore 1 is the highest priority.
102           Negative ints can be used to select from the lowest priority, -1
103           being last. set-repos can otherwise be used to explicitly set the
104           repository list at once.
105
106       -s, --short
107           Output raw lists of names, one per line, skipping any details.
108
109       -y, --yes
110           Answer yes to all opam yes/no questions without prompting. See also
111           --confirm-level. This is equivalent to setting $OPAMYES to "true".
112

COMMON OPTIONS

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

ENVIRONMENT

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

CLI VERSION

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

EXIT STATUS

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

FURTHER DOCUMENTATION

527       See https://opam.ocaml.org/doc.
528

AUTHORS

530       Vincent Bernardoff <vb@luminar.eu.org>
531       Raja Boujbel <raja.boujbel@ocamlpro.com>
532       Roberto Di Cosmo <roberto@dicosmo.org>
533       Thomas Gazagnaire <thomas@gazagnaire.org>
534       Louis Gesbert <louis.gesbert@ocamlpro.com>
535       Fabrice Le Fessant <Fabrice.Le_fessant@inria.fr>
536       Anil Madhavapeddy <anil@recoil.org>
537       Guillem Rieu <guillem.rieu@ocamlpro.com>
538       Ralf Treinen <ralf.treinen@pps.jussieu.fr>
539       Frederic Tuong <tuong@users.gforge.inria.fr>
540

BUGS

542       Check bug reports at https://github.com/ocaml/opam/issues.
543
544
545
546Opam 2.1.3                                                  OPAM-REPOSITORY(1)
Impressum