Debian Codegraph @

Documentation/man3/man9/man7/man4/man2/man2/bup-get.1.md

raw
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.