Documentation/*.md: add some options that we forgot to document.

Software evolves, but documentation evolves... slower.

Signed-off-by: Avery Pennarun <apenwarr@gmail.com>

diff --git a/Documentation/bup-ftp.md b/Documentation/bup-ftp.md
index ba11b48135c2fa57732c78a7e5256268743b6bef..04d0c728a5f705b7d20433beeeb05a3134afe8c0 100644 (file)
--- a/Documentation/bup-ftp.md
+++ b/Documentation/bup-ftp.md
@@ -27,8 +27,10 @@ lot of typing.
 
 The following commands are available inside `bup ftp`:
 
 
 The following commands are available inside `bup ftp`:
 

-ls
-:   print the contents of the current working directory
+ls [-a]
+:   print the contents of the current working directory. 
+    If -a is given, also include hidden files (files which
+    start with a `.` character).

 
 cd *dirname*
 :   change to a different working directory
 
 cd *dirname*
 :   change to a different working directory


@@ -61,18 +63,16 @@ quit
 
     $ bup ftp
     bup> ls
 
     $ bup ftp
     bup> ls

-    mybackup/
-    yourbackup/
+    mybackup/    yourbackup/
+

     bup> cd mybackup/
     bup> ls
     bup> cd mybackup/
     bup> ls

-    .2fe288dedbfab372c84b0502ee2bc1504270f3b3/
-    .ae760aa4cfc13b689b46e3d2ce5ae50e92299c72/
-    2010-02-05-185507@
-    2010-02-05-185508@
-    latest@
+    2010-02-05-185507@   2010-02-05-185508@    latest@
+

     bup> cd latest/
     bup> ls
       (...etc...)
     bup> cd latest/
     bup> ls
       (...etc...)

+

     bup> get myfile
     Saving 'myfile'
     bup> quit
     bup> get myfile
     Saving 'myfile'
     bup> quit

diff --git a/Documentation/bup-help.md b/Documentation/bup-help.md
index 97992790f4d6bb89979add0b62a8ef4d5cc6e4c3..059b04c200bbcda89efec232727971ce01ec464a 100644 (file)
--- a/Documentation/bup-help.md
+++ b/Documentation/bup-help.md
@@ -20,7 +20,7 @@ This is currently equivalent to typing `man bup-<command>`.
     
     $ bup help help
     (Imagine that this man page was pasted below,
     
     $ bup help help
     (Imagine that this man page was pasted below,

-     recursively.  Because that would cause an endless
+     recursively.  Since that would cause an endless loop

      we include this silly remark instead.  Chicken.)
     
 # BUP
      we include this silly remark instead.  Chicken.)
     
 # BUP

diff --git a/Documentation/bup-index.md b/Documentation/bup-index.md
index 9b72a00dc36a422a5afb387c7621392db0f80358..fa1552b210ae12c7b22ce5e1f52ebe0f9698437e 100644 (file)
--- a/Documentation/bup-index.md
+++ b/Documentation/bup-index.md
@@ -76,7 +76,7 @@ need the same information).
     
 -l, --long
 :   print more information about each file, in a similar
     
 -l, --long
 :   print more information about each file, in a similar

-    format to the `-l` option to `ls`(1).  (INCOMPLETE)
+    format to the `-l` option to `ls`(1).

 
 -x, --xdev, --one-file-system
 :   don't cross filesystem boundaries when recursing
 
 -x, --xdev, --one-file-system
 :   don't cross filesystem boundaries when recursing

diff --git a/Documentation/bup-margin.md b/Documentation/bup-margin.md
index 042c1825ff954c4c671f1b4fb29e960fc18d6a59..b3b78a2928b3529d477c2acc26c5343b1ccc9f3f 100644 (file)
--- a/Documentation/bup-margin.md
+++ b/Documentation/bup-margin.md
@@ -8,7 +8,7 @@ bup-margin - figure out your deduplication safety margin
 
 # SYNOPSIS
 
 
 # SYNOPSIS
 

-bup margin
+bup margin [options...]

 
 # DESCRIPTION
 
 
 # DESCRIPTION
 


@@ -37,12 +37,31 @@ collisions, you can monitor your repository by running `bup
 margin` occasionally to see if you're getting dangerously
 close to 160 bits.
 
 margin` occasionally to see if you're getting dangerously
 close to 160 bits.
 

+# OPTIONS
+
+--predict
+:   Guess the offset into each index file where a
+    particular object will appear, and report the maximum
+    deviation of the correct answer from the guess.  This
+    is potentially useful for tuning an interpolation
+    search algorithm.
+    
+--ignore-midx
+:   don't use .midx files, use only .idx files.  This is
+    only really useful when used with `--predict`.
+
+    

 # EXAMPLE
 
     $ bup margin
     Reading indexes: 100.00% (11188299/11188299), done.
     45
     
 # EXAMPLE
 
     $ bup margin
     Reading indexes: 100.00% (11188299/11188299), done.
     45
     

+    $ bup margin --predict
+    PackIdxList: using 1 index.
+    Reading indexes: 100.00% (1612581/1612581), done.
+    915 of 1612581 (0.057%) 
+    

 
 # SEE ALSO
 
 
 # SEE ALSO
 

diff --git a/Documentation/bup-memtest.md b/Documentation/bup-memtest.md
index 108a5a1328fe97f0df5fb771ab3c5af8632b0194..1450d2bb00ca750bb2a6e0795cbd66bf12424bab 100644 (file)
--- a/Documentation/bup-memtest.md
+++ b/Documentation/bup-memtest.md
@@ -42,6 +42,18 @@ what causes an increase in the VmRSS column.
 :   ignore any `.midx` files created by `bup midx`.  This
     allows you to compare memory performance with and
     without using midx.
 :   ignore any `.midx` files created by `bup midx`.  This
     allows you to compare memory performance with and
     without using midx.

+    
+--existing
+:   search for existing objects instead of searching for
+    random nonexistent ones.  This can greatly affect
+    memory usage and performance.  Note that most of the
+    time, `bup save` spends most of its time searching for
+    nonexistent objects, since existing ones are probably
+    in unmodified files that we won't be trying to back up
+    anyway.  So the default behaviour reflects real bup
+    performance more accurately.  But you might want this
+    option anyway just to make sure you haven't made
+    searching for existing objects much worse than before.

 
 
 # EXAMPLE
 
 
 # EXAMPLE

diff --git a/Documentation/bup-midx.md b/Documentation/bup-midx.md
index 829a74a2e120404ca4133a23c461d3f0b4df6e9d..c216c89b325df63e894928d2ed64ea9fb9ccab81 100644 (file)
--- a/Documentation/bup-midx.md
+++ b/Documentation/bup-midx.md
@@ -35,6 +35,14 @@ requiring too much RAM.
     already exist.  This will result in the fastest backup
     performance, but may take a long time to run.
 
     already exist.  This will result in the fastest backup
     performance, but may take a long time to run.
 

+--max-files
+:   maximum number of .idx files to open at a time.  You
+    can use this if you have an especially small number of file
+    descriptors available, so that midx can complete
+    (though possibly non-optimally) even if it can't open
+    all your .idx files at once.  The default value of this
+    option should be fine for most people.
+

 
 # EXAMPLE
 
 
 # EXAMPLE
 

diff --git a/Documentation/bup-save.md b/Documentation/bup-save.md
index 394855d07b1c0df1be5ecae573c7e3e6d60e9396..4f969c1ef16430f8b198bb3e67bfe8e5d200cb95 100644 (file)
--- a/Documentation/bup-save.md
+++ b/Documentation/bup-save.md
@@ -59,7 +59,16 @@ for `bup-index`(1).
     files, which can usually be backed up quickly, and skip
     over large ones (like virtual machine images) which
     take longer.  Then you can back up the large files
     files, which can usually be backed up quickly, and skip
     over large ones (like virtual machine images) which
     take longer.  Then you can back up the large files

-    less frequently.
+    less frequently.  Use a suffix like k, M, or G to
+    specify multiples of 1024, 1024*1024, 1024*1024*1024
+    respectively.
+    
+--bwlimit=*bytes/sec*
+:   don't transmit more than *bytes/sec* bytes per second
+    to the server.  This is good for making your backups
+    not suck up all your network bandwidth.  Use a suffix
+    like k, M, or G to specify multiples of 1024,
+    1024*1024, 1024*1024*1024 respectively.

     
 
 # EXAMPLE
     
 
 # EXAMPLE


@@ -67,7 +76,7 @@ for `bup-index`(1).
     $ bup index -ux /etc
     Indexing: 1981, done.
     
     $ bup index -ux /etc
     Indexing: 1981, done.
     

-    $ bup save -r myserver: -n my-pc-backup /etc
+    $ bup save -r myserver: -n my-pc-backup --bwlimit=50k /etc

     Reading index: 1981, done.
     Saving: 100.00% (998/998k, 1981/1981 files), done.    
     
     Reading index: 1981, done.
     Saving: 100.00% (998/998k, 1981/1981 files), done.    
     

diff --git a/Documentation/bup-split.md b/Documentation/bup-split.md
index 41a5731db6f94a2add2023ca9dcca10b4c5f157e..020f65f6d4ea4de4475762ce9a009d16f8f179e5 100644 (file)
--- a/Documentation/bup-split.md
+++ b/Documentation/bup-split.md
@@ -66,11 +66,21 @@ To get the data back, use `bup-join`(1).
     the same name, and later view the history of that
     dataset to see how it has changed over time.)
     
     the same name, and later view the history of that
     dataset to see how it has changed over time.)
     

+-q, --quiet
+:   disable progress messages.
+

 -v, --verbose
 :   increase verbosity (can be used more than once).
 
 -v, --verbose
 :   increase verbosity (can be used more than once).
 

--q, --quiet
-:   disable progress messages.
+--noop
+:   read the data and split it into blocks based on the "bupsplit"
+    rolling checksum algorithm, but don't do anything with
+    the blocks.  This is mostly useful for benchmarking.
+
+--copy
+:   like --noop, but also write the data to stdout.  This
+    can be useful for benchmarking the speed of read+bupsplit+write
+    for large amounts of data.

 
 --bench
 :   print benchmark timings to stderr.
 
 --bench
 :   print benchmark timings to stderr.


@@ -91,6 +101,14 @@ To get the data back, use `bup-join`(1).
     generate a new tree and link to that.  Default is
     4096 objects per tree.
 
     generate a new tree and link to that.  Default is
     4096 objects per tree.
 

+--bwlimit=*bytes/sec*
+:   don't transmit more than *bytes/sec* bytes per second
+    to the server.  This is good for making your backups
+    not suck up all your network bandwidth.  Use a suffix
+    like k, M, or G to specify multiples of 1024,
+    1024*1024, 1024*1024*1024 respectively.
+
+

 # EXAMPLE
     
     $ tar -cf - /etc | bup split -r myserver: -n mybackup-tar
 # EXAMPLE
     
     $ tar -cf - /etc | bup split -r myserver: -n mybackup-tar

diff --git a/Documentation/bup.md b/Documentation/bup.md
index 8def75c403712a63969397ee229bde3b3a0b75a4..ad4735cd9845a851e4bd9aabcfbb3f3e71082cf3 100644 (file)
--- a/Documentation/bup.md
+++ b/Documentation/bup.md
@@ -8,7 +8,7 @@ bup - Backup program using rolling checksums and git file formats
 
 # SYNOPSIS
 
 
 # SYNOPSIS
 

-bup \<command\> [options...]
+bup [global options...] \<command\> [options...]

 
 # DESCRIPTION
 
 
 # DESCRIPTION
 


@@ -24,6 +24,18 @@ using git tools.
 The individual bup subcommands appear in their own man
 pages.
 
 The individual bup subcommands appear in their own man
 pages.
 

+# GLOBAL OPTIONS
+
+--version
+:   print bup's version number.  Equivalent to
+    `bup-version`(1)
+
+-d, --bup-dir=*BUP_DIR*
+:   use the given BUP_DIR parameter as the bup repository
+    location, instead of reading it from the $BUP_DIR
+    environment variable or using the default `~/.bup`
+    location.
+

 # COMMONLY USED SUBCOMMANDS
 
 `bup-fsck`(1)
 # COMMONLY USED SUBCOMMANDS
 
 `bup-fsck`(1)


@@ -36,16 +48,12 @@ pages.
 :   Print detailed help for the given command
 `bup-index`(1)
 :   Create or display the index of files to back up
 :   Print detailed help for the given command
 `bup-index`(1)
 :   Create or display the index of files to back up

-`bup-join`(1)
-:   Retrieve a file backed up using `bup-split`(1)
-`bup-ls`(1)
-:   Browse the files in your backup sets

 `bup-midx`(1)
 :   Index objects to speed up future backups
 `bup-save`(1)
 :   Save files into a backup set (note: run "bup index" first)
 `bup-midx`(1)
 :   Index objects to speed up future backups
 `bup-save`(1)
 :   Save files into a backup set (note: run "bup index" first)

-`bup-split`(1)
-:   Split a single file into its own backup set
+`bup-web`(1)
+:   Launch a web server to examine backup sets

 
 # RARELY USED SUBCOMMANDS
 
 
 # RARELY USED SUBCOMMANDS
 


@@ -55,6 +63,10 @@ pages.
 :   Recursively list files in your filesystem
 `bup-init`(1)
 :   Initialize a bup repository
 :   Recursively list files in your filesystem
 `bup-init`(1)
 :   Initialize a bup repository

+`bup-join`(1)
+:   Retrieve a file backed up using `bup-split`(1)
+`bup-ls`(1)
+:   Browse the files in your backup sets

 `bup-margin`(1)
 :   Determine how close your bup repository is to armageddon
 `bup-memtest`(1)
 `bup-margin`(1)
 :   Determine how close your bup repository is to armageddon
 `bup-memtest`(1)


@@ -65,8 +77,12 @@ pages.
 :   Generate a stream of random output
 `bup-server`(1)
 :   The server side of the bup client-server relationship
 :   Generate a stream of random output
 `bup-server`(1)
 :   The server side of the bup client-server relationship

+`bup-split`(1)
+:   Split a single file into its own backup set

 `bup-tick`(1)
 :   Wait for up to one second.
 `bup-tick`(1)
 :   Wait for up to one second.

+`bup-version`(1)
+:   Report the version number of your copy of bup.

 
 # SEE ALSO
 
 
 # SEE ALSO
 

diff --git a/cmd/split-cmd.py b/cmd/split-cmd.py
index 26340bfe9a06c0e03d69169d65a6ffd9c7d623bd..5a3ea92808e378ec9a4ac03471eece34fa9a9784 100755 (executable)
--- a/cmd/split-cmd.py
+++ b/cmd/split-cmd.py
@@ -12,9 +12,9 @@ b,blobs    output a series of blob ids
 t,tree     output a tree id
 c,commit   output a commit id
 n,name=    name of backup set to update (if any)
 t,tree     output a tree id
 c,commit   output a commit id
 n,name=    name of backup set to update (if any)

-N,noop     don't actually save the data anywhere

 q,quiet    don't print progress messages
 v,verbose  increase log output (can be used more than once)
 q,quiet    don't print progress messages
 v,verbose  increase log output (can be used more than once)

+noop       don't actually save the data anywhere

 copy       just copy input to output, hashsplitting along the way
 bench      print benchmark timings to stderr
 max-pack-size=  maximum bytes in a single pack
 copy       just copy input to output, hashsplitting along the way
 bench      print benchmark timings to stderr
 max-pack-size=  maximum bytes in a single pack