path: root/docs/man/borg-create.1

.\" Man page generated from reStructuredText.
.
.TH BORG-CREATE 1 "2017-02-12" "" "borg backup tool"
.SH NAME
borg-create \- Create new archive
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.SH SYNOPSIS
.sp
borg create <options> ARCHIVE PATH
.SH DESCRIPTION
.sp
This command creates a backup archive containing all files found while recursively
traversing all paths specified. When giving \(aq\-\(aq as path, borg will read data
from standard input and create a file \(aqstdin\(aq in the created archive from that
data.
.sp
The archive will consume almost no disk space for files or parts of files that
have already been stored in other archives.
.sp
The archive name needs to be unique. It must not end in \(aq.checkpoint\(aq or
\(aq.checkpoint.N\(aq (with N being a number), because these names are used for
checkpoints and treated in special ways.
.sp
In the archive name, you may use the following placeholders:
{now}, {utcnow}, {fqdn}, {hostname}, {user} and some others.
.sp
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.
.sp
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.
.SH OPTIONS
.sp
See \fIborg\-common(1)\fP for common options of Borg commands.
.SS arguments
.INDENT 0.0
.TP
.B ARCHIVE
name of archive to create (must be also a valid directory name)
.TP
.B PATH
paths to archive
.UNINDENT
.SS optional arguments
.INDENT 0.0
.TP
.B \-n\fP,\fB  \-\-dry\-run
do not create a backup archive
.TP
.B \-s\fP,\fB  \-\-stats
print statistics for the created archive
.TP
.B \-p\fP,\fB  \-\-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
.TP
.B \-\-list
output verbose list of items (files, dirs, ...)
.TP
.BI \-\-filter \ STATUSCHARS
only display items with the given status characters
.UNINDENT
.SS Exclusion options
.INDENT 0.0
.TP
.BI \-e \ PATTERN\fP,\fB \ \-\-exclude \ PATTERN
exclude paths matching PATTERN
.TP
.BI \-\-exclude\-from \ EXCLUDEFILE
read exclude patterns from EXCLUDEFILE, one per line
.TP
.B \-\-exclude\-caches
exclude directories that contain a CACHEDIR.TAG file (\fI\%http://www.brynosaurus.com/cachedir/spec.html\fP)
.TP
.BI \-\-exclude\-if\-present \ NAME
exclude directories that are tagged by containing a filesystem object with the given NAME
.TP
.B \-\-keep\-exclude\-tags\fP,\fB  \-\-keep\-tag\-files
keep tag objects (i.e.: arguments to \-\-exclude\-if\-present) in otherwise excluded caches/directories
.UNINDENT
.SS Filesystem options
.INDENT 0.0
.TP
.B \-x\fP,\fB  \-\-one\-file\-system
stay in same file system, do not cross mount points
.TP
.B \-\-numeric\-owner
only store numeric user and group identifiers
.TP
.B \-\-noatime
do not store atime into archive
.TP
.B \-\-noctime
do not store ctime into archive
.TP
.B \-\-ignore\-inode
ignore inode data in the file metadata cache used to detect unchanged files.
.TP
.B \-\-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.
.UNINDENT
.SS Archive options
.INDENT 0.0
.TP
.BI \-\-comment \ COMMENT
add a comment text to the archive
.TP
.BI \-\-timestamp \ TIMESTAMP
manually specify the archive creation date/time (UTC, yyyy\-mm\-ddThh:mm:ss format). alternatively, give a reference file/directory.
.TP
.BI \-c \ SECONDS\fP,\fB \ \-\-checkpoint\-interval \ SECONDS
write checkpoint every SECONDS seconds (Default: 1800)
.TP
.BI \-\-chunker\-params \ PARAMS
specify the chunker parameters (CHUNK_MIN_EXP, CHUNK_MAX_EXP, HASH_MASK_BITS, HASH_WINDOW_SIZE). default: 19,23,21,4095
.TP
.BI \-C \ COMPRESSION\fP,\fB \ \-\-compression \ COMPRESSION
select compression algorithm, see the output of the "borg help compression" command for details.
.TP
.BI \-\-compression\-from \ COMPRESSIONCONFIG
read compression patterns from COMPRESSIONCONFIG, see the output of the "borg help compression" command for details.
.UNINDENT
.SH EXAMPLES
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
# Backup ~/Documents into an archive named "my\-documents"
$ borg create /path/to/repo::my\-documents ~/Documents

# same, but list all files as we process them
$ borg create \-\-list /path/to/repo::my\-documents ~/Documents

# Backup ~/Documents and ~/src but exclude pyc files
$ borg create /path/to/repo::my\-files \e
    ~/Documents                       \e
    ~/src                             \e
    \-\-exclude \(aq*.pyc\(aq

# Backup home directories excluding image thumbnails (i.e. only
# /home/*/.thumbnails is excluded, not /home/*/*/.thumbnails)
$ borg create /path/to/repo::my\-files /home \e
    \-\-exclude \(aqre:^/home/[^/]+/\e.thumbnails/\(aq

# Do the same using a shell\-style pattern
$ borg create /path/to/repo::my\-files /home \e
    \-\-exclude \(aqsh:/home/*/.thumbnails\(aq

# Backup the root filesystem into an archive named "root\-YYYY\-MM\-DD"
# use zlib compression (good, but slow) \- default is no compression
$ borg create \-C zlib,6 /path/to/repo::root\-{now:%Y\-%m\-%d} / \-\-one\-file\-system

# Backup a remote host locally ("pull" style) using sshfs
$ mkdir sshfs\-mount
$ sshfs root@example.com:/ sshfs\-mount
$ cd sshfs\-mount
$ borg create /path/to/repo::example.com\-root\-{now:%Y\-%m\-%d} .
$ cd ..
$ fusermount \-u sshfs\-mount

# Make a big effort in fine granular deduplication (big chunk management
# overhead, needs a lot of RAM and disk space, see formula in internals
# docs \- same parameters as borg < 1.0 or attic):
$ borg create \-\-chunker\-params 10,23,16,4095 /path/to/repo::small /smallstuff

# Backup a raw device (must not be active/in use/mounted at that time)
$ dd if=/dev/sdx bs=10M | borg create /path/to/repo::my\-sdx \-

# No compression (default)
$ borg create /path/to/repo::arch ~

# Super fast, low compression
$ borg create \-\-compression lz4 /path/to/repo::arch ~

# Less fast, higher compression (N = 0..9)
$ borg create \-\-compression zlib,N /path/to/repo::arch ~

# Even slower, even higher compression (N = 0..9)
$ borg create \-\-compression lzma,N /path/to/repo::arch ~

# Use short hostname, user name and current time in archive name
$ borg create /path/to/repo::{hostname}\-{user}\-{now} ~
# Similar, use the same datetime format as borg 1.1 will have as default
$ borg create /path/to/repo::{hostname}\-{user}\-{now:%Y\-%m\-%dT%H:%M:%S} ~
# As above, but add nanoseconds
$ borg create /path/to/repo::{hostname}\-{user}\-{now:%Y\-%m\-%dT%H:%M:%S.%f} ~
.ft P
.fi
.UNINDENT
.UNINDENT
.SH NOTES
.sp
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
\(aq*/.bundler/gems\(aq to get the same effect. See \fBborg help patterns\fP for
more information.
.SS Item flags
.sp
\fB\-\-list\fP 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.
.sp
If you are interested only in a subset of that output, you can give e.g.
\fB\-\-filter=AME\fP and it will only show regular files with A, M or E status (see
below).
.sp
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 \(aqA\(aq and \(aqM\(aq also new data
chunks are stored. For \(aqU\(aq all data chunks refer to already existing chunks.
.INDENT 0.0
.IP \(bu 2
\(aqA\(aq = regular file, added (see also \fIa_status_oddity\fP in the FAQ)
.IP \(bu 2
\(aqM\(aq = regular file, modified
.IP \(bu 2
\(aqU\(aq = regular file, unchanged
.IP \(bu 2
\(aqE\(aq = regular file, an error happened while accessing/reading \fIthis\fP file
.UNINDENT
.sp
A lowercase character means a file type other than a regular file,
borg usually just stores their metadata:
.INDENT 0.0
.IP \(bu 2
\(aqd\(aq = directory
.IP \(bu 2
\(aqb\(aq = block device
.IP \(bu 2
\(aqc\(aq = char device
.IP \(bu 2
\(aqh\(aq = regular file, hardlink (to already seen inodes)
.IP \(bu 2
\(aqs\(aq = symlink
.IP \(bu 2
\(aqf\(aq = fifo
.UNINDENT
.sp
Other flags used include:
.INDENT 0.0
.IP \(bu 2
\(aqi\(aq = backup data was read from standard input (stdin)
.IP \(bu 2
\(aq\-\(aq = dry run, item was \fInot\fP backed up
.IP \(bu 2
\(aqx\(aq = excluded, item was \fInot\fP backed up
.IP \(bu 2
\(aq?\(aq = missing status code (if you see this, please file a bug report!)
.UNINDENT
.SH SEE ALSO
.sp
\fIborg\-common(1)\fP, \fIborg\-delete(1)\fP, \fIborg\-prune(1)\fP, \fIborg\-check(1)\fP, \fIborg\-patterns(1)\fP, \fIborg\-placeholders(1)\fP, \fIborg\-compression(1)\fP
.SH AUTHOR
The Borg Collective
.\" Generated by docutils manpage writer.
.