
bbackupquery utility -- examine store, compare files, restore, etc.

This file has markers for automatic help generation script -- '>' marks a start of a command/help topic,
and '<' marks the end of a section.

Command line:
=============

> bbackupquery [-q] [-c configfile] [commands ...]

	-q -- quiet, no information prompts
	-c -- specify another bbackupd configuation file

The commands following the options are executed, then (if there was no quit
command) an interactive mode is entered.

If a command contains a space, enclose it in quotes. Example

	bbackupquery "list testdir1" quit

to list the contents of testdir1, and then exit without interactive mode.
<

Commands:
=========

All directory names relative to a "current" directory, or from root if they
start with '/'. The initial directory is always the root directory.


> ls [options] [directory-name]

	List contents of current directory, or specified directory.
	
	-R -- recursively list all files
	-d -- list deleted files/directories
	-o -- list old versions of files/directories
	-I -- don't display object ID
	-F -- don't display flags
	-t -- show file modification time in local time
	      (and attr mod time if has the object has attributes, ~ separated)
	-T -- show file modification time in GMT
	-a -- show updated attribute instead of file modification time
	-s -- show file size in blocks used on server
	      (only very approximate indication of size locally)
	-h -- show file attributes hash
	-D -- sort directories together with files (not dirs first)
	-i -- sort by object ID (the old default)
	-S -- sort by object size in blocks
	-U -- don't sort the results (new default is to sort by name)

list can be used as an alias.
<

> list

	Alias for 'ls'. Type 'help ls' for options.
<

> cd [options] <directory-name>

	Change directory
	
	-d -- consider deleted directories for traversal
	-o -- consider old versions of directories for traversal
		(this option should never be useful in a correctly formed store)
<

> pwd

	Print current directory, always root relative.
<

> lcd <local-directory-name>

	Change local directory.
	
	Type "sh ls" to list the contents.
<

> sh <shell command>

	All of the parameters after the "sh" are run as a shell command.
	
	For example, to list the contents of the location directory, type "sh ls"
<

> get <object-filename> [<local-filename>]
get -i <object-id> <local-filename>

	Gets a file from the store. Object is specified as the filename within
	the current directory, and local filename is optional. Ignores old and
	deleted files when searching the directory for the file to retrieve.
	
	To get an old or deleted file, use the -i option and select the object
	as a hex object ID (first column in listing). The local filename must
	be specified.
<

> compare -a
compare -l <location-name>
compare <store-dir-name> <local-dir-name>

	Compares the (current) data on the store with the data on the disc.
	All the data will be downloaded -- this is potentially a very long
	operation.
	
	-a -- compare all locations
	-l -- compare one backup location as specified in the configuration file.
	-c -- set return code
	-q -- quick compare. Only checks file contents against checksums,
			doesn't do a full download
	-A -- ignore attribute differences
	-E -- ignore exclusion settings
	
	Comparing with the root directory is an error, use -a option instead.

	If -c is set, then the return code (if quit is the next command) will be
		1	Comparison was exact
		2	Differences were found
		3	An error occured
	This can be used for automated tests.
<

> restore [-drif] <directory-name> [<local-directory-name>]

	Restores a directory to the local disc. The local directory specified
	must not exist (unless a previous restore is being restarted). If the
	local directory is omitted, the default is to restore to the same
	directory name and path, relative to the current local directory,
	as set with the "lcd" command.

	The root cannot be restored -- restore locations individually.

	-d -- restore a deleted directory or deleted files inside
	-r -- resume an interrupted restoration
	-i -- directory name is actually an ID
	-f -- force restore to continue if errors are encountered

	If a restore operation is interrupted for any reason, it can be restarted
	using the -r switch. Restore progress information is saved in a file at
	regular intervals during the restore operation to allow restarts. 
<

> getobject <object-id> <local-filename>

	Gets the object specified by the object id (in hex) and stores the raw
	contents in the local file specified.

	This is only useful for debugging as it does not decode files from the
	stored format, which is encrypted and compressed.
<

> usage [-m]

	Show space used on the server for this account.

	-m -- display the output in machine-readable form

	Used: Total amount of space used on the server.
	Old files: Space used by old files
	Deleted files: Space used by deleted files
	Directories: Space used by the directory structure.
	
	When Used exceeds the soft limit, the server will start to remove old and
	deleted files until the usage drops below the soft limit.
	
	After a while, you would expect to see the usage stay at just below the
	soft limit. You only need more space if the space used by old and deleted
	files is near zero.
<

> undelete <directory-name>
undelete -i <object-id>

	Removes the deleted flag from the specified directory name (in the
	current directory) or hex object ID. Be careful not to use this
	command where a directory already exists with the same name which is
	not marked as deleted.
<

> delete <file-name>

	Sets the deleted flag on the specified file name (in the current
	directory, or with a relative path).
<

> quit

	End session and exit.
<


