borg/docs/usage/create.rst.inc

.. IMPORTANT: this file is auto-generated from borg's built-in help, do not edit!

.. _borg_create:

borg create
-----------
::

    borg create <options> ARCHIVE PATH

positional arguments
    ARCHIVE
        name of archive to create (must be also a valid directory name)
    PATH
        paths to archive

optional arguments
    ``-n``, ``--dry-run``
        | do not create a backup archive
    ``-s``, ``--stats``
        | print statistics for the created archive
    ``-p``, ``--progress``
        | show progress display while creating the archive, showing Original, Compressed and Deduplicated sizes, followed by the Number of files seen and the path being processed, default: False
    ``--list``
        | output verbose list of items (files, dirs, ...)
    ``--filter STATUSCHARS``
        | only display items with the given status characters

`Common options`_
    |

Exclusion options
    ``-e PATTERN``, ``--exclude PATTERN``
        | exclude paths matching PATTERN
    ``--exclude-from EXCLUDEFILE``
        | read exclude patterns from EXCLUDEFILE, one per line
    ``--exclude-caches``
        | exclude directories that contain a CACHEDIR.TAG file (http://www.brynosaurus.com/cachedir/spec.html)
    ``--exclude-if-present NAME``
        | exclude directories that are tagged by containing a filesystem object with the given NAME
    ``--keep-exclude-tags``, ``--keep-tag-files``
        | keep tag objects (i.e.: arguments to --exclude-if-present) in otherwise excluded caches/directories

Filesystem options
    ``-x``, ``--one-file-system``
        | stay in same file system, do not cross mount points
    ``--numeric-owner``
        | only store numeric user and group identifiers
    ``--noatime``
        | do not store atime into archive
    ``--noctime``
        | do not store ctime into archive
    ``--ignore-inode``
        | ignore inode data in the file metadata cache used to detect unchanged files.
    ``--read-special``
        | open and read block and char device files as well as FIFOs as if they were regular files. Also follows symlinks pointing to these kinds of files.

Archive options
    ``--comment COMMENT``
        | add a comment text to the archive
    ``--timestamp TIMESTAMP``
        | manually specify the archive creation date/time (UTC, yyyy-mm-ddThh:mm:ss format). alternatively, give a reference file/directory.
    ``-c SECONDS``, ``--checkpoint-interval SECONDS``
        | write checkpoint every SECONDS seconds (Default: 1800)
    ``--chunker-params PARAMS``
        | specify the chunker parameters (CHUNK_MIN_EXP, CHUNK_MAX_EXP, HASH_MASK_BITS, HASH_WINDOW_SIZE). default: 19,23,21,4095
    ``-C COMPRESSION``, ``--compression COMPRESSION``
        | select compression algorithm, see the output of the "borg help compression" command for details.
    ``--compression-from COMPRESSIONCONFIG``
        | read compression patterns from COMPRESSIONCONFIG, see the output of the "borg help compression" command for details.

Description
~~~~~~~~~~~

This command creates a backup archive containing all files found while recursively
traversing all paths specified. When giving '-' as path, borg will read data
from standard input and create a file 'stdin' in the created archive from that
data.

The archive will consume almost no disk space for files or parts of files that
have already been stored in other archives.

The archive name needs to be unique. It must not end in '.checkpoint' or
'.checkpoint.N' (with N being a number), because these names are used for
checkpoints and treated in special ways.

In the archive name, you may use the following placeholders:
{now}, {utcnow}, {fqdn}, {hostname}, {user} and some others.

To speed up pulling backups over sshfs and similar network file systems which do
not provide correct inode information the --ignore-inode flag can be used. This
potentially decreases reliability of change detection, while avoiding always reading
all files on these file systems.

See the output of the "borg help patterns" command for more help on exclude patterns.
See the output of the "borg help placeholders" command for more help on placeholders.

.. man NOTES

The --exclude patterns are not like tar. In tar --exclude .bundler/gems will
exclude foo/.bundler/gems. In borg it will not, you need to use --exclude
'\*/.bundler/gems' to get the same effect. See ``borg help patterns`` for
more information.

Item flags
++++++++++

``--list`` outputs a list of all files, directories and other
file system items it considered (no matter whether they had content changes
or not). For each item, it prefixes a single-letter flag that indicates type
and/or status of the item.

If you are interested only in a subset of that output, you can give e.g.
``--filter=AME`` and it will only show regular files with A, M or E status (see
below).

A uppercase character represents the status of a regular file relative to the
"files" cache (not relative to the repo -- this is an issue if the files cache
is not used). Metadata is stored in any case and for 'A' and 'M' also new data
chunks are stored. For 'U' all data chunks refer to already existing chunks.

- 'A' = regular file, added (see also :ref:`a_status_oddity` in the FAQ)
- 'M' = regular file, modified
- 'U' = regular file, unchanged
- 'E' = regular file, an error happened while accessing/reading *this* file

A lowercase character means a file type other than a regular file,
borg usually just stores their metadata:

- 'd' = directory
- 'b' = block device
- 'c' = char device
- 'h' = regular file, hardlink (to already seen inodes)
- 's' = symlink
- 'f' = fifo

Other flags used include:

- 'i' = backup data was read from standard input (stdin)
- '-' = dry run, item was *not* backed up
- 'x' = excluded, item was *not* backed up
- '?' = missing status code (if you see this, please file a bug report!)