| 1 |
% bup-get(1) Bup %BUP_VERSION% |
| 2 |
% Rob Browning <[email protected]> |
| 3 |
% %BUP_DATE% |
| 4 |
|
| 5 |
# NAME |
| 6 |
|
| 7 |
bup-get - copy repository items (CAUTION: EXPERIMENTAL) |
| 8 |
|
| 9 |
# SYNOPSIS |
| 10 |
|
| 11 |
bup get \[-s *source-path*\] \[-r *host*:*path*\] OPTIONS \<(METHOD *ref* [*dest*])\>... |
| 12 |
|
| 13 |
# DESCRIPTION |
| 14 |
|
| 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. |
| 21 |
|
| 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. |
| 25 |
For example: |
| 26 |
|
| 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 |
| 30 |
|
| 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`. |
| 36 |
|
| 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 |
| 40 |
source). |
| 41 |
|
| 42 |
An existing destination tag can only be overwritten by a `--replace` |
| 43 |
or `--force-pick`. |
| 44 |
|
| 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 |
| 48 |
and time. |
| 49 |
|
| 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. |
| 53 |
|
| 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 |
| 57 |
further information. |
| 58 |
|
| 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.) |
| 65 |
|
| 66 |
# METHODS |
| 67 |
|
| 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 |
| 72 |
same name for *dest*. |
| 73 |
|
| 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*. |
| 80 |
|
| 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*. |
| 86 |
|
| 87 |
\--force-pick *ref*, \--force-pick: *ref* *dest* |
| 88 |
: do the same thing as `--pick`, but don't refuse to overwrite an |
| 89 |
existing tag, and if the tag refers to a commit, make it the |
| 90 |
parent of *ref*. |
| 91 |
|
| 92 |
\--new-tag *ref*, \--new-tag: *ref* *dest* |
| 93 |
: create a *dest* tag for *ref*, but refuse to overwrite an existing |
| 94 |
tag. If *dest* is not specified and *ref* names a tag, use the |
| 95 |
same name for *dest*. |
| 96 |
|
| 97 |
\--replace *ref*, \--replace: *ref* *dest* |
| 98 |
: clobber *dest* with *ref*, overwriting any existing tag, or |
| 99 |
replacing any existing branch. If *dest* is not specified and |
| 100 |
*ref* names a branch or tag, use the same name for *dest*. |
| 101 |
|
| 102 |
\--unnamed *ref* |
| 103 |
: copy *ref* into the destination repository, without any name, |
| 104 |
leaving a potentially dangling reference until/unless the object |
| 105 |
named by *ref* is referred to some other way (cf. `bup tag`). |
| 106 |
|
| 107 |
# OPTIONS |
| 108 |
|
| 109 |
-s, \--source=*path* |
| 110 |
: use *path* as the source repository, instead of the default. |
| 111 |
|
| 112 |
-r, \--remote=*host*:*path* |
| 113 |
: store the indicated items on the given remote server. If *path* |
| 114 |
is omitted, uses the default path on the remote server (you still |
| 115 |
need to include the ':'). The connection to the remote server is |
| 116 |
made with SSH. If you'd like to specify which port, user or |
| 117 |
private key to use for the SSH connection, we recommend you use |
| 118 |
the `~/.ssh/config` file. |
| 119 |
|
| 120 |
-c, \--print-commits |
| 121 |
: for each updated branch, print the new git commit id. |
| 122 |
|
| 123 |
-t, \--print-trees |
| 124 |
: for each updated branch, print the new git tree id of the |
| 125 |
filesystem root. |
| 126 |
|
| 127 |
\--print-tags |
| 128 |
: for each updated tag, print the new git id. |
| 129 |
|
| 130 |
-v, \--verbose |
| 131 |
: increase verbosity (can be used more than once). With |
| 132 |
`-v`, print the name of every item fetched, with `-vv` add |
| 133 |
directory names, and with `-vvv` add every filename. |
| 134 |
|
| 135 |
\--bwlimit=*bytes/sec* |
| 136 |
: don't transmit more than *bytes/sec* bytes per second to the |
| 137 |
server. This can help avoid sucking up all your network |
| 138 |
bandwidth. Use a suffix like k, M, or G to specify multiples of |
| 139 |
1024, 1024\*1024, 1024\*1024\*1024 respectively. |
| 140 |
|
| 141 |
-*#*, \--compress=*#* |
| 142 |
: set the compression level to # (a value from 0-9, where |
| 143 |
9 is the highest and 0 is no compression). The default |
| 144 |
is 1 (fast, loose compression) |
| 145 |
|
| 146 |
\--ignore-missing |
| 147 |
: ignore missing objects encountered during a transfer. Currently |
| 148 |
only supported by `--unnamed`, and potentially *dangerous*. |
| 149 |
|
| 150 |
# EXAMPLES |
| 151 |
|
| 152 |
# Update or copy the archives branch in src-repo to the local repository. |
| 153 |
$ bup get -s src-repo --ff archives |
| 154 |
|
| 155 |
# Append a particular archives save to the pruned-archives branch. |
| 156 |
$ bup get -s src-repo --pick: archives/2013-01-01-030405 pruned-archives |
| 157 |
|
| 158 |
# Update or copy the archives branch on remotehost to the local |
| 159 |
# repository. |
| 160 |
$ bup on remotehost get --ff archives |
| 161 |
|
| 162 |
# Update or copy the local branch archives to remotehost. |
| 163 |
$ bup get -r remotehost: --ff archives |
| 164 |
|
| 165 |
# Update or copy the archives branch in src-repo to remotehost. |
| 166 |
$ bup get -s src-repo -r remotehost: --ff archives |
| 167 |
|
| 168 |
# Update the archives-2 branch on remotehost to match archives. |
| 169 |
# If archives-2 exists and is not an ancestor of archives, bup |
| 170 |
# will refuse. |
| 171 |
$ bup get -r remotehost: --ff: archives archives-2 |
| 172 |
|
| 173 |
# Replace the contents of branch y with those of x. |
| 174 |
$ bup get --replace: x y |
| 175 |
|
| 176 |
# Copy the latest local save from the archives branch to the |
| 177 |
# remote tag foo. |
| 178 |
$ bup get -r remotehost: --pick: archives/latest .tag/foo |
| 179 |
|
| 180 |
# Or if foo already exists: |
| 181 |
$ bup get -r remotehost: --force-pick: archives/latest .tag/foo |
| 182 |
|
| 183 |
# Append foo (from above) to the local other-archives branch. |
| 184 |
$ bup on remotehost get --append: .tag/foo other-archives |
| 185 |
|
| 186 |
# Append only the /home directory from archives/latest to only-home. |
| 187 |
$ bup get -s "$BUP_DIR" --append: archives/latest/home only-home |
| 188 |
|
| 189 |
# SEE ALSO |
| 190 |
|
| 191 |
`bup-on`(1), `bup-tag`(1), `ssh_config`(5) |
| 192 |
|
| 193 |
# BUP |
| 194 |
|
| 195 |
Part of the `bup`(1) suite. |