From 14ae015865df892a9cdc4759121d52ef741d22f7 Mon Sep 17 00:00:00 2001 From: Dennis Schwerdel Date: Thu, 13 Apr 2017 10:36:06 +0200 Subject: [PATCH] Man pages for all subcommands (closes #6) --- CHANGELOG.md | 1 + deb/zvault/Makefile | 6 ++- deb/zvault/debian/manpages | 8 ++++ docs/man/zvault-addkey.1.md | 43 +++++++++++++++++++ docs/man/zvault-algotest.1.md | 73 +++++++++++++++++++++++++++++++++ docs/man/zvault-analyze.1.md | 29 +++++++++++++ docs/man/zvault-bundleinfo.1.md | 30 ++++++++++++++ docs/man/zvault-bundlelist.1.md | 27 ++++++++++++ docs/man/zvault-diff.1.md | 36 ++++++++++++++++ docs/man/zvault-genkey.1.md | 25 +++++++++++ docs/man/zvault-versions.1.md | 31 ++++++++++++++ 11 files changed, 308 insertions(+), 1 deletion(-) create mode 100644 docs/man/zvault-addkey.1.md create mode 100644 docs/man/zvault-algotest.1.md create mode 100644 docs/man/zvault-analyze.1.md create mode 100644 docs/man/zvault-bundleinfo.1.md create mode 100644 docs/man/zvault-bundlelist.1.md create mode 100644 docs/man/zvault-diff.1.md create mode 100644 docs/man/zvault-genkey.1.md create mode 100644 docs/man/zvault-versions.1.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 25e78b2..3f0aa36 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,6 +8,7 @@ This project follows [semantic versioning](http://semver.org). - [added] Locking local repository to avoid index corruption - [added] Storing user/group names in backups - [added] Ability to repair bundles, backups, index, bundle map and bundle cache +- [added] Manpages for all subcommands - [modified] No longer trying to upload by rename - [modified] No longer failing restore if setting file attributes fails - [modified] Backup files must end with `.backup` (**conversion needed**) diff --git a/deb/zvault/Makefile b/deb/zvault/Makefile index 0b76d1f..cca6e05 100644 --- a/deb/zvault/Makefile +++ b/deb/zvault/Makefile @@ -1,7 +1,11 @@ build: man/zvault.1 man/zvault-backup.1 man/zvault-check.1 man/zvault-config.1 \ man/zvault-import.1 man/zvault-info.1 man/zvault-init.1 man/zvault-list.1 \ man/zvault-mount.1 man/zvault-prune.1 man/zvault-remove.1 \ - man/zvault-restore.1 man/zvault-vacuum.1 + man/zvault-restore.1 man/zvault-vacuum.1 man/zvault-addkey.1 \ + man/zvault-algotest.1 man/zvault-analyze.1 man/zvault-bundleinfo.1 \ + man/zvault-bundlelist.1 man/zvault-diff.1 man/zvault-genkey.1 \ + man/zvault-versions.1 + %.1: %.1.md ronn -r $< diff --git a/deb/zvault/debian/manpages b/deb/zvault/debian/manpages index fbb5bcd..8abc0db 100644 --- a/deb/zvault/debian/manpages +++ b/deb/zvault/debian/manpages @@ -11,3 +11,11 @@ man/zvault-mount.1 man/zvault-remove.1 man/zvault-restore.1 man/zvault-vacuum.1 +man/zvault-addkey.1 +man/zvault-algotest.1 +man/zvault-analyze.1 +man/zvault-bundleinfo.1 +man/zvault-bundlelist.1 +man/zvault-diff.1 +man/zvault-genkey.1 +man/zvault-versions.1 diff --git a/docs/man/zvault-addkey.1.md b/docs/man/zvault-addkey.1.md new file mode 100644 index 0000000..109ceaa --- /dev/null +++ b/docs/man/zvault-addkey.1.md @@ -0,0 +1,43 @@ +zvault-addkey(1) -- Add a key pair to the repository +==================================================== + +## SYNOPSIS + +`zvault addkey [OPTIONS] [FILE]` + + +## DESCRIPTION + +This subcommand adds a new key pair to the repository `REPO`. + +If `FILE` is given, the key pair is read from the file and added to the +repository. + +If `--generate` is set, a new key pair is generated, printed to console and +added to the repository. + +If `--default` is set, encryption will be enabled (if not already) and the new +key will be set as default encryption key. + + +## OPTIONS + + * `-g`, `--generate`: + + Generate a new key pair + + + * `-d`, `--default`: + + Set the key pair as default + + + * `-h`, `--help`: + + Prints help information + + +## COPYRIGHT + +Copyright (C) 2017 Dennis Schwerdel +This software is licensed under GPL-3 or newer (see LICENSE.md) diff --git a/docs/man/zvault-algotest.1.md b/docs/man/zvault-algotest.1.md new file mode 100644 index 0000000..b87701f --- /dev/null +++ b/docs/man/zvault-algotest.1.md @@ -0,0 +1,73 @@ +zvault-algotest(1) -- Test a specific algorithm combination +=========================================================== + +## SYNOPSIS + +`zvault algotest [OPTIONS] ` + + +## DESCRIPTION + +This subcommand tests a specific combination of algorithms on a given input +`FILE`. + +The subcommand exists to help users compare and select algorithms and +configuration options when creating a repository with _zvault-init(1)_ or +changing its configuration via _zvault-config(1)_. + +The given algorithms will be used to simulate a backup run and determine the +efficiency and performance of each used algorithm as well as their combination. + +The input file `FILE` is used as sample data during the test and should be +selected to be representative for the envisioned use case. Good examples of such +files can be tar files of system images or parts of a home folder. +Please note, that the input file is read into memory completely in order to +factor out the hard drive speed of the analysis. + +The options are exactly the same as for _zvault-init(1)_. + + +## OPTIONS + +* `--bundle-size `: + + Set the target bundle size in MiB (default: 25). + Please see zvault(1) for more information on *bundle size*. + + +* `--chunker `: + + Set the chunker algorithm and target chunk size (default: fastcdc/16). + Please see _zvault(1)_ for more information on *chunkers* and possible + values. + + +* `-c`, `--compression `: + + Set the compression method and level (default: brotli/3). + Please see _zvault(1)_ for more information on *compression* and possible + values. + + +* `-e`, `--encrypt`: + + Generate a keypair and enable encryption. + Please see _zvault(1)_ for more information on *encryption*. + + +* `--hash `: + + Set the hash method (default: blake2). + Please see _zvault(1)_ for more information on *hash methods* and possible + values. + + +* `-h`, `--help`: + + Prints help information + + +## COPYRIGHT + +Copyright (C) 2017 Dennis Schwerdel +This software is licensed under GPL-3 or newer (see LICENSE.md) diff --git a/docs/man/zvault-analyze.1.md b/docs/man/zvault-analyze.1.md new file mode 100644 index 0000000..af6e4f9 --- /dev/null +++ b/docs/man/zvault-analyze.1.md @@ -0,0 +1,29 @@ +zvault-analyze(1) -- Analyze the used and reclaimable space of bundles +====================================================================== + +## SYNOPSIS + +`zvault analyze [OPTIONS] ` + + +## DESCRIPTION + +This subcommand analyzes the used and reclaimable storage space of bundles in +the repository `REPO`. + +The analysis will scan through all backups and identify used chunks, order them +by bundle and finally determine and print the space that could be reclaimed by +running _zvault-vacuum(1)_ with different ratios. + + +## OPTIONS + + * `-h`, `--help`: + + Prints help information + + +## COPYRIGHT + +Copyright (C) 2017 Dennis Schwerdel +This software is licensed under GPL-3 or newer (see LICENSE.md) diff --git a/docs/man/zvault-bundleinfo.1.md b/docs/man/zvault-bundleinfo.1.md new file mode 100644 index 0000000..edd2c4f --- /dev/null +++ b/docs/man/zvault-bundleinfo.1.md @@ -0,0 +1,30 @@ +zvault-bundleinfo(1) -- Display information on a bundle +======================================================= + +## SYNOPSIS + +`zvault bundleinfo [OPTIONS] ` + + +## DESCRIPTION + +This subcommand displays information on bundle `BUNDLE` in the repository +`REPO`. + +The argument `BUNDLE` must give the id of an existing bundle as listed by +_zvault-bundlelist(1)_. Please note that bundles are stored with random file +names on the remote storage that do not relate to the bundle id. + + + +## OPTIONS + + * `-h`, `--help`: + + Prints help information + + +## COPYRIGHT + +Copyright (C) 2017 Dennis Schwerdel +This software is licensed under GPL-3 or newer (see LICENSE.md) diff --git a/docs/man/zvault-bundlelist.1.md b/docs/man/zvault-bundlelist.1.md new file mode 100644 index 0000000..3f441aa --- /dev/null +++ b/docs/man/zvault-bundlelist.1.md @@ -0,0 +1,27 @@ +zvault-bundlelist(1) -- List bundles in a repository +==================================================== + +## SYNOPSIS + +`zvault bundlelist [OPTIONS] ` + + +## DESCRIPTION + +This subcommand lists all bundles in the repository `REPO`. + +_zvault-bundleinfo(1)_ can be used to display information on a specific bundle +given its bundle id. + + +## OPTIONS + + * `-h`, `--help`: + + Prints help information + + +## COPYRIGHT + +Copyright (C) 2017 Dennis Schwerdel +This software is licensed under GPL-3 or newer (see LICENSE.md) diff --git a/docs/man/zvault-diff.1.md b/docs/man/zvault-diff.1.md new file mode 100644 index 0000000..a62a121 --- /dev/null +++ b/docs/man/zvault-diff.1.md @@ -0,0 +1,36 @@ +zvault-diff(1) -- Display differences between two backup versions +================================================================= + +## SYNOPSIS + +`zvault diff [OPTIONS] ` + + +## DESCRIPTION + +This subcommand lists all differences between the two backups or a backup +subtrees `OLD` and `NEW`. + +The backups or backup subtrees given by `OLD` and `NEW` must be in the format +`[repository]::backup_name[::subtree]` as described in _zvault(1)_. +If `repository` is omitted, the default repository location is used instead. + +The differences will be reported in the format of added, modified, and deleted +files and directories. If some file or directory is present in `NEW` but not in +`OLD`, it will be reported as added (_add_) and if it is present in `OLD` but +not in `NEW`, it will be reported as deleted (_del_). If a file is present in +both versions but got modified between both versions it will be reported as +modified (_mod_). + + +## OPTIONS + + * `-h`, `--help`: + + Prints help information + + +## COPYRIGHT + +Copyright (C) 2017 Dennis Schwerdel +This software is licensed under GPL-3 or newer (see LICENSE.md) diff --git a/docs/man/zvault-genkey.1.md b/docs/man/zvault-genkey.1.md new file mode 100644 index 0000000..fab9fd3 --- /dev/null +++ b/docs/man/zvault-genkey.1.md @@ -0,0 +1,25 @@ +zvault-genkey(1) -- Generate a new key pair +=========================================== + +## SYNOPSIS + +`zvault genkey [OPTIONS] [FILE]` + + +## DESCRIPTION + +This subcommand generates a new key pair, prints it to console and optionally +writes it to the given file `FILE`. + + +## OPTIONS + + * `-h`, `--help`: + + Prints help information + + +## COPYRIGHT + +Copyright (C) 2017 Dennis Schwerdel +This software is licensed under GPL-3 or newer (see LICENSE.md) diff --git a/docs/man/zvault-versions.1.md b/docs/man/zvault-versions.1.md new file mode 100644 index 0000000..e7dd169 --- /dev/null +++ b/docs/man/zvault-versions.1.md @@ -0,0 +1,31 @@ +zvault-versions(1) -- Find different versions of a file in all backups +====================================================================== + +## SYNOPSIS + +`zvault versions [OPTIONS] ` + + +## DESCRIPTION + +This subcommand finds and lists all versions of the file given by `PATH` in any +backup in the repository `REPO`. + +The path given by `PATH` must be relative with regard to the repository root. + +All different versions of the file in all backups will be listed by this +subcommand. That means that only unique versions will be listed with the +earliest backup that version appeared in. + + +## OPTIONS + + * `-h`, `--help`: + + Prints help information + + +## COPYRIGHT + +Copyright (C) 2017 Dennis Schwerdel +This software is licensed under GPL-3 or newer (see LICENSE.md)