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 switch to other repositories, you need to use the
40           --all or --set-default options (see below). If you want to enable a
41           repository only to install of of its switches, you may be looking
42           for 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',
92           `local', `git', `darcs' or `hg').
93
94       --rank=RANK (absent=1)
95           Set the rank of the repository in the list of configured
96           repositories. Package definitions are looked in the repositories in
97           increasing rank order, therefore 1 is the highest priority.
98           Negative ints can be used to select from the lowest priority, -1
99           being last. set-repos can otherwise be used to explicitly set the
100           repository list at once.
101
102       -s, --short
103           Output raw lists of names, one per line, skipping any details.
104

COMMON OPTIONS

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

ENVIRONMENT VARIABLES

230       Opam makes use of the environment variables listed here. Boolean
231       variables should be set to "0", "no", "false" or the empty string to
232       disable, "1", "yes" or "true" to enable.
233
234       OPAMALLPARENS surround all filters with parenthesis
235
236       OPAMAUTOREMOVE see remove option `--auto-remove`
237
238       OPAMBESTEFFORT see option `--best-effort`
239
240       OPAMBESTEFFORTPREFIXCRITERIA sets the string that must be prepended to
241       the criteria when the `--best-effort` option is set, and is expected to
242       maximise the `opam-query` property in the solution
243
244       OPAMCOLOR, when set to always or never, sets a default value for the
245       --color option.
246
247       OPAMCRITERIA specifies user preferences for dependency solving. The
248       default value depends on the solver version, use `config report` to
249       know the current setting. See also option --criteria
250
251       OPAMCUDFFILE file save the cudf graph to file-actions-explicit.dot
252
253       OPAMCURL can be used to select a given 'curl' program. See OPAMFETCH
254       for more options.
255
256       OPAMDEBUG see options `--debug' and `--debug-level'.
257
258       OPAMDOWNLOADJOBS sets the maximum number of simultaneous downloads.
259
260       OPAMDRYRUN see option `--dry-run`
261
262       OPAMEDITOR sets the editor to use for opam file editing, overrides
263       $EDITOR and $VISUAL
264
265       OPAMERRLOGLEN sets the number of log lines printed when a sub-process
266       fails. 0 to print all.
267
268       OPAMEXTERNALSOLVER see option `--solver'.
269
270       OPAMFAKE see option `--fake`
271
272       OPAMFETCH specifies how to download files: either `wget', `curl' or a
273       custom command where variables %{url}%, %{out}%, %{retry}%,
274       %{compress}% and %{checksum}% will be replaced. Overrides the
275       'download-command' value from the main config file.
276
277       OPAMFIXUPCRITERIA same as OPAMUPGRADECRITERIA, but specific to fixup
278
279       OPAMIGNORECONSTRAINTS see install option `--ignore-constraints-on`
280
281       OPAMIGNOREPINDEPENDS see option `--ignore-pin-depends`
282
283       OPAMJOBS sets the maximum number of parallel workers to run.
284
285       OPAMJSON log json output to the given file (use character `%' to index
286       the files)
287
288       OPAMLOCKED see install option `--locked`
289
290       OPAMLOGS logdir sets log directory, default is a temporary directory in
291       /tmp
292
293       OPAMMAKECMD set the system make command to use
294
295       OPAMNOAUTOUPGRADE disables automatic internal upgrade of repositories
296       in an earlier format to the current one, on 'update' or 'init'.
297
298       OPAMKEEPLOGS tells opam to not remove some temporary command logs and
299       some backups. This skips some finalisers and may also help to get more
300       reliable backtraces
301
302       OPAMLOCKRETRIES sets the number of tries after which opam gives up
303       acquiring its lock and fails. <= 0 means infinite wait.
304
305       OPAMMERGEOUT merge process outputs, stderr on stdout
306
307       OPAMNO answer no to any question asked.
308
309       OPAMNOASPCUD Deprecated.
310
311       OPAMNOCHECKSUMS enables option --no-checksums when available.
312
313       OPAMNOSELFUPGRADE see option `--no-self-upgrade'.
314
315       OPAMPINKINDAUTO sets whether version control systems should be detected
316       when pinning to a local path. Enabled by default since 1.3.0.
317
318       OPAMPRECISETRACKING fine grain tracking of directories
319
320       OPAMREQUIRECHECKSUMS Enables option `--require-checksums' when
321       available (e.g. for `opam install`).
322
323       OPAMRETRES sets the number of tries before failing downloads.
324
325       OPAMROOT see option `--root'. This is automatically set by `opam env
326       --root=DIR --set-root'.
327
328       OPAMROOTISOK don't complain when running as root.
329
330       OPAMSAFE see option `--safe'
331
332       OPAMSHOW see option `--show`
333
334       OPAMSKIPUPDATE see option `--skip-updates`
335
336       OPAMSKIPVERSIONCHECKS bypasses some version checks. Unsafe, for
337       compatibility testing only.
338
339       OPAMSOLVERTIMEOUT change the time allowance of the solver. Default is
340       60.0, set to 0 for unlimited. Note that all solvers may not support
341       this option.
342
343       OPAMSTATUSLINE display a dynamic status line showing what's currently
344       going on on the terminal. (one of one of `always', `never' or `auto')
345
346       OPAMSTATS display stats at the end of command
347
348       OPAMSTRICT fail on inconsistencies (file reading, switch import, etc.)
349
350       OPAMSWITCH see option `--switch'. Automatically set by `opam env
351       --switch=SWITCH --set-switch'.
352
353       OPAMUNLOCKBASE see install option `--unlock-base`
354
355       OPAMUPGRADECRITERIA specifies user preferences for dependency solving
356       when performing an upgrade. Overrides OPAMCRITERIA in upgrades if both
357       are set. See also option --criteria
358
359       OPAMUSEINTERNALSOLVER see option `--use-internal-solver'.
360
361       OPAMUSEOPENSSL force openssl use for hash computing
362
363       OPAMUTF8 use UTF8 characters in output (one of one of `always', `never'
364       or `auto'). By default `auto', which is determined from the locale).
365
366       OPAMUTF8MSGS use extended UTF8 characters (camels) in opam messages.
367       Implies OPAMUTF8. This is set by default on OSX only.
368
369       OPAMVALIDATIONHOOK hook if set, uses the `%{hook%}` command to validate
370       an opam repository update
371
372       OPAMVAR_var overrides the contents of the variable var when
373       substituting `%{var}%` strings in `opam` files.
374
375       OPAMVAR_package_var overrides the contents of the variable package:var
376       when substituting `%{package:var}%` strings in `opam` files.
377
378       OPAMVERBOSE see option `--verbose'.
379
380       OPAMWORKINGDIR see option `--working-dir`
381
382       OPAMYES see option `--yes'.
383

EXIT STATUS

385       As an exception to the following, the `exec' command returns 127 if the
386       command was not found or couldn't be executed, and the command's exit
387       value otherwise.
388
389       0   Success, or true for boolean queries.
390
391       1   False. Returned when a boolean return value is expected, e.g. when
392           running with --check, or for queries like opam lint.
393
394       2   Bad command-line arguments, or command-line arguments pointing to
395           an invalid context (e.g. file not following the expected format).
396
397       5   Not found. You requested something (package, version, repository,
398           etc.) that couldn't be found.
399
400       10  Aborted. The operation required confirmation, which wasn't given.
401
402       15  Could not acquire the locks required for the operation.
403
404       20  There is no solution to the user request. This can be caused by
405           asking to install two incompatible packages, for example.
406
407       30  Error in package definition, or other metadata files. Using
408           --strict raises this error more often.
409
410       31  Package script error. Some package operations were unsuccessful.
411           This may be an error in the packages or an incompatibility with
412           your system. This can be a partial error.
413
414       40  Sync error. Could not fetch some remotes from the network. This can
415           be a partial error.
416
417       50  Configuration error. Opam or system configuration doesn't allow
418           operation, and needs fixing.
419
420       60  Solver failure. The solver failed to return a sound answer. It can
421           be due to a broken external solver, or an error in solver
422           configuration.
423
424       99  Internal error. Something went wrong, likely due to a bug in opam
425           itself.
426
427       130 User interrupt. SIGINT was received, generally due to the user
428           pressing Ctrl-C.
429

FURTHER DOCUMENTATION

431       See https://opam.ocaml.org/doc.
432

AUTHORS

434       Vincent Bernardoff <vb@luminar.eu.org>
435       Raja Boujbel <raja.boujbel@ocamlpro.com>
436       Roberto Di Cosmo <roberto@dicosmo.org>
437       Thomas Gazagnaire <thomas@gazagnaire.org>
438       Louis Gesbert <louis.gesbert@ocamlpro.com>
439       Fabrice Le Fessant <Fabrice.Le_fessant@inria.fr>
440       Anil Madhavapeddy <anil@recoil.org>
441       Guillem Rieu <guillem.rieu@ocamlpro.com>
442       Ralf Treinen <ralf.treinen@pps.jussieu.fr>
443       Frederic Tuong <tuong@users.gforge.inria.fr>
444

BUGS

446       Check bug reports at https://github.com/ocaml/opam/issues.
447
448
449
450Opam 2.0.6                                                  OPAM-REPOSITORY(1)
Impressum