2026-09-01
bup-config - bup configuration options
The following options may be set in the relevant git
config (git-config(1)). For example:
git --git-dir="$BUP_DIR" config bup.split.trees truebup init now adds a random identifier when it creates new
repositories or refreshes a existing repository that doesn’t have a
bup.repo.id, so you can add one to repositories created
before this became the norm by re-running bup init. If you
do set your own identifier, consider including randomized content to
help ensure uniqueness.
Note: you should always change the identifier of a copied repository
(e.g. locally via cp(1) or across hosts via
rsync(1)) since duplicate identifiers can cause significant
performance problems, if nothing else.
true)true bup-server(1) checks each incoming
object against its local index, and if the object already exists, the
server suggests to the client that it download the *.idx
file that the object was found in so that it can avoid sending duplicate
data.
When false the server does not check its local index before writing
objects. To avoid writing duplicate objects, the server tells the client
to download all of its *.idx files at the start of the
session. This mode is useful on more limited server hardware
(i.e. routers, slow NAS devices, etc.).
If no value is set, and a $BUP_DIR/dumb-server-mode file
exists, then bup will act as if this setting were
false.
legacy:13)bup save or bup split. Should not normally be
changed after adding any data to the repository (see below).
This determines the “granularity” of the deduplication, with larger
values producing, on average, larger chunks. The value must be a string
like legacy:N where the integer N must be
greater than 12 and less than 22. The default of 13 provides backward
compatibility, but it is recommended to increase this for larger
repositories.
N specifies the number of fixed bits in the hash-split
algorithm that when all set to one produce a chunk boundary, and thus it
determines the average size of the deduplicated objects. This represents
a trade-off between the efficiency of the deduplication (fewer bits
means better deduplication) as compared to the amount of metadata to
keep on disk and the RAM usage during repo operations (more bits means
fewer objects, means less metadata space and RAM use). The expected
average blob size is 2^bits (1 << bits). A sufficiently small
change in a file would cause that much new data to be saved (plus tree
metadata). The maximum blob size is four times that.
The historical default of legacy:13 is probably small for
many current repositories. As mentioned above, setting it higher should
decrease the RAM required for many operations by roughly a factor of two
per increment while also increasing the repository’s size by some amount
(because it exposes less potential deduplication), but the effect
depends on the data stored in the repository (file sizes, deduplication
rates, etc.). If you have the space and time, you can always test
different values for your data by comparing
bup get --rewrites to new repositories with different
settings.
legacy refers to the current split method, which has an
unintentional, but harmless quirk. See DESIGN in the source tree for
further details.
NOTE: Changing this value in an existing repository will
duplicate data because it causes the split boundaries to change, so
subsequent saves will not deduplicate against the existing data; they
will just store the data again.
NOTE: As with bup.split.trees below (see NOTE),
using the same index for repositories with different
bup.split.files settings will result in the index
optimizations not working correctly, and so bup save will
have to completely re-read files that haven’t been modified, which is
expensive.
bup will attempt
to split trees (directories) when writing to the repository during, for
example bup save ..., bup gc .., etc. This can
notably decrease the size of the new data added to the repository when
large directories have changed (e.g. large active Maildirs). See
“Handling large directories” in the DESIGN in the bup
source for additional information.
NOTE: Using the same index to save to repositories that have
differing values for this option can decrease performance because the
index includes hashes for directories that have been saved and changing
this option changes the hashes for directories that are affected by
splitting.
A directory tree’s hash allows bup to avoid traversing the directory if
the index indicates that it didn’t otherwise change and the tree object
with that hash already exists in the destination repository. Since the
the value of this setting changes the hashes of splittable trees, the
hash in the index won’t be found in a repository that has a different
bup.split.trees value from the one to which that tree was
last saved. As a result, any (usually big) directory subject to tree
splitting will have to be re-read and its related hashes recalculated.
core.compression
isn’t set. If this isn’t set either, the default is 1 (unlike git, which
defaults to -1). A compression level given on the command-line overrides
this. See also git-config(1).
core.compression. See also git-config(1).
git-config(1)) when
writing pack files (e.g. via bup save). This setting is
relevant when set in the destination repository (which may be remote).
The default value is 1e9 bytes, i.e. about 0.93 GiB, and
bup may exceed this limit by a chunk. However, setting it
to e.g. “2g” (2 GiB) will still mean that all objects in the pack can be
addressed by a 31-bit offset, and thus need no large offset in the idx
file.
bup -d on the command line.
$XDG_CACHE_HOME/bup/remote
~/.cache/bup/remote
bup save -r. Currently bup looks for existing
data in precedence order, and if none is found for the repository of
interest then bup will use
$XDG_CACHE_HOME/bup/remote if $XDG_CACHE_HOME
is set and ~/.cache/bup/remote otherwise.
git-config(1)
Part of the bup(1) suite.