1General
2-------
3
4Borg consists of a number of commands. Each command accepts
5a number of arguments and options and interprets various environment variables.
6The following sections will describe each command in detail.
7
8Commands, options, parameters, paths and such are ``set in fixed-width``.
9Option values are `underlined`. Borg has few options accepting a fixed set
10of values (e.g. ``--encryption`` of :ref:`borg_init`).
11
12.. container:: experimental
13
14   Experimental features are marked with red stripes on the sides, like this paragraph.
15
16   Experimental features are not stable, which means that they may be changed in incompatible
17   ways or even removed entirely without prior notice in following releases.
18
19.. include:: usage_general.rst.inc
20
21In case you are interested in more details (like formulas), please see
22:ref:`internals`. For details on the available JSON output, refer to
23:ref:`json_output`.
24
25.. _common_options:
26
27Common options
28~~~~~~~~~~~~~~
29
30All Borg commands share these options:
31
32.. include:: common-options.rst.inc
33
34Option ``--bypass-lock`` allows you to access the repository while bypassing
35borg's locking mechanism. This is necessary if your repository is on a read-only
36storage where you don't have write permissions or capabilities and therefore
37cannot create a lock. Examples are repositories stored on a Bluray disc or a
38read-only network storage. Avoid this option if you are able to use locks as
39that is the safer way; see the warning below.
40
41.. warning::
42
43    If you do use ``--bypass-lock``, you are responsible to ensure that no other
44    borg instances have write access to the repository. Otherwise, you might
45    experience errors and read broken data if changes to that repository are
46    being made at the same time.
47
48Examples
49~~~~~~~~
50::
51
52    # Create an archive and log: borg version, files list, return code
53    $ borg create --show-version --list --show-rc /path/to/repo::my-files files
54
55