Reasons you might want to avoid bup
-----------------------------------
- - This is a very early version. Therefore it will most probably not work
- for you, but we don't know why. It is also missing some
- probably-critical features.
+ - It's not remotely as well tested as something like tar, so it's
+ more likely to eat your data. It's also missing some
+ probably-critical features, though fewer than it used to be.
- - It requires python >= 2.5, a C compiler, and an installed git
- version >= 1.5.3.1. It also requires par2 if you want fsck to be
+ - It requires python >= 2.6, a C compiler, and an installed git
+ version >= 1.5.6. It also requires par2 if you want fsck to be
able to generate the information needed to recover from some types
of corruption.
- - It currently only works on Linux, MacOS X >= 10.4,
- NetBSD, Solaris, or Windows (with Cygwin). Patches to support
- other platforms are welcome.
+ - It currently only works on Linux, FreeBSD, NetBSD, OS X >= 10.4,
+ Solaris, or Windows (with Cygwin, and maybe with WSL). Patches to
+ support other platforms are welcome.
- Any items in "Things that are stupid" below.
-
+
+Notable changes introduced by a release
+=======================================
+
+ - <a href="note/0.30-from-0.29.3.md">Changes in 0.30 as compared to 0.29.3</a>
+ - <a href="note/0.29.3-from-0.29.2.md">Changes in 0.29.3 as compared to 0.29.2</a>
+ - <a href="note/0.29.2-from-0.29.1.md">Changes in 0.29.2 as compared to 0.29.1</a>
+ - <a href="note/0.29.1-from-0.29.md">Changes in 0.29.1 as compared to 0.29</a>
+ - <a href="note/0.29-from-0.28.1.md">Changes in 0.29 as compared to 0.28.1</a>
+ - <a href="note/0.28.1-from-0.28.md">Changes in 0.28.1 as compared to 0.28</a>
+ - <a href="note/0.28-from-0.27.1.md">Changes in 0.28 as compared to 0.27.1</a>
+ - <a href="note/0.27.1-from-0.27.md">Changes in 0.27.1 as compared to 0.27</a>
+
+
+Test status
+===========
+
+| branch | Debian | FreeBSD | macOS |
+|--------|------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------|
+| master | [![Debian test status](https://api.cirrus-ci.com/github/bup/bup.svg?branch=master&task=debian)](https://cirrus-ci.com/github/bup/bup) | [![FreeBSD test status](https://api.cirrus-ci.com/github/bup/bup.svg?branch=master&task=freebsd)](https://cirrus-ci.com/github/bup/bup) | [![macOS test status](https://api.cirrus-ci.com/github/bup/bup.svg?branch=master&task=macos)](https://cirrus-ci.com/github/bup/bup) |
+| 0.29.x | [![Debian test status](https://api.cirrus-ci.com/github/bup/bup.svg?branch=0.29.x&task=debian)](https://cirrus-ci.com/github/bup/bup) | [![FreeBSD test status](https://api.cirrus-ci.com/github/bup/bup.svg?branch=0.29.x&task=freebsd)](https://cirrus-ci.com/github/bup/bup) | [![macOS test status](https://api.cirrus-ci.com/github/bup/bup.svg?branch=0.29.x&task=macos)](https://cirrus-ci.com/github/bup/bup) |
+
Getting started
===============
-
From source
-----------
- Check out the bup source code using git:
- git clone git://github.com/bup/bup
+ git clone https://github.com/bup/bup
+
+ - This will leave you on the master branch, which is perfect if you
+ would like to help with development, but if you'd just like to use
+ bup, please check out the latest stable release like this:
+
+ git checkout 0.29.1
+
+ You can see the latest stable release here:
+ https://github.com/bup/bup/releases.
- Install the required python libraries (including the development
libraries).
apt-get build-dep bup
- Otherwise try this (substitute python2.5-dev or python2.6-dev if
- you have an older system):
+ Otherwise try this (substitute python2.6-dev if you have an older
+ system):
apt-get install python2.7-dev python-fuse
apt-get install python-pyxattr python-pylibacl
- Run the tests:
- make test
+ make long-check
+
+ or if you're in a bit more of a hurry:
+
+ make check
- (The tests should pass. If they don't pass for you, stop here and send
- an email to bup-list@googlegroups.com.)
+ The tests should pass. If they don't pass for you, stop here and
+ send an email to bup-list@googlegroups.com. Though if there are
+ symbolic links along the current working directory path, the tests
+ may fail. Running something like this before "make test" should
+ sidestep the problem:
+
+ cd "$(pwd -P)"
- You can install bup via "make install", and override the default
destination with DESTDIR and PREFIX.
Files are normally installed to "$DESTDIR/$PREFIX" where DESTDIR is
- empty by default, and PREFIX is set to /usr. So if you wanted to
+ empty by default, and PREFIX is set to /usr/local. So if you wanted to
install bup to /opt/bup, you might do something like this:
make install DESTDIR=/opt/bup PREFIX=''
+ - The Python executable that bup will use is chosen by ./configure,
+ which will search for a reasonable version unless PYTHON is set in
+ the environment, in which case, bup will use that path. You can
+ see which Python executable was chosen by looking at the
+ configure output, or examining cmd/python-cmd.sh, and you can
+ change the selection by re-running ./configure.
From binary packages
--------------------
http://cvsweb.netbsd.org/bsdweb.cgi/pkgsrc/sysutils/bup/
- Arch Linux:
https://www.archlinux.org/packages/?sort=&q=bup
+ - Fedora:
+ https://apps.fedoraproject.org/packages/bup
Using bup
bup help restore
...
- - Initialize the default BUP_DIR (~/.bup):
+ - Initialize the default BUP_DIR (~/.bup -- you can choose another by
+ either specifying `bup -d DIR ...` or setting the `BUP_DIR`
+ environment variable for a command):
bup init
bup restore -C ./dest-2 local-etc/2013-11-23-11195/etc
- - Make a backup on a remote server (which must already have the 'bup' command
- somewhere in the server's PATH (see /etc/profile, etc/environment,
- ~/.profile, or ~/.bashrc), and be accessible via ssh.
- Make sure to replace SERVERNAME with the actual hostname of your server):
+ - Make a backup to a remote server which must already have the 'bup' command
+ somewhere in its PATH (see /etc/profile, etc/environment, ~/.profile, or
+ ~/.bashrc), and be accessible via ssh.
+ Make sure to replace SERVERNAME with the actual hostname of your server:
- ssh SERVERNAME bup init
+ bup init -r SERVERNAME:path/to/remote-bup-dir
bup index /etc
- bup save -r SERVERNAME: -n local-etc /etc
+ bup save -r SERVERNAME:path/to/remote-bup-dir -n local-etc /etc
- - Restore a backup from a remote server. (FAIL: unfortunately,
- unlike "bup join", "bup restore" does not yet support remote
- restores. See both "bup join" and "Things that are stupid" below.)
+ - Make a remote backup to ~/.bup on SERVER:
+
+ bup index /etc
+ bup save -r SERVER: -n local-etc /etc
+
+ - See what saves are available in ~/.bup on SERVER:
+
+ bup ls -r SERVER:
+
+ - Restore the remote backup to ./dest:
+
+ bup restore -r SERVER: -C ./dest local-etc/latest/etc
+ ls -l dest/etc
- Defend your backups from death rays (OK fine, more likely from the
occasional bad disk block). This writes parity information
- Look at how little extra space your second backup used on top of
the first:
- du -s ~/.bup
+ du -s ~/.bup
- Restore the first tar backup again (the ~1 is git notation for "one
older than the most recent"):
GIT_DIR=~/.bup git log local-etc
- - Make a backup on a remote server:
+ - Save a tar archive to a remote server (without tar -z to facilitate
+ deduplication):
tar -cvf - /etc | bup split -r SERVERNAME: -n local-etc -vv
- - Try restoring the remote backup tarball:
+ - Restore the archive:
bup join -r SERVERNAME: local-etc | tar -tf -
Help with any of these problems, or others, is very welcome. Join the
mailing list (see below) if you'd like to help.
- - 'bup restore' can't pull directly from a remote server.
-
- So in one sense "save -r" is a dead-end right now. Obviously you
- can use "ssh SERVER bup restore -C ./dest..." to create a tree you
- can transfer elsewhere via rsync/tar/whatever, but that's *lame*.
-
- Until we fix it, you may be able to mount the remote BUP_DIR via
- sshfs and then restore "normally", though that hasn't been
- officially tested.
-
- 'bup save' and 'bup restore' have immature metadata support.
On the plus side, they actually do have support now, but it's new,
give the continuous-backup process a really low CPU and I/O priority so
you wouldn't even know it was running.
- - bup currently has no way to prune *old* backups.
-
- Because of the way the packfile system works, backups become "entangled"
- in weird ways and it's not actually possible to delete one pack
- (corresponding approximately to one backup) without risking screwing up
- other backups.
-
- git itself has lots of ways of optimizing this sort of thing, but its
- methods aren't really applicable here; bup packfiles are just too huge.
- We'll have to do it in a totally different way. There are lots of
- options. For now: make sure you've got lots of disk space :)
+ - bup only has experimental support for pruning old backups.
+
+ While you should now be able to drop old saves and branches with
+ `bup rm`, and reclaim the space occupied by data that's no longer
+ needed by other backups with `bup gc`, these commands are
+ experimental, and should be handled with great care. See the
+ man pages for more information.
- Until we fix this, one possible workaround is to just start a new
- BUP_DIR occasionally, i.e. bup-2013-10, bup-2013-11...
+ Unless you want to help test the new commands, one possible
+ workaround is to just start a new BUP_DIR occasionally,
+ i.e. bup-2013, bup-2014...
- - bup has never been tested on anything but Linux, MacOS, and Windows+Cygwin.
+ - bup has never been tested on anything but Linux, FreeBSD, NetBSD,
+ OS X, and Windows+Cygwin.
There's nothing that makes it *inherently* non-portable, though, so
that's mostly a matter of someone putting in some effort. (For a
- bup needs better documentation.
- According to a recent article about bup in Linux Weekly News
+ According to an article about bup in Linux Weekly News
(https://lwn.net/Articles/380983/), "it's a bit short on examples and
a user guide would be nice." Documentation is the sort of thing that
will never be great unless someone from outside contributes it (since
- bup has no GUI.
- Actually, that's not stupid, but you might consider it a limitation.
- There are a bunch of Linux GUI backup programs; someday I expect someone
- will adapt one of them to use bup.
-
+ Actually, that's not stupid, but you might consider it a
+ limitation. See the ["Related Projects"](https://bup.github.io/)
+ list for some possible options.
More Documentation
==================