Documentation/bup-save.md

   1 % bup-save(1) Bup %BUP_VERSION%
   2 % Avery Pennarun <apenwarr@gmail.com>
   3 % %BUP_DATE%
   4
   5 # NAME
   6
   7 bup-save - create a new bup backup set
   8
   9 # SYNOPSIS
  10
  11 bup save [-r *host*:*path*] \<-t|-c|-n *name*\> [-#] [-f *indexfile*]
  12 [-v] [-q] [\--smaller=*maxsize*] \<paths...\>;
  13
  14 # DESCRIPTION
  15
  16 `bup save` saves the contents of the given files or paths
  17 into a new backup set and optionally names that backup set.
  18
  19 Before trying to save files using `bup save`, you should
  20 first update the index using `bup index`.  The reasons
  21 for separating the two steps are described in the man page
  22 for `bup-index`(1).
  23
  24 By default, metadata will be saved for every path.  However, if
  25 `--strip`, `--strip-path`, or `--graft` is specified, metadata will
  26 not be saved for the root directory (*/*).  See `bup-restore`(1) for
  27 more information about the handling of metadata.
  28
  29 # OPTIONS
  30
  31 -r, \--remote=*host*:*path*
  32 :   save the backup set to the given remote server.  If
  33     *path* is omitted, uses the default path on the remote
  34     server (you still need to include the ':').  The connection to the
  35     remote server is made with SSH.  If you'd like to specify which port, user
  36     or private key to use for the SSH connection, we recommend you use the
  37     `~/.ssh/config` file.
  38
  39 -t, \--tree
  40 :   after creating the backup set, print out the git tree
  41     id of the resulting backup.
  42
  43 -c, \--commit
  44 :   after creating the backup set, print out the git commit
  45     id of the resulting backup.
  46
  47 -n, \--name=*name*
  48 :   after creating the backup set, create a git branch
  49     named *name* so that the backup can be accessed using
  50     that name.  If *name* already exists, the new backup
  51     will be considered a descendant of the old *name*.
  52     (Thus, you can continually create new backup sets with
  53     the same name, and later view the history of that
  54     backup set to see how files have changed over time.)
  55
  56 -d, \--date=*date*
  57 :   specify the date of the backup, in seconds since the epoch, instead
  58     of the current time.
  59
  60 -f, \--indexfile=*indexfile*
  61 :   use a different index filename instead of
  62     `~/.bup/bupindex`.
  63
  64 -v, \--verbose
  65 :   increase verbosity (can be used more than once).  With
  66     one -v, prints every directory name as it gets backed up.  With
  67     two -v, also prints every filename.
  68
  69 -q, \--quiet
  70 :   disable progress messages.
  71
  72 \--smaller=*maxsize*
  73 :   don't back up files >= *maxsize* bytes.  You can use
  74     this to run frequent incremental backups of your small
  75     files, which can usually be backed up quickly, and skip
  76     over large ones (like virtual machine images) which
  77     take longer.  Then you can back up the large files
  78     less frequently.  Use a suffix like k, M, or G to
  79     specify multiples of 1024, 1024*1024, 1024*1024*1024
  80     respectively.
  81
  82 \--bwlimit=*bytes/sec*
  83 :   don't transmit more than *bytes/sec* bytes per second
  84     to the server.  This is good for making your backups
  85     not suck up all your network bandwidth.  Use a suffix
  86     like k, M, or G to specify multiples of 1024,
  87     1024*1024, 1024*1024*1024 respectively.
  88
  89 \--strip
  90 :   strips the path that is given from all files and directories.
  91
  92     A directory */root/chroot/etc* saved with "bup save -n chroot
  93     \--strip /root/chroot" would be saved as */etc*.  Note that
  94     currently, metadata will not be saved for the root directory (*/*)
  95     when this option is specified.
  96
  97 \--strip-path=*path-prefix*
  98 :   strips the given path prefix *path-prefix* from all
  99     files and directories.
 100
 101     A directory */root/chroots/webserver* saved with "bup save -n
 102     webserver \--strip-path=/root/chroots" would be saved as
 103     */webserver/etc*.  Note that currently, metadata will not be saved
 104     for the root directory (*/*) when this option is specified.
 105
 106 \--graft=*old_path*=*new_path*
 107 :   a graft point *old_path*=*new_path* (can be used more than
 108     once).
 109
 110     A directory */root/chroot/a/etc* saved with "bup save -n chroots
 111     \--graft /root/chroot/a/etc=/chroots/a" would be saved as
 112     */chroots/a/etc*.  Note that currently, metadata will not be saved
 113     for the root directory (*/*) when this option is specified.
 114
 115 -*#*, \--compress=*#*
 116 :   set the compression level to # (a value from 0-9, where
 117     9 is the highest and 0 is no compression).  The default
 118     is 1 (fast, loose compression)
 119
 120
 121 # EXAMPLE
 122
 123     $ bup index -ux /etc
 124     Indexing: 1981, done.
 125
 126     $ bup save -r myserver: -n my-pc-backup --bwlimit=50k /etc
 127     Reading index: 1981, done.
 128     Saving: 100.00% (998/998k, 1981/1981 files), done.
 129
 130
 131
 132     $ ls /home/joe/chroots/httpd
 133     bin var
 134
 135     $ bup index -ux /home/joe/chroots/httpd
 136     Indexing: 1337, done.
 137
 138     $ bup save --strip -n joes-httpd-chroot /home/joe/chroots/httpd
 139     Reading index: 1337, done.
 140     Saving: 100.00% (998/998k, 1337/1337 files), done.
 141
 142     $ bup ls joes-httpd-chroot/latest/
 143     bin/
 144     var/
 145
 146
 147     $ bup save --strip-path=/home/joe/chroots -n joes-chroots \
 148          /home/joe/chroots/httpd
 149     Reading index: 1337, done.
 150     Saving: 100.00% (998/998k, 1337/1337 files), done.
 151
 152     $ bup ls joes-chroots/latest/
 153     httpd/
 154
 155
 156     $ bup save --graft /home/joe/chroots/httpd=/http-chroot \
 157          -n joe
 158          /home/joe/chroots/httpd
 159     Reading index: 1337, done.
 160     Saving: 100.00% (998/998k, 1337/1337 files), done.
 161
 162     $ bup ls joe/latest/
 163     http-chroot/
 164
 165
 166 # SEE ALSO
 167
 168 `bup-index`(1), `bup-split`(1), `bup-on`(1),
 169 `bup-restore`(1), `ssh_config`(5)
 170
 171 # BUP
 172
 173 Part of the `bup`(1) suite.