1 % bup-get(1) Bup %BUP_VERSION%
2 % Rob Browning <rlb@defaultvalue.org>
7 bup-get - copy repository items (CAUTION: EXPERIMENTAL)
11 bup get \[-s *source-path*\] \[-r *host*:*path*\] OPTIONS \<(METHOD *ref* [*dest*])\>...
15 `bup get` copies the indicated *ref*s from the source repository to
16 the destination repository (respecting `--bup-dir` and `BUP_DIR`),
17 according to the specified METHOD, which may be one of `--ff`,
18 `--ff:`, `--append`, `--append:`, `--pick`, `--pick:`, `--force-pick`,
19 `--force-pick:`, `--new-tag`, `--new-tag:`, `--replace`, `--replace:`,
20 or `--unnamed`. See the EXAMPLES below for a quick introduction.
22 The *ref* is the source repository reference of the object to be
23 fetched, and the *dest* is the optional destination reference. A
24 *dest* may only be specified for a METHOD whose name ends in a colon.
27 bup get -s /source/repo --ff foo
28 bup get -s /source/repo --ff: foo/latest bar
29 bup get -s /source/repo --pick: foo/2010-10-10-101010 .tag/bar
31 As a special case, if *ref* names the "latest" save symlink, then bup
32 will act exactly as if the save that "latest" points to had been
33 specified, rather than the "latest" symlink itself, so `bup get
34 foo/latest` will actually be interpreted as something like `bup get
35 foo/2013-01-01-030405`.
37 In some situations `bup get` will evaluate a branch operation
38 according to whether or not it will be a "fast-forward" (which
39 requires that any existing destination branch be an ancestor of the
42 An existing destination tag can only be overwritten by a `--replace`
45 When a new commit is created (i.e. via `--append`, `--pick`, etc.), it
46 will have the same author, author date, and message as the original,
47 but a committer and committer date corresponding to the current user
50 If requested by the appropriate options, bup will print the commit,
51 tree, or tag hash for each destination reference updated. When
52 relevant, the tree hash will be printed before the commit hash.
54 Local *ref*s can be pushed to a remote repository with the `--remote`
55 option, and remote *ref*s can be pulled into a local repository via
56 "bup on HOST get ...". See `bup-on`(1) and the EXAMPLES below for
59 WARNING: This is one of the few bup commands that can modify your
60 archives in intentionally destructive ways. Though if an attempt to
61 join or restore the data you still care about succeeds after you've
62 run this command, then that's a fairly encouraging sign that it worked
63 correctly. (The dev/compare-trees command in the source tree can be
64 used to help test before/after results.)
68 \--ff *ref*, \--ff: *ref* *dest*
69 : fast-forward *dest* to match *ref*. If *dest* is not specified
70 and *ref* names a save, set *dest* to the save's branch. If
71 *dest* is not specified and *ref* names a branch or a tag, use the
74 \--append *ref*, \--append: *ref* *dest*
75 : append all of the commits represented by *ref* to *dest* as new
76 commits. If *ref* names a directory/tree, append a new commit for
77 that tree. If *dest* is not specified and *ref* names a save or
78 branch, set *dest* to the *ref* branch name. If *dest* is not
79 specified and *ref* names a tag, use the same name for *dest*.
81 \--pick *ref*, \--pick: *ref* *dest*
82 : append the single commit named by *ref* to *dest* as a new commit.
83 If *dest* is not specified and *ref* names a save, set *dest* to
84 the *ref* branch name. If *dest* is not specified and *ref* names
85 a tag, use the same name for *dest*.
87 \--force-pick *ref*, \--force-pick: *ref* *dest*
88 : do the same thing as `--pick`, but don't refuse to overwrite an
91 \--new-tag *ref*, \--new-tag: *ref* *dest*
92 : create a *dest* tag for *ref*, but refuse to overwrite an existing
93 tag. If *dest* is not specified and *ref* names a tag, use the
96 \--replace *ref*, \--replace: *ref* *dest*
97 : clobber *dest* with *ref*, overwriting any existing tag, or
98 replacing any existing branch. If *dest* is not specified and
99 *ref* names a branch or tag, use the same name for *dest*.
102 : copy *ref* into the destination repository, without any name,
103 leaving a potentially dangling reference until/unless the object
104 named by *ref* is referred to some other way (cf. `bup tag`).
109 : use *path* as the source repository, instead of the default.
111 -r, \--remote=*host*:*path*
112 : store the indicated items on the given remote server. If *path*
113 is omitted, uses the default path on the remote server (you still
114 need to include the ':'). The connection to the remote server is
115 made with SSH. If you'd like to specify which port, user or
116 private key to use for the SSH connection, we recommend you use
117 the `~/.ssh/config` file.
120 : for each updated branch, print the new git commit id.
123 : for each updated branch, print the new git tree id of the
127 : for each updated tag, print the new git id.
130 : increase verbosity (can be used more than once). With
131 `-v`, print the name of every item fetched, with `-vv` add
132 directory names, and with `-vvv` add every filename.
134 \--bwlimit=*bytes/sec*
135 : don't transmit more than *bytes/sec* bytes per second to the
136 server. This can help avoid sucking up all your network
137 bandwidth. Use a suffix like k, M, or G to specify multiples of
138 1024, 1024\*1024, 1024\*1024\*1024 respectively.
140 -*#*, \--compress=*#*
141 : set the compression level to # (a value from 0-9, where
142 9 is the highest and 0 is no compression). The default
143 is 1 (fast, loose compression)
147 # Update or copy the archives branch in src-repo to the local repository.
148 $ bup get -s src-repo --ff archives
150 # Append a particular archives save to the pruned-archives branch.
151 $ bup get -s src-repo --pick: archives/2013-01-01-030405 pruned-archives
153 # Update or copy the archives branch on remotehost to the local
155 $ bup on remotehost get --ff archives
157 # Update or copy the local branch archives to remotehost.
158 $ bup get -r remotehost: --ff archives
160 # Update or copy the archives branch in src-repo to remotehost.
161 $ bup get -s src-repo -r remotehost: --ff archives
163 # Update the archives-2 branch on remotehost to match archives.
164 # If archives-2 exists and is not an ancestor of archives, bup
166 $ bup get -r remotehost: --ff: archives archives-2
168 # Replace the contents of branch y with those of x.
169 $ bup get --replace: x y
171 # Copy the latest local save from the archives branch to the
173 $ bup get -r remotehost: --pick: archives/latest .tag/foo
175 # Or if foo already exists:
176 $ bup get -r remotehost: --force-pick: archives/latest .tag/foo
178 # Append foo (from above) to the local other-archives branch.
179 $ bup on remotehost get --append: .tag/foo other-archives
181 # Append only the /home directory from archives/latest to only-home.
182 $ bup get -s "$BUP_DIR" --append: archives/latest/home only-home
186 `bup-on`(1), `bup-tag`(1), `ssh_config`(5)
190 Part of the `bup`(1) suite.