Documentation/bup-get.md

   1 % bup-get(1) Bup %BUP_VERSION%
   2 % Rob Browning <rlb@defaultvalue.org>
   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 t/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.
  90
  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
  94     same name for *dest*.
  95
  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*.
 100
 101 \--unnamed *ref*
 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`).
 105
 106 # OPTIONS
 107
 108 -s, \--source=*path*
 109 :   use *path* as the source repository, instead of the default.
 110
 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.
 118
 119 -c, \--print-commits
 120 :   for each updated branch, print the new git commit id.
 121
 122 -t, \--print-trees
 123 :   for each updated branch, print the new git tree id of the
 124     filesystem root.
 125
 126 \--print-tags
 127 :   for each updated tag, print the new git id.
 128
 129 -v, \--verbose
 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.
 133
 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.
 139
 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)
 144
 145 # EXAMPLES
 146
 147     # Update or copy the archives branch in src-repo to the local repository.
 148     $ bup get -s src-repo --ff archives
 149
 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
 152
 153     # Update or copy the archives branch on remotehost to the local
 154     # repository.
 155     $ bup on remotehost get --ff archives
 156
 157     # Update or copy the local branch archives to remotehost.
 158     $ bup get -r remotehost: --ff archives
 159
 160     # Update or copy the archives branch in src-repo to remotehost.
 161     $ bup get -s src-repo -r remotehost: --ff archives
 162
 163     # Update the archives-2 branch on remotehost to match archives.
 164     # If archives-2 exists and is not an ancestor of archives, bup
 165     # will refuse.
 166     $ bup get -r remotehost: --ff: archives archives-2
 167
 168     # Replace the contents of branch y with those of x.
 169     $ bup get --replace: x y
 170
 171     # Copy the latest local save from the archives branch to the
 172     # remote tag foo.
 173     $ bup get -r remotehost: --pick: archives/latest .tag/foo
 174
 175     # Or if foo already exists:
 176     $ bup get -r remotehost: --force-pick: archives/latest .tag/foo
 177
 178     # Append foo (from above) to the local other-archives branch.
 179     $ bup on remotehost get --append: .tag/foo other-archives
 180
 181     # Append only the /home directory from archives/latest to only-home.
 182     $ bup get -s "$BUP_DIR" --append: archives/latest/home only-home
 183
 184 # SEE ALSO
 185
 186 `bup-on`(1), `bup-tag`(1), `ssh_config`(5)
 187
 188 # BUP
 189
 190 Part of the `bup`(1) suite.