From: Avery Pennarun Date: Sun, 5 Sep 2010 18:44:41 +0000 (-0700) Subject: Documentation/*.md: add some options that we forgot to document. X-Git-Tag: bup-0.18~8 X-Git-Url: https://arthur.barton.de/cgi-bin/gitweb.cgi?p=bup.git;a=commitdiff_plain;h=5d502ae9e4becf6be6c46872ffdfe808c14a739b Documentation/*.md: add some options that we forgot to document. Software evolves, but documentation evolves... slower. Signed-off-by: Avery Pennarun --- diff --git a/Documentation/bup-ftp.md b/Documentation/bup-ftp.md index ba11b48..04d0c72 100644 --- 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`: -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 @@ -61,18 +63,16 @@ quit $ bup ftp bup> ls - mybackup/ - yourbackup/ + mybackup/ yourbackup/ + 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> get myfile Saving 'myfile' bup> quit diff --git a/Documentation/bup-help.md b/Documentation/bup-help.md index 9799279..059b04c 100644 --- a/Documentation/bup-help.md +++ b/Documentation/bup-help.md @@ -20,7 +20,7 @@ This is currently equivalent to typing `man bup-`. $ 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 diff --git a/Documentation/bup-index.md b/Documentation/bup-index.md index 9b72a00..fa1552b 100644 --- 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 - 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 diff --git a/Documentation/bup-margin.md b/Documentation/bup-margin.md index 042c182..b3b78a2 100644 --- a/Documentation/bup-margin.md +++ b/Documentation/bup-margin.md @@ -8,7 +8,7 @@ bup-margin - figure out your deduplication safety margin # SYNOPSIS -bup margin +bup margin [options...] # 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. +# 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 + $ bup margin --predict + PackIdxList: using 1 index. + Reading indexes: 100.00% (1612581/1612581), done. + 915 of 1612581 (0.057%) + # SEE ALSO diff --git a/Documentation/bup-memtest.md b/Documentation/bup-memtest.md index 108a5a1..1450d2b 100644 --- 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. + +--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 diff --git a/Documentation/bup-midx.md b/Documentation/bup-midx.md index 829a74a..c216c89 100644 --- 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. +--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 diff --git a/Documentation/bup-save.md b/Documentation/bup-save.md index 394855d..4f969c1 100644 --- 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 - 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 @@ -67,7 +76,7 @@ for `bup-index`(1). $ 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. diff --git a/Documentation/bup-split.md b/Documentation/bup-split.md index 41a5731..020f65f 100644 --- 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.) +-q, --quiet +: disable progress messages. + -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. @@ -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. +--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 diff --git a/Documentation/bup.md b/Documentation/bup.md index 8def75c..ad4735c 100644 --- a/Documentation/bup.md +++ b/Documentation/bup.md @@ -8,7 +8,7 @@ bup - Backup program using rolling checksums and git file formats # SYNOPSIS -bup \ [options...] +bup [global options...] \ [options...] # DESCRIPTION @@ -24,6 +24,18 @@ using git tools. 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) @@ -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 -`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-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 @@ -55,6 +63,10 @@ pages. : 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) @@ -65,8 +77,12 @@ pages. : 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-version`(1) +: Report the version number of your copy of bup. # SEE ALSO diff --git a/cmd/split-cmd.py b/cmd/split-cmd.py index 26340bf..5a3ea92 100755 --- 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) -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) +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