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/etc* saved with "bup save -n
 108     webserver \--strip-path=/root/chroot /root/chroot/webserver/etc"
 109     would be saved as */webserver/etc*.  Note that currently, metadata
 110     will not be saved for the root directory (*/*) when this option is
 111     specified.
 112
 113 \--graft=*old_path*=*new_path*
 114 :   a graft point *old_path*=*new_path* (can be used more than
 115     once).
 116
 117     A directory */root/chroot/a/etc* saved with "bup save -n chroot
 118     \--graft /root/chroot/a=/chroot/a" would be saved as
 119     */chroot/a/etc*.  Note that currently, metadata will not be saved
 120     for the root directory (*/*) when this option is specified.
 121
 122 -*#*, \--compress=*#*
 123 :   set the compression level to # (a value from 0-9, where
 124     9 is the highest and 0 is no compression).  The default
 125     is 1 (fast, loose compression)
 126
 127
 128 # EXAMPLES
 129     $ bup index -ux /etc
 130     Indexing: 1981, done.
 131
 132     $ bup save -r myserver: -n my-pc-backup --bwlimit=50k /etc
 133     Reading index: 1981, done.
 134     Saving: 100.00% (998/998k, 1981/1981 files), done.
 135
 136
 137
 138     $ ls /home/joe/chroot/httpd
 139     bin var
 140
 141     $ bup index -ux /home/joe/chroot/httpd
 142     Indexing: 1337, done.
 143
 144     $ bup save --strip -n joes-httpd-chroot /home/joe/chroot/httpd
 145     Reading index: 1337, done.
 146     Saving: 100.00% (998/998k, 1337/1337 files), done.
 147
 148     $ bup ls joes-httpd-chroot/latest/
 149     bin/
 150     var/
 151
 152
 153     $ bup save --strip-path=/home/joe/chroot -n joes-chroot \
 154          /home/joe/chroot/httpd
 155     Reading index: 1337, done.
 156     Saving: 100.00% (998/998k, 1337/1337 files), done.
 157
 158     $ bup ls joes-chroot/latest/
 159     httpd/
 160
 161
 162     $ bup save --graft /home/joe/chroot/httpd=/http-chroot \
 163          -n joe
 164          /home/joe/chroot/httpd
 165     Reading index: 1337, done.
 166     Saving: 100.00% (998/998k, 1337/1337 files), done.
 167
 168     $ bup ls joe/latest/
 169     http-chroot/
 170
 171
 172 # SEE ALSO
 173
 174 `bup-index`(1), `bup-split`(1), `bup-on`(1),
 175 `bup-restore`(1), `ssh_config`(5)
 176
 177 # BUP
 178
 179 Part of the `bup`(1) suite.