diff --git a/docs/faq.rst b/docs/faq.rst index b01db2415..1832f7226 100644 --- a/docs/faq.rst +++ b/docs/faq.rst @@ -94,7 +94,7 @@ retransfer the data since the last checkpoint. If a backup was interrupted, you normally do not need to do anything special, just invoke ``borg create`` as you always do. If the repository is still locked, -you may need to run ``borg break-lock`` before the next backup. You may use the +you may need to run ``borg break-lock`` before the next backup. You may use the same archive name as in previous attempt or a different one (e.g. if you always include the current datetime), it does not matter. @@ -265,7 +265,7 @@ Say you want to prune ``/var/log`` faster than the rest of archive *names* and then implement different prune policies for different prefixes. For example, you could have a script that does:: - borg create $REPOSITORY:main-$(date +%Y-%m-%d) --exclude /var/log / + borg create --exclude /var/log $REPOSITORY:main-$(date +%Y-%m-%d) / borg create $REPOSITORY:logs-$(date +%Y-%m-%d) /var/log Then you would have two different prune calls with different policies:: diff --git a/docs/usage/create.rst b/docs/usage/create.rst index ec49f5fa8..d221c4e65 100644 --- a/docs/usage/create.rst +++ b/docs/usage/create.rst @@ -23,7 +23,7 @@ Examples # Backup the root filesystem into an archive named "root-YYYY-MM-DD" # use zlib compression (good, but slow) - default is lz4 (fast, low compression ratio) - $ borg create -C zlib,6 /path/to/repo::root-{now:%Y-%m-%d} / --one-file-system + $ borg create -C zlib,6 --one-file-system /path/to/repo::root-{now:%Y-%m-%d} / # Backup a remote host locally ("pull" style) using sshfs $ mkdir sshfs-mount diff --git a/docs/usage/mount.rst b/docs/usage/mount.rst index 46c7d554c..f170fb317 100644 --- a/docs/usage/mount.rst +++ b/docs/usage/mount.rst @@ -36,6 +36,12 @@ Examples # which does not support lazy processing of archives. $ borg mount -o versions --glob-archives '*-my-home' --last 10 /path/to/repo /tmp/mymountpoint + # Exclusion options are supported. + # These can speed up mounting and lower memory needs significantly. + $ borg mount /path/to/repo /tmp/mymountpoint only/that/path + $ borg mount --exclude '...' /path/to/repo /tmp/mymountpoint + + borgfs ++++++ diff --git a/docs/usage/notes.rst b/docs/usage/notes.rst index 4342a8c12..d5415d0e9 100644 --- a/docs/usage/notes.rst +++ b/docs/usage/notes.rst @@ -61,6 +61,16 @@ affect metadata stream deduplication: if only this timestamp changes between backups and is stored into the metadata stream, the metadata stream chunks won't deduplicate just because of that. +``--nobsdflags`` +~~~~~~~~~~~~~~~~ + +You can use this to not query and store (or not extract and set) bsdflags - +in case you don't need them or if they are broken somehow for your fs. + +On Linux, dealing with the bsflags needs some additional syscalls. +Especially when dealing with lots of small files, this causes a noticable +overhead, so you can use this option also for speeding up operations. + ``--umask`` ~~~~~~~~~~~ diff --git a/docs/usage/tar.rst b/docs/usage/tar.rst index 3b63afb4d..dc79b708e 100644 --- a/docs/usage/tar.rst +++ b/docs/usage/tar.rst @@ -11,11 +11,11 @@ Examples $ borg export-tar /path/to/repo::Monday Monday.tar.gz --exclude '*.so' # use higher compression level with gzip - $ borg export-tar testrepo::linux --tar-filter="gzip -9" Monday.tar.gz + $ borg export-tar --tar-filter="gzip -9" testrepo::linux Monday.tar.gz - # export a gzipped tar, but instead of storing it on disk, + # export a tar, but instead of storing it on disk, # upload it to a remote site using curl. - $ borg export-tar ... --tar-filter="gzip" - | curl --data-binary @- https://somewhere/to/POST + $ borg export-tar /path/to/repo::Monday - | curl --data-binary @- https://somewhere/to/POST # remote extraction via "tarpipe" $ borg export-tar /path/to/repo::Monday - | ssh somewhere "cd extracted; tar x" diff --git a/docs/usage_general.rst.inc b/docs/usage_general.rst.inc index c87a8b8b4..2f1ec3f11 100644 --- a/docs/usage_general.rst.inc +++ b/docs/usage_general.rst.inc @@ -1,3 +1,20 @@ +Positional Arguments and Options: Order matters +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Borg only supports taking options (``-s`` and ``--progress`` in the example) +to the left or right of all positional arguments (``repo::archive`` and ``path`` +in the example), but not in between them: + +:: + + borg create -s --progress repo::archive path # good and preferred + borg create repo::archive path -s --progress # also works + borg create -s repo::archive path --progress # works, but ugly + borg create repo::archive -s --progress path # BAD + +This is due to a problem in the argparse module: http://bugs.python.org/issue15112 + + Repository URLs ~~~~~~~~~~~~~~~ @@ -373,6 +390,7 @@ Besides regular file and directory structures, Borg can preserve By default the metadata to create them with mknod(2), mkfifo(2) etc. is stored. * hardlinked regular files, devices, FIFOs (considering all items in the same archive) * timestamps in nanosecond precision: mtime, atime, ctime +* other timestamps: birthtime (on platforms supporting it) * permissions: * IDs of owning user and owning group diff --git a/src/borg/archiver.py b/src/borg/archiver.py index d99822d4f..13fc3db2a 100644 --- a/src/borg/archiver.py +++ b/src/borg/archiver.py @@ -2952,12 +2952,6 @@ class Archiver: it had before a content change happened. This can be used maliciously as well as well-meant, but in both cases mtime based cache modes can be problematic. - By default, borg tries to archive all metadata that it supports archiving. - If that is not what you want or need, there are some tuning options: - - - --nobsdflags (getting bsdflags has a speed penalty under Linux) - - --noatime (if atime changes frequently, the metadata stream will dedup badly) - The mount points of filesystems or filesystem snapshots should be the same for every creation of a new archive to ensure fast operation. This is because the file cache that is used to determine changed files quickly uses absolute filenames.