]> arthur.barton.de Git - bup.git/blobdiff - README.md
cmd/margin: interpret the meaning of the margin bits.
[bup.git] / README.md
index ef19a84a7a01f0a1c4098065476b4ec9e51567ae..f53c87cc8ec86afd461c5c981e5d5db7089dd09b 100644 (file)
--- a/README.md
+++ b/README.md
@@ -34,7 +34,9 @@ bup has a few advantages over other backup software:
    
  - Unlike git, it writes packfiles *directly* (instead of having a separate
    garbage collection / repacking stage) so it's fast even with gratuitously
-   huge amounts of data.
+   huge amounts of data.  bup's improved index formats also allow you to
+   track far more filenames than git (millions) and keep track of far more
+   objects (hundreds or thousands of gigabytes).
    
  - Data is "automagically" shared between incremental backups without having
    to know which backup is based on which other one - even if the backups
@@ -42,11 +44,23 @@ bup has a few advantages over other backup software:
    other.  You just tell bup to back stuff up, and it saves only the minimum
    amount of data needed.
    
+ - You can back up directly to a remote bup server, without needing tons of
+   temporary disk space on the computer being backed up.  And if your backup
+   is interrupted halfway through, the next run will pick up where you left
+   off.  And it's easy to set up a bup server: just install bup on any
+   machine where you have ssh access.
+   
+ - Bup can use "par2" redundancy to recover corrupted backups even if your
+   disk has undetected bad sectors.
+   
  - Even when a backup is incremental, you don't have to worry about
    restoring the full backup, then each of the incrementals in turn; an
    incremental backup *acts* as if it's a full backup, it just takes less
    disk space.
    
+ - You can mount your bup repository as a FUSE filesystem and access the
+   content that way, and even export it over Samba.
+   
  - It's written in python (with some C parts to make it faster) so it's easy
    for you to extend and maintain.
 
@@ -63,27 +77,26 @@ Reasons you might want to avoid bup
  
  - It currently only works on Linux, MacOS X >= 10.4, or Windows (with
    Cygwin).  Patches to support other platforms are welcome.
- - It has almost no documentation.  Not even a man page!  This file is all
-   you get for now.
    
    
 Getting started
 ---------------
 
- - check out the bup source code using git:
+ - Check out the bup source code using git:
  
         git clone git://github.com/apenwarr/bup
 
- - install the python 2.5 development libraries.  On Debian or Ubuntu, this
-   is:
-        apt-get install python2.5-dev
+ - Install the needed python libraries (including the development
+   libraries).  On Debian or Ubuntu, this is usually:
+        apt-get install python2.6-dev python-fuse
+        
+    Substitute python2.5-dev or python2.4-dev if you have an older system.
        
- - build the python module and symlinks:
+ - Build the python module and symlinks:
  
         make
        
- - run the tests:
+ - Run the tests:
  
         make test
        
@@ -117,28 +130,29 @@ Getting started
    
         bup join local-etc~1 | tar -tf -
  
- - get a list of your previous backups:
+ - Get a list of your previous backups:
  
         GIT_DIR=~/.bup git log local-etc
        
- - make a backup on a remote server (which must already have the 'bup' command
-   somewhere in the PATH, and be accessible via ssh; make sure to replace
-   SERVERNAME with the actual hostname of your server):
+ - 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):
    
         tar -cvf - /etc | bup split -r SERVERNAME: -n local-etc -vv
  
- - try restoring the remote backup tarball:
+ - Try restoring the remote backup tarball:
  
         bup join -r SERVERNAME: local-etc | tar -tf -
        
- - try using the new (slightly experimental) 'bup index' and 'bup save'
+ - Try using the new (slightly experimental) 'bup index' and 'bup save'
    style backups, which bypass 'tar' but have some missing features (see
    "Things that are stupid" below):
        
         bup index -uv /etc
         bup save -n local-etc /etc
        
- - do it again and see how fast an incremental backup can be:
+ - Do it again and see how fast an incremental backup can be:
  
         bup index -uv /etc
         bup save -n local-etc /etc
@@ -213,7 +227,7 @@ a lot of files have changed.
 Things that are stupid for now but which we'll fix later
 --------------------------------------------------------
 
-Help with any of these problems, or others, is very, very welcome.  Join the
+Help with any of these problems, or others, is very welcome.  Join the
 mailing list (see below) if you'd like to help.
 
  - 'bup save' doesn't know about file metadata.
@@ -230,17 +244,16 @@ mailing list (see below) if you'd like to help.
     fetching and packing an entire (possibly huge) pack, which could be very
     slow.  Also, like 'bup save', you would need extra features in order to
     properly restore file metadata.  And files that bup has split into
-    chunks would need to be recombined somehow.
-   
+    chunks will need to be recombined.  Although there's no restore tool,
+    'bup fuse' does accomplish some of this already.
+    
  - 'bup index' is slower than it should be.
  
     It's still rather fast: it can iterate through all the filenames on my
-    600,000 file filesystem in a few seconds.  But sometimes you just want to
-    change a filename or two, so this is needlessly slow.  There should be
-    a way to binary search through the file list rather than always going
-    through it sequentially.  And if you only add a couple of filenames,
-    there's no need to rewrite the entire index; just leave the new files
-    in a second "extra index" file or something.
+    600,000 file filesystem in a few seconds.  But it still needs to rewrite
+    the entire index file just to add a single filename, which is pretty
+    nasty; it should just leave the new files in a second "extra index" file
+    or something.
    
  - bup could use inotify for *really* efficient incremental backups.
 
@@ -261,16 +274,32 @@ mailing list (see below) if you'd like to help.
     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 has never been tested on anything but Linux, MacOS, and Linux+Cygwin.
+ - bup has never been tested on anything but Linux, MacOS, 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
     "native" Windows port, the most annoying thing is the absence of ssh in
     a default Windows installation.)
+    
+ - bup needs better documentation.
+    According to a recent article about git 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
+    the developers can never remember which parts are hard to understand).
+    
+ - bup is "relatively speedy" and has "pretty good" compression.
+    ...according to the same LWN article.  Clearly neither of those is good
+    enough.  We should have awe-inspiring speed and crazy-good compression. 
+    Must work on that.  Writing more parts in C might help with the speed.
    
- - 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.
+ - 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.
 
 
 How you can help