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