.\" Automatically generated by Pandoc 3.10.2
.\"
.TH "bup\-config" "5" "2026\-09\-01" "Bup 0.34+"
.SH NAME
bup\-config \- bup configuration options
.SH DESCRIPTION
The following options may be set in the relevant \f[CR]git\f[R] config
(\f[CR]git\-config(1)\f[R]).
For example:
.IP
.EX
git \-\-git\-dir=\(dq$BUP_DIR\(dq config bup.split.trees true
.EE
.SH OPTIONS
.TP
bup.repo.id
When set, an identifier for the repository which should be unique across
all repositories encountered.
Because it is currently used in filesystem paths, it must consist of
only the characters within double\-quotes here: \(lq0123456789_\-\(rq,
\(lqABCDEFGHIJKLMNOPQRSTUVWXYZ\(rq, and
\(lqabcdefghijklmnopqrstuvwxyz\(rq.
Two repo\-ids must also not differ only in case (\(lqsomething\(rq vs
\(lqSOMETHING\(rq) unless all all relevant filesystems are case
sensitive.
.RS
\f[CR]bup init\f[R] now adds a random identifier when it creates new
repositories or refreshes a existing repository that doesn\(cqt have a
\f[CR]bup.repo.id\f[R], so you can add one to repositories created
before this became the norm by re\-running \f[CR]bup init\f[R].
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 \f[CR]cp\f[R](1) or across hosts via
\f[CR]rsync\f[R](1)) since duplicate identifiers can cause significant
performance problems, if nothing else.
.RE
.TP
bup.server.deduplicate\-writes (default \f[CR]true\f[R])
When \f[CR]true\f[R] \f[CR]bup\-server\f[R](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 \f[CR]*.idx\f[R] file
that the object was found in so that it can avoid sending duplicate
data.
.RS
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 \f[CR]*.idx\f[R] 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 \f[CR]$BUP_DIR/dumb\-server\-mode\f[R] file
exists, then \f[CR]bup\f[R] will act as if this setting were
\f[CR]false\f[R].
.RE
.TP
bup.split.files (default \f[CR]legacy:13\f[R])
Method used to split data for deduplication, for example by
\f[CR]bup save\f[R] or \f[CR]bup split\f[R].
Should not normally be changed after adding any data to the repository
(see below).
.RS
This determines the \(lqgranularity\(rq of the deduplication, with
larger values producing, on average, larger chunks.
The value must be a string like \f[CR]legacy:N\f[R] where the integer
\f[CR]N\f[R] 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.
\f[CR]N\f[R] 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\(habits (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 \f[CR]legacy:13\f[R] 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\(cqs 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 \f[CR]bup get \-\-rewrite\f[R]s to new
repositories with different settings.
\f[CR]legacy\f[R] refers to the current split method, which has an
unintentional, but harmless quirk.
See DESIGN in the source tree for further details.
\f[I]NOTE:\f[R] 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.
\f[I]NOTE:\f[R] As with \f[CR]bup.split.trees\f[R] below (see NOTE),
using the same index for repositories with different
\f[CR]bup.split.files\f[R] settings will result in the index
optimizations not working correctly, and so \f[CR]bup save\f[R] will
have to completely re\-read files that haven\(cqt been modified, which
is expensive.
.RE
.TP
bup.split.trees
When this boolean option is set to true, \f[CR]bup\f[R] will attempt to
split trees (directories) when writing to the repository during, for
example \f[CR]bup save ...\f[R], \f[CR]bup gc ..\f[R], 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 \(lqHandling large directories\(rq in the DESIGN in the
\f[CR]bup\f[R] source for additional information.
.RS
\f[I]NOTE:\f[R] 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\(cqs hash allows bup to avoid traversing the directory
if the index indicates that it didn\(cqt 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\(cqt be found in a repository that has
a different \f[CR]bup.split.trees\f[R] 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.
.RE
.TP
core.compression
The default pack file compression level if \f[CR]core.compression\f[R]
isn\(cqt set.
If this isn\(cqt set either, the default is 1 (unlike git, which
defaults to \-1).
A compression level given on the command\-line overrides this.
See also \f[CR]git\-config\f[R](1).
.TP
pack.compression
The default pack file compression level.
If not given, falls back to \f[CR]core.compression\f[R].
See also \f[CR]git\-config\f[R](1).
.TP
pack.packSizeLimit
Limits the maximum pack size (see \f[CR]git\-config\f[R](1)) when
writing pack files (e.g.\ via \f[CR]bup save\f[R]).
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 \f[CR]bup\f[R]
may exceed this limit by a chunk.
However, setting it to e.g.\ \(lq2g\(rq (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.
.SH ENVIRONMENT
.TP
BUP_DIR
When set, the default repository location, unless overridden by
\f[CR]bup \-d\f[R] on the command line.
.TP
XDG_CACHE_HOME/bup
The preferred cache location.
.SH FILES
$XDG_CACHE_HOME/bup/remote
.PD 0
.P
.PD
\(ti/.cache/bup/remote
.PD 0
.P
.PD
.TP
$BUP_DIR/index\-cache
The client index cache locations, in order of precedence.
Remote repository data is stored here during operations like
\f[CR]bup save \-r\f[R].
Currently \f[CR]bup\f[R] looks for existing data in precedence order,
and if none is found for the repository of interest then \f[CR]bup\f[R]
will use \f[CR]$XDG_CACHE_HOME/bup/remote\f[R] if
\f[CR]$XDG_CACHE_HOME\f[R] is set and \f[CR]\(ti/.cache/bup/remote\f[R]
otherwise.
.SH SEE ALSO
\f[CR]git\-config\f[R](1)
.SH BUP
Part of the \f[CR]bup\f[R](1) suite.
.SH AUTHORS
Rob Browning \c
.MT rlb@defaultvalue.org
.ME \c.