.\" Automatically generated by Pandoc 3.10.2
.\"
.TH "bup\-get" "1" "2026\-09\-01" "Bup 0.34+"
.SH NAME
bup\-get \- copy repository items (note CAUTION below)
.SH SYNOPSIS
bup get [\-s \f[I]source\-path\f[R]] [\-r \f[I]host\f[R]:\f[I]path\f[R]]
OPTIONS <(METHOD \f[I]ref\f[R] [\f[I]dest\f[R]])>\&...
.SH DESCRIPTION
\f[CR]bup get\f[R] transfers the indicated \f[I]ref\f[R]s from the
source repository to the destination repository (respecting
\f[CR]\-\-bup\-dir\f[R] and \f[CR]BUP_DIR\f[R]), according to the
specified METHOD, which may be one of \f[CR]\-\-ff\f[R],
\f[CR]\-\-ff:\f[R], \f[CR]\-\-append\f[R], \f[CR]\-\-append:\f[R],
\f[CR]\-\-pick\f[R], \f[CR]\-\-pick:\f[R], \f[CR]\-\-force\-pick\f[R],
\f[CR]\-\-force\-pick:\f[R], \f[CR]\-\-new\-tag\f[R],
\f[CR]\-\-new\-tag:\f[R], \f[CR]\-\-replace\f[R],
\f[CR]\-\-replace:\f[R], or \f[CR]\-\-unnamed\f[R].
By default it will \f[CR]\-\-copy\f[R] the data without alteration, but
it can also \f[CR]\-\-rewrite\f[R] it, potentially changing the
deduplication granularity, and \f[CR]\-\-repair\f[R] some kinds of
damage.
See the EXAMPLES below for a quick introduction.
.PP
The \f[I]ref\f[R] is the source repository reference of the object to be
fetched, and the \f[I]dest\f[R] is the optional destination reference.
A \f[I]dest\f[R] may only be specified for a METHOD whose name ends in a
colon.
For example:
.IP
.EX
bup get \-s /source/repo \-\-ff foo
bup get \-s /source/repo \-\-ff: foo/latest bar
bup get \-s /source/repo \-\-pick: foo/2010\-10\-10\-101010 bar
bup get \-s /source/repo \-\-pick: foo/2010\-10\-10\-101010 .tag/bar
.EE
.PP
The behavior of any given METHOD is determined in part by the
\f[I]ref\f[R] and \f[I]dest\f[R] types, i.e.\ branch, save, tag, etc.
.PP
As a special case, if \f[I]ref\f[R] names the \(lqlatest\(rq save
symlink, then bup will act exactly as if the save that \(lqlatest\(rq
points to had been specified, rather than the \(lqlatest\(rq symlink
itself, so \f[CR]bup get foo/latest\f[R] will actually be interpreted as
something like \f[CR]bup get foo/2013\-01\-01\-030405\f[R].
.PP
In some situations \f[CR]bup get\f[R] will evaluate a branch operation
according to whether or not it will be a \(lqfast\-forward\(rq (which
requires that any existing destination branch be an ancestor of the
source).
.PP
An existing destination tag can only be overwritten by a
\f[CR]\-\-replace\f[R] or \f[CR]\-\-force\-pick\f[R].
.PP
When a new commit is created (i.e.\ via \f[CR]\-\-append\f[R],
\f[CR]\-\-pick\f[R], etc.), it will have the same author, author date,
and message as the original, but a committer and committer date
corresponding to the current user and time.
.PP
If requested by the appropriate options, bup will print the commit,
tree, or tag hash for each destination reference updated.
When relevant, the tree hash will be printed before the commit hash.
.PP
Local \f[I]ref\f[R]s can be pushed to a remote repository with the
\f[CR]\-\-remote\f[R] option, and remote \f[I]ref\f[R]s can be pulled
into a local repository via \(lqbup on HOST get \&...\(rq.
See \f[CR]bup\-on\f[R](1) and the EXAMPLES below for further
information.
.PP
CAUTION: This is one of the few bup commands that can modify your
archives in intentionally destructive ways.
Though if an attempt to join or restore the data you still care about
succeeds after you\(cqve run this command, then that\(cqs a fairly
encouraging sign that it worked correctly.
(The dev/compare\-trees command in the source tree can be used to help
test before/after results.)
.SH METHODS
.TP
\-\-ff \f[I]ref\f[R], \-\-ff: \f[I]ref\f[R] \f[I]dest\f[R]
fast\-forward \f[I]dest\f[R] to match \f[I]ref\f[R].
If \f[I]dest\f[R] is not specified and \f[I]ref\f[R] names a save, set
\f[I]dest\f[R] to the save\(cqs branch.
If \f[I]dest\f[R] is not specified and \f[I]ref\f[R] names a branch or a
tag, use the same name for \f[I]dest\f[R].
.TP
\-\-append \f[I]ref\f[R], \-\-append: \f[I]ref\f[R] \f[I]dest\f[R]
append all of the commits represented by \f[I]ref\f[R] to \f[I]dest\f[R]
as new commits.
If \f[I]ref\f[R] names a directory/tree, append a new commit for that
tree.
If \f[I]dest\f[R] is not specified and \f[I]ref\f[R] names a save or
branch, set \f[I]dest\f[R] to the \f[I]ref\f[R] branch name.
If \f[I]dest\f[R] is not specified and \f[I]ref\f[R] names a tag, use
the same name for \f[I]dest\f[R].
.TP
\-\-pick \f[I]ref\f[R], \-\-pick: \f[I]ref\f[R] \f[I]dest\f[R]
append the single commit named by \f[I]ref\f[R] to \f[I]dest\f[R] as a
new commit.
If \f[I]dest\f[R] is not specified and \f[I]ref\f[R] names a save, set
\f[I]dest\f[R] to the \f[I]ref\f[R] branch name.
If \f[I]dest\f[R] is not specified and \f[I]ref\f[R] names a tag, use
the same name for \f[I]dest\f[R].
.TP
\-\-force\-pick \f[I]ref\f[R], \-\-force\-pick: \f[I]ref\f[R] \f[I]dest\f[R]
do the same thing as \f[CR]\-\-pick\f[R], but don\(cqt refuse to
overwrite an existing tag, and if the tag refers to a commit, make it
the parent of \f[I]ref\f[R].
.TP
\-\-new\-tag \f[I]ref\f[R], \-\-new\-tag: \f[I]ref\f[R] \f[I]dest\f[R]
create a \f[I]dest\f[R] tag for \f[I]ref\f[R], but refuse to overwrite
an existing tag.
If \f[I]dest\f[R] is not specified and \f[I]ref\f[R] names a tag, use
the same name for \f[I]dest\f[R].
.TP
\-\-replace \f[I]ref\f[R], \-\-replace: \f[I]ref\f[R] \f[I]dest\f[R]
clobber \f[I]dest\f[R] with \f[I]ref\f[R], overwriting any existing tag,
or replacing any existing branch.
If \f[I]dest\f[R] is not specified and \f[I]ref\f[R] names a branch or
tag, use the same name for \f[I]dest\f[R].
.TP
\-\-unnamed \f[I]ref\f[R]
copy \f[I]ref\f[R] into the destination repository, without any name,
leaving a potentially dangling reference until/unless the object named
by \f[I]ref\f[R] is referred to some other way
(cf.\ \f[CR]bup tag\f[R]).
Currently only compatible with \f[CR]\-\-copy\f[R].
.SH OPTIONS
.TP
\-s \f[I]path\f[R], \-S \f[I]url, \-\-source \f[R]path\f[I], \-\-source\-url \f[R]url*
use \f[I]path\f[R] or \f[I]url\f[R] as the source repository, instead of
the default.
See \f[CR]bup\f[R](1) REPOSITORY URLS for further information.
.TP
\-r, \-\-remote=[\f[I]user\f[R]\(at]\f[I]host\f[R]:[\f[I]path\f[R]], \-\-remote=URL
write the \f[I]ref\f[R]s to the specified remote repository, by default
via SSH.
See \f[CR]bup\f[R](1) REMOTE OPTIONS for further information.
.TP
\-c, \-\-print\-commits
for each updated branch, print the new git commit id.
.TP
\-t, \-\-print\-trees
for each updated branch, print the new git tree id of the filesystem
root.
.TP
\-\-print\-tags
for each updated tag, print the new git id.
.TP
\-\-copy
copy the data without changes (i.e.\ without rewrites or repairs).
This is the default.
.TP
\-\-rewrite
rewrite the data according to the destination repository configuration,
e.g.\ its \f[CR]bup.split.files\f[R], and \f[CR]bup.split.trees\f[R]
values.
Some incidental repairs may be performed during the transfer when they
do not materially alter the result (see REPAIRS below).
Currently, \f[CR]\-\-rewrite\f[R], \f[CR]\-\-\-repair\f[R], or
\f[CR]\-\-copy\f[R] must be specified whenever the source and
destination repository configurations differ in a relevant way, and so
far, \f[CR]\-\-rewrite\f[R] is only supported for appends and picks of
saves (e.g.\ not trees).
.RS
Note that rewriting a git\-created save may, and for now will, introduce
bup\-related changes.
Further, while tested, \f[CR]\-\-rewrite\f[R] is relatively new and so
warrants even more caution (see CAUTION above) than \f[CR]bup get\f[R]
itself.
Please consider validating the results carefully for now.
This option is contextual (see CONTEXTUAL OPTIONS).
.RE
.TP
\-\-repair
in addition to what \f[CR]\-\-rewrite\f[R] does, perform all known
repairs during the transfer.
See REPAIRS below.
This option is contextual (see CONTEXTUAL OPTIONS).
.TP
\-\-repair\-id ID
set the repair session identifier, defaults to a UUID (v4).
This identifier will be included in any \f[CR]\-\-repair\f[R]s made
during the transfer.
Currently, the identifier must be ASCII and must not include control
characters or DEL (i.e.\ must be comprised of bytes >= 20 and < 127).
This option is contextual (see CONTEXTUAL OPTIONS).
.TP
\-\-ignore\-missing
ignore missing objects encountered during a transfer.
Currently only supported by \f[CR]\-\-unnamed\f[R], and potentially
\f[I]dangerous\f[R].
.TP
\-\-exclude\-rx=\f[I]pattern\f[R]
exclude any path matching \f[I]pattern\f[R], which must be a Python
regular expression (http://docs.python.org/library/re.html).
The pattern will be compared against the full path, without anchoring,
so \(lqx/y\(rq will match \(lqox/yard\(rq or \(lqbox/yards\(rq.
To exclude the contents of /tmp, but not the directory itself, use
\(lq\(ha/tmp/.\(rq.
(may be repeated)
.RS
Examples:
.IP \(bu 2
\f[CR]/foo$\f[R] \- exclude any file named foo
.IP \(bu 2
\f[CR]/foo/$\f[R] \- exclude any directory named foo
.IP \(bu 2
\f[CR]/foo/.\f[R] \- exclude the content of any directory named foo
.IP \(bu 2
\f[CR]\(ha/tmp/.\f[R] \- exclude root\-level tmp\(cqs content
Only supported when rewriting or repairing.
This option is contextual (see CONTEXTUAL OPTIONS).
.RE
.TP
\-\-exclude\-rx\-from=\f[I]filename\f[R]
read \(enexclude\-rx patterns from \f[I]filename\f[R], one pattern
per\-line (may be repeated).
Ignore completely empty lines.
Only supported when rewriting.
This option is contextual (see CONTEXTUAL OPTIONS).
.TP
\-\-no\-excludes
forget any previous \f[CR]\-\-exclude\-rx\f[R] or
\f[CR]\-\-exclude\-rx\-from\f[R] options.
This option is contextual (see CONTEXTUAL OPTIONS).
.TP
\-v, \-\-verbose
increase verbosity (can be used more than once).
With \f[CR]\-v\f[R], print the name of every item fetched, with
\f[CR]\-vv\f[R] add directory names, and with \f[CR]\-vvv\f[R] add every
filename.
.TP
\-\-bwlimit=\f[I]bytes/sec\f[R]
don\(cqt transmit more than \f[I]bytes/sec\f[R] bytes per second to the
server.
This can help avoid sucking up all your network bandwidth.
Use a suffix like k, M, or G to specify multiples of 1024, 1024*1024,
1024*1024*1024 respectively.
.TP
\-\f[I]#\f[R], \-\-compress=\f[I]#\f[R]
set the compression level to # (a value from 0\-9, where 9 is the
highest and 0 is no compression).
Defaults to a configured pack.compression or core.compression, or 1
(fast, loose compression).
.SH CONTEXTUAL OPTIONS
Some options like \f[CR]\-\-repair\f[R] and
\f[CR]\-\-ignore\-missing\f[R] can differ across METHODs, and each
option changes the context for the next METHOD.
So you can have
.IP
.EX
bup get ... \-\-ignore\-missing \-\-unnamed REF \(rs
    \-\-no\-ignore\-missing \-\-rewrite \-\-append REF
.EE
.PP
Without \f[CR]\-\-no\-ignore\-missing\f[R] this command would fail
because \f[CR]\-\-ignore\-missing\f[R] is incompatible with
\f[CR]\-\-rewrite\f[R].
.PP
Changing the currently active excludes is expensive because at the
moment the cache of remembered rewrites must be cleared whenever a
METHODs excludes differ from those for the previous METHOD.
.SH REPAIRS
\f[CR]bup get\f[R] can fix (or mitigate) a number of known issues during
the transfer when \f[CR]\-\-repair\f[R] is requested, and a subset of
\(lqincidental\(rq repairs may also be performed during a
\f[CR]\-\-rewrite\f[R].
.IP \(bu 2
Versions of \f[CR]bup\f[R] at or after 0.25 and before 0.30.1 might
rarely drop metadata entries for non\-directories (which can be detected
by \f[CR]bup\-validate\-refs\f[R](1) \f[CR]\-\-bupm\f[R]).
This makes the metadata for all of the other non\-directory paths in the
same directory unusable (ambiguous).
When such an abridged \f[CR].bupm\f[R] is detected,
\f[CR]\-\-repair\f[R] drops all of the \f[CR].bupm\f[R] entries except
the one for the directory itself, \(lq.\(rq, and so the affected paths
lose most or all of their metadata (ownership, permissions, timestamps,
etc.).
These paths will have restrictive permissions (as if via umask 077) when
presented, e.g.\ via \f[CR]bup\-restore(1)\f[R], \f[CR]bup\-ls(1)\f[R],
etc.
.IP \(bu 2
Use of \f[CR]bup get\f[R] or \f[CR]bup gc\f[R] versions before 0.33.5
could cause repositories to end up with missing objects (which can be
detected by \f[CR]bup\-validate\-object\-links\f[R](1)).
To fix affected trees, \f[CR]\-\-repair\f[R] substitutes synthesized
\(lqrepair files\(rq for any paths with missing objects.
Note that there is currently no support for retrieving the unaffected
parts of split files; the entire file is replaced with a repair file.
These repair files contain the \f[CR]\-\-repair\-id\f[R] and information
about the replacement.
Support for split trees was added after the problem was fixed, and so
should be unaffected.
See the \c
.UR https://github.com/bup/bup/blob/main/note/0.33.5-from-0.33.4.md
0.33.5 release notes (0.33.5\-from\-0.33.4.md)
.UE \c
\ for additional information.
.PP
\(lqIncidental\(rq repairs may also be performed \(em repairs that do
not functionally alter the result.
For example, bup records symlink targets in two places, but generally
only refers to one of them.
If the other one is missing, it can and will be restored from the first.
.SH EXAMPLES
.IP
.EX
# Update or copy the archives branch in src\-repo to the local repository.
$ bup get \-s src\-repo \-\-ff archives

# Append a particular archives save to the pruned\-archives branch.
$ bup get \-s src\-repo \-\-pick: archives/2013\-01\-01\-030405 pruned\-archives

# Update or copy the archives branch on remotehost to the local
# repository.
$ bup on remotehost get \-\-ff archives

# Update or copy the local branch archives to remotehost.
$ bup get \-r remotehost: \-\-ff archives

# Update or copy the archives branch in src\-repo to remotehost.
$ bup get \-s src\-repo \-r remotehost: \-\-ff archives

# Update the archives\-2 branch on remotehost to match archives.
# If archives\-2 exists and is not an ancestor of archives, bup
# will refuse.
$ bup get \-r remotehost: \-\-ff: archives archives\-2

# Replace the contents of branch y with those of x.
$ bup get \-\-replace: x y

# Copy the latest local save from the archives branch to the
# remote tag foo.
$ bup get \-r remotehost: \-\-pick: archives/latest .tag/foo

# Or if foo already exists:
$ bup get \-r remotehost: \-\-force\-pick: archives/latest .tag/foo

# Append foo (from above) to the local other\-archives branch.
$ bup on remotehost get \-\-append: .tag/foo other\-archives

# Append only the /home directory from archives/latest to only\-home.
$ bup get \-s \(dq$BUP_DIR\(dq \-\-append: archives/latest/home only\-home

# Resplit (rewrite) the archives branch. Note that, done all at
# once, this may require additional space up to the size of the
# archives branch. The pick methods can do the rewriting more
# selectively or incrementally. (Assume BUP_DIR has no split
# settings.)
#
$ git \-\-git\-dir \(dq$BUP_DIR\(dq config bup.split.trees true
$ git \-\-git\-dir \(dq$BUP_DIR\(dq config bup.split.files legacy:16
$ bup get \-\-rewrite \-\-append: archives archives\-resplit
#
# Check that archives\-resplit looks OK, perhaps via trial
# restores, joining it, etc. (see CAUTION above), and once
# satisfied, perhaps...
#
$ bup rm archives
$ bup gc
$ git \-\-git\-dir \(dq$BUP_DIR\(dq branch \-m archives\-resplit archives
#
# Repair a single save.
$ bup get \-\-repair \-\-pick archives/latest fixed
#
# Check that fixed/latest looks OK, perhaps via trial
# restores, joining it, etc. (see CAUTION above).
.EE
.SH EXIT STATUS
An exit status of 3 indicates that repairs were needed and were
successful, and that no other errors occurred.
.SH SEE ALSO
\f[CR]bup\-on\f[R](1), \f[CR]bup\-tag\f[R](1), \f[CR]ssh_config\f[R](5)
.SH BUP
Part of the \f[CR]bup\f[R](1) suite.
.SH AUTHORS
Rob Browning \c
.MT rlb@defaultvalue.org
.ME \c.