From abd34ab76f6d90e4147880259de0169a2b37e770 Mon Sep 17 00:00:00 2001
From: Alexander Neumann <alexander@bumpern.de>
Date: Mon, 21 May 2018 15:57:32 +0200
Subject: [PATCH] Update manpages and auto-completion

---
 doc/bash-completion.sh         | 191 +++++++++++++++++++++++++--------
 doc/man/restic-backup.1        |   6 +-
 doc/man/restic-cache.1         |  95 ++++++++++++++++
 doc/man/restic-cat.1           |   6 +-
 doc/man/restic-check.1         |   6 +-
 doc/man/restic-diff.1          |  10 +-
 doc/man/restic-dump.1          |   6 +-
 doc/man/restic-find.1          |   6 +-
 doc/man/restic-forget.1        |  10 +-
 doc/man/restic-generate.1      |   6 +-
 doc/man/restic-init.1          |   6 +-
 doc/man/restic-key.1           |  10 +-
 doc/man/restic-list.1          |   6 +-
 doc/man/restic-ls.1            |   6 +-
 doc/man/restic-migrate.1       |   6 +-
 doc/man/restic-mount.1         |   6 +-
 doc/man/restic-prune.1         |   6 +-
 doc/man/restic-rebuild-index.1 |   6 +-
 doc/man/restic-restore.1       |   6 +-
 doc/man/restic-snapshots.1     |   6 +-
 doc/man/restic-tag.1           |   6 +-
 doc/man/restic-unlock.1        |   6 +-
 doc/man/restic-version.1       |   6 +-
 doc/man/restic.1               |   8 +-
 doc/zsh-completion.zsh         |   2 +-
 25 files changed, 365 insertions(+), 69 deletions(-)
 create mode 100644 doc/man/restic-cache.1

diff --git a/doc/bash-completion.sh b/doc/bash-completion.sh
index c4652c36f..5203f5368 100644
--- a/doc/bash-completion.sh
+++ b/doc/bash-completion.sh
@@ -1,6 +1,6 @@
 # bash completion for restic                               -*- shell-script -*-
 
-__debug()
+__restic_debug()
 {
     if [[ -n ${BASH_COMP_DEBUG_FILE} ]]; then
         echo "$*" >> "${BASH_COMP_DEBUG_FILE}"
@@ -9,13 +9,13 @@ __debug()
 
 # Homebrew on Macs have version 1.3 of bash-completion which doesn't include
 # _init_completion. This is a very minimal version of that function.
-__my_init_completion()
+__restic_init_completion()
 {
     COMPREPLY=()
     _get_comp_words_by_ref "$@" cur prev words cword
 }
 
-__index_of_word()
+__restic_index_of_word()
 {
     local w word=$1
     shift
@@ -27,7 +27,7 @@ __index_of_word()
     index=-1
 }
 
-__contains_word()
+__restic_contains_word()
 {
     local w word=$1; shift
     for w in "$@"; do
@@ -36,9 +36,9 @@ __contains_word()
     return 1
 }
 
-__handle_reply()
+__restic_handle_reply()
 {
-    __debug "${FUNCNAME[0]}"
+    __restic_debug "${FUNCNAME[0]}"
     case $cur in
         -*)
             if [[ $(type -t compopt) = "builtin" ]]; then
@@ -62,8 +62,8 @@ __handle_reply()
                 fi
 
                 local index flag
-                flag="${cur%%=*}"
-                __index_of_word "${flag}" "${flags_with_completion[@]}"
+                flag="${cur%=*}"
+                __restic_index_of_word "${flag}" "${flags_with_completion[@]}"
                 COMPREPLY=()
                 if [[ ${index} -ge 0 ]]; then
                     PREFIX=""
@@ -81,7 +81,7 @@ __handle_reply()
 
     # check if we are handling a flag with special work handling
     local index
-    __index_of_word "${prev}" "${flags_with_completion[@]}"
+    __restic_index_of_word "${prev}" "${flags_with_completion[@]}"
     if [[ ${index} -ge 0 ]]; then
         ${flags_completion[${index}]}
         return
@@ -114,24 +114,30 @@ __handle_reply()
     if declare -F __ltrim_colon_completions >/dev/null; then
         __ltrim_colon_completions "$cur"
     fi
+
+    # If there is only 1 completion and it is a flag with an = it will be completed
+    # but we don't want a space after the =
+    if [[ "${#COMPREPLY[@]}" -eq "1" ]] && [[ $(type -t compopt) = "builtin" ]] && [[ "${COMPREPLY[0]}" == --*= ]]; then
+       compopt -o nospace
+    fi
 }
 
 # The arguments should be in the form "ext1|ext2|extn"
-__handle_filename_extension_flag()
+__restic_handle_filename_extension_flag()
 {
     local ext="$1"
     _filedir "@(${ext})"
 }
 
-__handle_subdirs_in_dir_flag()
+__restic_handle_subdirs_in_dir_flag()
 {
     local dir="$1"
     pushd "${dir}" >/dev/null 2>&1 && _filedir -d && popd >/dev/null 2>&1
 }
 
-__handle_flag()
+__restic_handle_flag()
 {
-    __debug "${FUNCNAME[0]}: c is $c words[c] is ${words[c]}"
+    __restic_debug "${FUNCNAME[0]}: c is $c words[c] is ${words[c]}"
 
     # if a command required a flag, and we found it, unset must_have_one_flag()
     local flagname=${words[c]}
@@ -139,30 +145,33 @@ __handle_flag()
     # if the word contained an =
     if [[ ${words[c]} == *"="* ]]; then
         flagvalue=${flagname#*=} # take in as flagvalue after the =
-        flagname=${flagname%%=*} # strip everything after the =
+        flagname=${flagname%=*} # strip everything after the =
         flagname="${flagname}=" # but put the = back
     fi
-    __debug "${FUNCNAME[0]}: looking for ${flagname}"
-    if __contains_word "${flagname}" "${must_have_one_flag[@]}"; then
+    __restic_debug "${FUNCNAME[0]}: looking for ${flagname}"
+    if __restic_contains_word "${flagname}" "${must_have_one_flag[@]}"; then
         must_have_one_flag=()
     fi
 
     # if you set a flag which only applies to this command, don't show subcommands
-    if __contains_word "${flagname}" "${local_nonpersistent_flags[@]}"; then
+    if __restic_contains_word "${flagname}" "${local_nonpersistent_flags[@]}"; then
       commands=()
     fi
 
     # keep flag value with flagname as flaghash
-    if [ -n "${flagvalue}" ] ; then
-        flaghash[${flagname}]=${flagvalue}
-    elif [ -n "${words[ $((c+1)) ]}" ] ; then
-        flaghash[${flagname}]=${words[ $((c+1)) ]}
-    else
-        flaghash[${flagname}]="true" # pad "true" for bool flag
+    # flaghash variable is an associative array which is only supported in bash > 3.
+    if [[ -z "${BASH_VERSION}" || "${BASH_VERSINFO[0]}" -gt 3 ]]; then
+        if [ -n "${flagvalue}" ] ; then
+            flaghash[${flagname}]=${flagvalue}
+        elif [ -n "${words[ $((c+1)) ]}" ] ; then
+            flaghash[${flagname}]=${words[ $((c+1)) ]}
+        else
+            flaghash[${flagname}]="true" # pad "true" for bool flag
+        fi
     fi
 
     # skip the argument to a two word flag
-    if __contains_word "${words[c]}" "${two_word_flags[@]}"; then
+    if __restic_contains_word "${words[c]}" "${two_word_flags[@]}"; then
         c=$((c+1))
         # if we are looking for a flags value, don't show commands
         if [[ $c -eq $cword ]]; then
@@ -174,13 +183,13 @@ __handle_flag()
 
 }
 
-__handle_noun()
+__restic_handle_noun()
 {
-    __debug "${FUNCNAME[0]}: c is $c words[c] is ${words[c]}"
+    __restic_debug "${FUNCNAME[0]}: c is $c words[c] is ${words[c]}"
 
-    if __contains_word "${words[c]}" "${must_have_one_noun[@]}"; then
+    if __restic_contains_word "${words[c]}" "${must_have_one_noun[@]}"; then
         must_have_one_noun=()
-    elif __contains_word "${words[c]}" "${noun_aliases[@]}"; then
+    elif __restic_contains_word "${words[c]}" "${noun_aliases[@]}"; then
         must_have_one_noun=()
     fi
 
@@ -188,42 +197,42 @@ __handle_noun()
     c=$((c+1))
 }
 
-__handle_command()
+__restic_handle_command()
 {
-    __debug "${FUNCNAME[0]}: c is $c words[c] is ${words[c]}"
+    __restic_debug "${FUNCNAME[0]}: c is $c words[c] is ${words[c]}"
 
     local next_command
     if [[ -n ${last_command} ]]; then
         next_command="_${last_command}_${words[c]//:/__}"
     else
         if [[ $c -eq 0 ]]; then
-            next_command="_$(basename "${words[c]//:/__}")"
+            next_command="_restic_root_command"
         else
             next_command="_${words[c]//:/__}"
         fi
     fi
     c=$((c+1))
-    __debug "${FUNCNAME[0]}: looking for ${next_command}"
+    __restic_debug "${FUNCNAME[0]}: looking for ${next_command}"
     declare -F "$next_command" >/dev/null && $next_command
 }
 
-__handle_word()
+__restic_handle_word()
 {
     if [[ $c -ge $cword ]]; then
-        __handle_reply
+        __restic_handle_reply
         return
     fi
-    __debug "${FUNCNAME[0]}: c is $c words[c] is ${words[c]}"
+    __restic_debug "${FUNCNAME[0]}: c is $c words[c] is ${words[c]}"
     if [[ "${words[c]}" == -* ]]; then
-        __handle_flag
-    elif __contains_word "${words[c]}" "${commands[@]}"; then
-        __handle_command
-    elif [[ $c -eq 0 ]] && __contains_word "$(basename "${words[c]}")" "${commands[@]}"; then
-        __handle_command
+        __restic_handle_flag
+    elif __restic_contains_word "${words[c]}" "${commands[@]}"; then
+        __restic_handle_command
+    elif [[ $c -eq 0 ]]; then
+        __restic_handle_command
     else
-        __handle_noun
+        __restic_handle_noun
     fi
-    __handle_word
+    __restic_handle_word
 }
 
 _restic_backup()
@@ -288,6 +297,51 @@ _restic_backup()
     flags+=("--repo=")
     two_word_flags+=("-r")
     flags+=("--tls-client-cert=")
+    flags+=("--verbose")
+    flags+=("-v")
+
+    must_have_one_flag=()
+    must_have_one_noun=()
+    noun_aliases=()
+}
+
+_restic_cache()
+{
+    last_command="restic_cache"
+    commands=()
+
+    flags=()
+    two_word_flags=()
+    local_nonpersistent_flags=()
+    flags_with_completion=()
+    flags_completion=()
+
+    flags+=("--cleanup")
+    local_nonpersistent_flags+=("--cleanup")
+    flags+=("--help")
+    flags+=("-h")
+    local_nonpersistent_flags+=("--help")
+    flags+=("--max-age=")
+    local_nonpersistent_flags+=("--max-age=")
+    flags+=("--cacert=")
+    flags+=("--cache-dir=")
+    flags+=("--cleanup-cache")
+    flags+=("--json")
+    flags+=("--limit-download=")
+    flags+=("--limit-upload=")
+    flags+=("--no-cache")
+    flags+=("--no-lock")
+    flags+=("--option=")
+    two_word_flags+=("-o")
+    flags+=("--password-file=")
+    two_word_flags+=("-p")
+    flags+=("--quiet")
+    flags+=("-q")
+    flags+=("--repo=")
+    two_word_flags+=("-r")
+    flags+=("--tls-client-cert=")
+    flags+=("--verbose")
+    flags+=("-v")
 
     must_have_one_flag=()
     must_have_one_noun=()
@@ -325,6 +379,8 @@ _restic_cat()
     flags+=("--repo=")
     two_word_flags+=("-r")
     flags+=("--tls-client-cert=")
+    flags+=("--verbose")
+    flags+=("-v")
 
     must_have_one_flag=()
     must_have_one_noun=()
@@ -370,6 +426,8 @@ _restic_check()
     flags+=("--repo=")
     two_word_flags+=("-r")
     flags+=("--tls-client-cert=")
+    flags+=("--verbose")
+    flags+=("-v")
 
     must_have_one_flag=()
     must_have_one_noun=()
@@ -409,6 +467,8 @@ _restic_diff()
     flags+=("--repo=")
     two_word_flags+=("-r")
     flags+=("--tls-client-cert=")
+    flags+=("--verbose")
+    flags+=("-v")
 
     must_have_one_flag=()
     must_have_one_noun=()
@@ -453,6 +513,8 @@ _restic_dump()
     flags+=("--repo=")
     two_word_flags+=("-r")
     flags+=("--tls-client-cert=")
+    flags+=("--verbose")
+    flags+=("-v")
 
     must_have_one_flag=()
     must_have_one_noun=()
@@ -512,6 +574,8 @@ _restic_find()
     flags+=("--repo=")
     two_word_flags+=("-r")
     flags+=("--tls-client-cert=")
+    flags+=("--verbose")
+    flags+=("-v")
 
     must_have_one_flag=()
     must_have_one_noun=()
@@ -547,6 +611,8 @@ _restic_forget()
     flags+=("--keep-yearly=")
     two_word_flags+=("-y")
     local_nonpersistent_flags+=("--keep-yearly=")
+    flags+=("--keep-within=")
+    local_nonpersistent_flags+=("--keep-within=")
     flags+=("--keep-tag=")
     local_nonpersistent_flags+=("--keep-tag=")
     flags+=("--host=")
@@ -588,6 +654,8 @@ _restic_forget()
     flags+=("--repo=")
     two_word_flags+=("-r")
     flags+=("--tls-client-cert=")
+    flags+=("--verbose")
+    flags+=("-v")
 
     must_have_one_flag=()
     must_have_one_noun=()
@@ -631,6 +699,8 @@ _restic_generate()
     flags+=("--repo=")
     two_word_flags+=("-r")
     flags+=("--tls-client-cert=")
+    flags+=("--verbose")
+    flags+=("-v")
 
     must_have_one_flag=()
     must_have_one_noun=()
@@ -668,6 +738,8 @@ _restic_init()
     flags+=("--repo=")
     two_word_flags+=("-r")
     flags+=("--tls-client-cert=")
+    flags+=("--verbose")
+    flags+=("-v")
 
     must_have_one_flag=()
     must_have_one_noun=()
@@ -688,6 +760,8 @@ _restic_key()
     flags+=("--help")
     flags+=("-h")
     local_nonpersistent_flags+=("--help")
+    flags+=("--new-password-file=")
+    local_nonpersistent_flags+=("--new-password-file=")
     flags+=("--cacert=")
     flags+=("--cache-dir=")
     flags+=("--cleanup-cache")
@@ -705,6 +779,8 @@ _restic_key()
     flags+=("--repo=")
     two_word_flags+=("-r")
     flags+=("--tls-client-cert=")
+    flags+=("--verbose")
+    flags+=("-v")
 
     must_have_one_flag=()
     must_have_one_noun=()
@@ -742,6 +818,8 @@ _restic_list()
     flags+=("--repo=")
     two_word_flags+=("-r")
     flags+=("--tls-client-cert=")
+    flags+=("--verbose")
+    flags+=("-v")
 
     must_have_one_flag=()
     must_have_one_noun=()
@@ -789,6 +867,8 @@ _restic_ls()
     flags+=("--repo=")
     two_word_flags+=("-r")
     flags+=("--tls-client-cert=")
+    flags+=("--verbose")
+    flags+=("-v")
 
     must_have_one_flag=()
     must_have_one_noun=()
@@ -829,6 +909,8 @@ _restic_migrate()
     flags+=("--repo=")
     two_word_flags+=("-r")
     flags+=("--tls-client-cert=")
+    flags+=("--verbose")
+    flags+=("-v")
 
     must_have_one_flag=()
     must_have_one_noun=()
@@ -881,6 +963,8 @@ _restic_mount()
     flags+=("--repo=")
     two_word_flags+=("-r")
     flags+=("--tls-client-cert=")
+    flags+=("--verbose")
+    flags+=("-v")
 
     must_have_one_flag=()
     must_have_one_noun=()
@@ -918,6 +1002,8 @@ _restic_prune()
     flags+=("--repo=")
     two_word_flags+=("-r")
     flags+=("--tls-client-cert=")
+    flags+=("--verbose")
+    flags+=("-v")
 
     must_have_one_flag=()
     must_have_one_noun=()
@@ -955,6 +1041,8 @@ _restic_rebuild-index()
     flags+=("--repo=")
     two_word_flags+=("-r")
     flags+=("--tls-client-cert=")
+    flags+=("--verbose")
+    flags+=("-v")
 
     must_have_one_flag=()
     must_have_one_noun=()
@@ -1008,6 +1096,8 @@ _restic_restore()
     flags+=("--repo=")
     two_word_flags+=("-r")
     flags+=("--tls-client-cert=")
+    flags+=("--verbose")
+    flags+=("-v")
 
     must_have_one_flag=()
     must_have_one_noun=()
@@ -1057,6 +1147,8 @@ _restic_snapshots()
     flags+=("--repo=")
     two_word_flags+=("-r")
     flags+=("--tls-client-cert=")
+    flags+=("--verbose")
+    flags+=("-v")
 
     must_have_one_flag=()
     must_have_one_noun=()
@@ -1107,6 +1199,8 @@ _restic_tag()
     flags+=("--repo=")
     two_word_flags+=("-r")
     flags+=("--tls-client-cert=")
+    flags+=("--verbose")
+    flags+=("-v")
 
     must_have_one_flag=()
     must_have_one_noun=()
@@ -1146,6 +1240,8 @@ _restic_unlock()
     flags+=("--repo=")
     two_word_flags+=("-r")
     flags+=("--tls-client-cert=")
+    flags+=("--verbose")
+    flags+=("-v")
 
     must_have_one_flag=()
     must_have_one_noun=()
@@ -1183,17 +1279,20 @@ _restic_version()
     flags+=("--repo=")
     two_word_flags+=("-r")
     flags+=("--tls-client-cert=")
+    flags+=("--verbose")
+    flags+=("-v")
 
     must_have_one_flag=()
     must_have_one_noun=()
     noun_aliases=()
 }
 
-_restic()
+_restic_root_command()
 {
     last_command="restic"
     commands=()
     commands+=("backup")
+    commands+=("cache")
     commands+=("cat")
     commands+=("check")
     commands+=("diff")
@@ -1241,6 +1340,8 @@ _restic()
     flags+=("--repo=")
     two_word_flags+=("-r")
     flags+=("--tls-client-cert=")
+    flags+=("--verbose")
+    flags+=("-v")
 
     must_have_one_flag=()
     must_have_one_noun=()
@@ -1254,7 +1355,7 @@ __start_restic()
     if declare -F _init_completion >/dev/null 2>&1; then
         _init_completion -s || return
     else
-        __my_init_completion -n "=" || return
+        __restic_init_completion -n "=" || return
     fi
 
     local c=0
@@ -1269,7 +1370,7 @@ __start_restic()
     local last_command
     local nouns=()
 
-    __handle_word
+    __restic_handle_word
 }
 
 if [[ $(type -t compopt) = "builtin" ]]; then
diff --git a/doc/man/restic-backup.1 b/doc/man/restic-backup.1
index 101a428f5..26bd4c8b1 100644
--- a/doc/man/restic-backup.1
+++ b/doc/man/restic-backup.1
@@ -84,7 +84,7 @@ given as the arguments.
 .SH OPTIONS INHERITED FROM PARENT COMMANDS
 .PP
 \fB\-\-cacert\fP=[]
-    path to load root certificates from (default: use system certificates)
+    \fB\fCfile\fR to load root certificates from (default: use system certificates)
 
 .PP
 \fB\-\-cache\-dir\fP=""
@@ -134,6 +134,10 @@ given as the arguments.
 \fB\-\-tls\-client\-cert\fP=""
     path to a file containing PEM encoded TLS client certificate and private key
 
+.PP
+\fB\-v\fP, \fB\-\-verbose\fP[=0]
+    be verbose (specify \-\-verbose multiple times or level \fB\fCn\fR)
+
 
 .SH SEE ALSO
 .PP
diff --git a/doc/man/restic-cache.1 b/doc/man/restic-cache.1
new file mode 100644
index 000000000..bd351b6e5
--- /dev/null
+++ b/doc/man/restic-cache.1
@@ -0,0 +1,95 @@
+.TH "restic backup" "1" "Jan 2017" "generated by `restic generate`" "" 
+.nh
+.ad l
+
+
+.SH NAME
+.PP
+restic\-cache \- Operate on local cache directories
+
+
+.SH SYNOPSIS
+.PP
+\fBrestic cache [flags]\fP
+
+
+.SH DESCRIPTION
+.PP
+The "cache" command allows listing and cleaning local cache directories.
+
+
+.SH OPTIONS
+.PP
+\fB\-\-cleanup\fP[=false]
+    remove old cache directories
+
+.PP
+\fB\-h\fP, \fB\-\-help\fP[=false]
+    help for cache
+
+.PP
+\fB\-\-max\-age\fP=30
+    max age in \fB\fCdays\fR for cache directories to be considered old
+
+
+.SH OPTIONS INHERITED FROM PARENT COMMANDS
+.PP
+\fB\-\-cacert\fP=[]
+    \fB\fCfile\fR to load root certificates from (default: use system certificates)
+
+.PP
+\fB\-\-cache\-dir\fP=""
+    set the cache directory
+
+.PP
+\fB\-\-cleanup\-cache\fP[=false]
+    auto remove old cache directories
+
+.PP
+\fB\-\-json\fP[=false]
+    set output mode to JSON for commands that support it
+
+.PP
+\fB\-\-limit\-download\fP=0
+    limits downloads to a maximum rate in KiB/s. (default: unlimited)
+
+.PP
+\fB\-\-limit\-upload\fP=0
+    limits uploads to a maximum rate in KiB/s. (default: unlimited)
+
+.PP
+\fB\-\-no\-cache\fP[=false]
+    do not use a local cache
+
+.PP
+\fB\-\-no\-lock\fP[=false]
+    do not lock the repo, this allows some operations on read\-only repos
+
+.PP
+\fB\-o\fP, \fB\-\-option\fP=[]
+    set extended option (\fB\fCkey=value\fR, can be specified multiple times)
+
+.PP
+\fB\-p\fP, \fB\-\-password\-file\fP=""
+    read the repository password from a file (default: $RESTIC\_PASSWORD\_FILE)
+
+.PP
+\fB\-q\fP, \fB\-\-quiet\fP[=false]
+    do not output comprehensive progress report
+
+.PP
+\fB\-r\fP, \fB\-\-repo\fP=""
+    repository to backup to or restore from (default: $RESTIC\_REPOSITORY)
+
+.PP
+\fB\-\-tls\-client\-cert\fP=""
+    path to a file containing PEM encoded TLS client certificate and private key
+
+.PP
+\fB\-v\fP, \fB\-\-verbose\fP[=0]
+    be verbose (specify \-\-verbose multiple times or level \fB\fCn\fR)
+
+
+.SH SEE ALSO
+.PP
+\fBrestic(1)\fP
diff --git a/doc/man/restic-cat.1 b/doc/man/restic-cat.1
index d620c9c3d..238bc97a8 100644
--- a/doc/man/restic-cat.1
+++ b/doc/man/restic-cat.1
@@ -27,7 +27,7 @@ The "cat" command is used to print internal objects to stdout.
 .SH OPTIONS INHERITED FROM PARENT COMMANDS
 .PP
 \fB\-\-cacert\fP=[]
-    path to load root certificates from (default: use system certificates)
+    \fB\fCfile\fR to load root certificates from (default: use system certificates)
 
 .PP
 \fB\-\-cache\-dir\fP=""
@@ -77,6 +77,10 @@ The "cat" command is used to print internal objects to stdout.
 \fB\-\-tls\-client\-cert\fP=""
     path to a file containing PEM encoded TLS client certificate and private key
 
+.PP
+\fB\-v\fP, \fB\-\-verbose\fP[=0]
+    be verbose (specify \-\-verbose multiple times or level \fB\fCn\fR)
+
 
 .SH SEE ALSO
 .PP
diff --git a/doc/man/restic-check.1 b/doc/man/restic-check.1
index c75acb34d..d939fd6a8 100644
--- a/doc/man/restic-check.1
+++ b/doc/man/restic-check.1
@@ -48,7 +48,7 @@ repository and not use a local cache.
 .SH OPTIONS INHERITED FROM PARENT COMMANDS
 .PP
 \fB\-\-cacert\fP=[]
-    path to load root certificates from (default: use system certificates)
+    \fB\fCfile\fR to load root certificates from (default: use system certificates)
 
 .PP
 \fB\-\-cache\-dir\fP=""
@@ -98,6 +98,10 @@ repository and not use a local cache.
 \fB\-\-tls\-client\-cert\fP=""
     path to a file containing PEM encoded TLS client certificate and private key
 
+.PP
+\fB\-v\fP, \fB\-\-verbose\fP[=0]
+    be verbose (specify \-\-verbose multiple times or level \fB\fCn\fR)
+
 
 .SH SEE ALSO
 .PP
diff --git a/doc/man/restic-diff.1 b/doc/man/restic-diff.1
index e73d3588d..26f8595eb 100644
--- a/doc/man/restic-diff.1
+++ b/doc/man/restic-diff.1
@@ -18,6 +18,8 @@ restic\-diff \- Show differences between two snapshots
 The "diff" command shows differences from the first to the second snapshot. The
 first characters in each line display what has happened to a particular file or
 directory:
+
+.RS
 .IP \(bu 2
 The item was added
 .IP \(bu 2
@@ -26,6 +28,8 @@ U  The metadata (access mode, timestamps, ...) for the item was updated
 M  The file's content was modified
 T  The type was changed, e.g. a file was made a symlink
 
+.RE
+
 
 .SH OPTIONS
 .PP
@@ -40,7 +44,7 @@ T  The type was changed, e.g. a file was made a symlink
 .SH OPTIONS INHERITED FROM PARENT COMMANDS
 .PP
 \fB\-\-cacert\fP=[]
-    path to load root certificates from (default: use system certificates)
+    \fB\fCfile\fR to load root certificates from (default: use system certificates)
 
 .PP
 \fB\-\-cache\-dir\fP=""
@@ -90,6 +94,10 @@ T  The type was changed, e.g. a file was made a symlink
 \fB\-\-tls\-client\-cert\fP=""
     path to a file containing PEM encoded TLS client certificate and private key
 
+.PP
+\fB\-v\fP, \fB\-\-verbose\fP[=0]
+    be verbose (specify \-\-verbose multiple times or level \fB\fCn\fR)
+
 
 .SH SEE ALSO
 .PP
diff --git a/doc/man/restic-dump.1 b/doc/man/restic-dump.1
index b95ca85a6..e0c66df3f 100644
--- a/doc/man/restic-dump.1
+++ b/doc/man/restic-dump.1
@@ -44,7 +44,7 @@ repository.
 .SH OPTIONS INHERITED FROM PARENT COMMANDS
 .PP
 \fB\-\-cacert\fP=[]
-    path to load root certificates from (default: use system certificates)
+    \fB\fCfile\fR to load root certificates from (default: use system certificates)
 
 .PP
 \fB\-\-cache\-dir\fP=""
@@ -94,6 +94,10 @@ repository.
 \fB\-\-tls\-client\-cert\fP=""
     path to a file containing PEM encoded TLS client certificate and private key
 
+.PP
+\fB\-v\fP, \fB\-\-verbose\fP[=0]
+    be verbose (specify \-\-verbose multiple times or level \fB\fCn\fR)
+
 
 .SH SEE ALSO
 .PP
diff --git a/doc/man/restic-find.1 b/doc/man/restic-find.1
index 17504328b..09334bb58 100644
--- a/doc/man/restic-find.1
+++ b/doc/man/restic-find.1
@@ -60,7 +60,7 @@ repo.
 .SH OPTIONS INHERITED FROM PARENT COMMANDS
 .PP
 \fB\-\-cacert\fP=[]
-    path to load root certificates from (default: use system certificates)
+    \fB\fCfile\fR to load root certificates from (default: use system certificates)
 
 .PP
 \fB\-\-cache\-dir\fP=""
@@ -110,6 +110,10 @@ repo.
 \fB\-\-tls\-client\-cert\fP=""
     path to a file containing PEM encoded TLS client certificate and private key
 
+.PP
+\fB\-v\fP, \fB\-\-verbose\fP[=0]
+    be verbose (specify \-\-verbose multiple times or level \fB\fCn\fR)
+
 
 .SH SEE ALSO
 .PP
diff --git a/doc/man/restic-forget.1 b/doc/man/restic-forget.1
index b0988e46d..0546fac5b 100644
--- a/doc/man/restic-forget.1
+++ b/doc/man/restic-forget.1
@@ -46,6 +46,10 @@ data after 'forget' was run successfully, see the 'prune' command.
 \fB\-y\fP, \fB\-\-keep\-yearly\fP=0
     keep the last \fB\fCn\fR yearly snapshots
 
+.PP
+\fB\-\-keep\-within\fP=
+    keep snapshots that were created within \fB\fCduration\fR before the newest (e.g. 1y5m7d)
+
 .PP
 \fB\-\-keep\-tag\fP=[]
     keep snapshots with this \fB\fCtaglist\fR (can be specified multiple times)
@@ -90,7 +94,7 @@ data after 'forget' was run successfully, see the 'prune' command.
 .SH OPTIONS INHERITED FROM PARENT COMMANDS
 .PP
 \fB\-\-cacert\fP=[]
-    path to load root certificates from (default: use system certificates)
+    \fB\fCfile\fR to load root certificates from (default: use system certificates)
 
 .PP
 \fB\-\-cache\-dir\fP=""
@@ -140,6 +144,10 @@ data after 'forget' was run successfully, see the 'prune' command.
 \fB\-\-tls\-client\-cert\fP=""
     path to a file containing PEM encoded TLS client certificate and private key
 
+.PP
+\fB\-v\fP, \fB\-\-verbose\fP[=0]
+    be verbose (specify \-\-verbose multiple times or level \fB\fCn\fR)
+
 
 .SH SEE ALSO
 .PP
diff --git a/doc/man/restic-generate.1 b/doc/man/restic-generate.1
index 95a0105eb..35f0261e2 100644
--- a/doc/man/restic-generate.1
+++ b/doc/man/restic-generate.1
@@ -40,7 +40,7 @@ and the auto\-completion files for bash and zsh).
 .SH OPTIONS INHERITED FROM PARENT COMMANDS
 .PP
 \fB\-\-cacert\fP=[]
-    path to load root certificates from (default: use system certificates)
+    \fB\fCfile\fR to load root certificates from (default: use system certificates)
 
 .PP
 \fB\-\-cache\-dir\fP=""
@@ -90,6 +90,10 @@ and the auto\-completion files for bash and zsh).
 \fB\-\-tls\-client\-cert\fP=""
     path to a file containing PEM encoded TLS client certificate and private key
 
+.PP
+\fB\-v\fP, \fB\-\-verbose\fP[=0]
+    be verbose (specify \-\-verbose multiple times or level \fB\fCn\fR)
+
 
 .SH SEE ALSO
 .PP
diff --git a/doc/man/restic-init.1 b/doc/man/restic-init.1
index 8aa6d5a6a..7ca8feb64 100644
--- a/doc/man/restic-init.1
+++ b/doc/man/restic-init.1
@@ -27,7 +27,7 @@ The "init" command initializes a new repository.
 .SH OPTIONS INHERITED FROM PARENT COMMANDS
 .PP
 \fB\-\-cacert\fP=[]
-    path to load root certificates from (default: use system certificates)
+    \fB\fCfile\fR to load root certificates from (default: use system certificates)
 
 .PP
 \fB\-\-cache\-dir\fP=""
@@ -77,6 +77,10 @@ The "init" command initializes a new repository.
 \fB\-\-tls\-client\-cert\fP=""
     path to a file containing PEM encoded TLS client certificate and private key
 
+.PP
+\fB\-v\fP, \fB\-\-verbose\fP[=0]
+    be verbose (specify \-\-verbose multiple times or level \fB\fCn\fR)
+
 
 .SH SEE ALSO
 .PP
diff --git a/doc/man/restic-key.1 b/doc/man/restic-key.1
index a0f75491e..9f2ea7cce 100644
--- a/doc/man/restic-key.1
+++ b/doc/man/restic-key.1
@@ -23,11 +23,15 @@ The "key" command manages keys (passwords) for accessing the repository.
 \fB\-h\fP, \fB\-\-help\fP[=false]
     help for key
 
+.PP
+\fB\-\-new\-password\-file\fP=""
+    the file from which to load a new password
+
 
 .SH OPTIONS INHERITED FROM PARENT COMMANDS
 .PP
 \fB\-\-cacert\fP=[]
-    path to load root certificates from (default: use system certificates)
+    \fB\fCfile\fR to load root certificates from (default: use system certificates)
 
 .PP
 \fB\-\-cache\-dir\fP=""
@@ -77,6 +81,10 @@ The "key" command manages keys (passwords) for accessing the repository.
 \fB\-\-tls\-client\-cert\fP=""
     path to a file containing PEM encoded TLS client certificate and private key
 
+.PP
+\fB\-v\fP, \fB\-\-verbose\fP[=0]
+    be verbose (specify \-\-verbose multiple times or level \fB\fCn\fR)
+
 
 .SH SEE ALSO
 .PP
diff --git a/doc/man/restic-list.1 b/doc/man/restic-list.1
index 34599bc8c..b80771110 100644
--- a/doc/man/restic-list.1
+++ b/doc/man/restic-list.1
@@ -27,7 +27,7 @@ The "list" command allows listing objects in the repository based on type.
 .SH OPTIONS INHERITED FROM PARENT COMMANDS
 .PP
 \fB\-\-cacert\fP=[]
-    path to load root certificates from (default: use system certificates)
+    \fB\fCfile\fR to load root certificates from (default: use system certificates)
 
 .PP
 \fB\-\-cache\-dir\fP=""
@@ -77,6 +77,10 @@ The "list" command allows listing objects in the repository based on type.
 \fB\-\-tls\-client\-cert\fP=""
     path to a file containing PEM encoded TLS client certificate and private key
 
+.PP
+\fB\-v\fP, \fB\-\-verbose\fP[=0]
+    be verbose (specify \-\-verbose multiple times or level \fB\fCn\fR)
+
 
 .SH SEE ALSO
 .PP
diff --git a/doc/man/restic-ls.1 b/doc/man/restic-ls.1
index 1e3c8d4b4..e0e6a6a1f 100644
--- a/doc/man/restic-ls.1
+++ b/doc/man/restic-ls.1
@@ -46,7 +46,7 @@ The special snapshot\-ID "latest" can be used to list files and directories of t
 .SH OPTIONS INHERITED FROM PARENT COMMANDS
 .PP
 \fB\-\-cacert\fP=[]
-    path to load root certificates from (default: use system certificates)
+    \fB\fCfile\fR to load root certificates from (default: use system certificates)
 
 .PP
 \fB\-\-cache\-dir\fP=""
@@ -96,6 +96,10 @@ The special snapshot\-ID "latest" can be used to list files and directories of t
 \fB\-\-tls\-client\-cert\fP=""
     path to a file containing PEM encoded TLS client certificate and private key
 
+.PP
+\fB\-v\fP, \fB\-\-verbose\fP[=0]
+    be verbose (specify \-\-verbose multiple times or level \fB\fCn\fR)
+
 
 .SH SEE ALSO
 .PP
diff --git a/doc/man/restic-migrate.1 b/doc/man/restic-migrate.1
index 2c2ed06b5..3d46376f0 100644
--- a/doc/man/restic-migrate.1
+++ b/doc/man/restic-migrate.1
@@ -32,7 +32,7 @@ name is explicitly given, a list of migrations that can be applied is printed.
 .SH OPTIONS INHERITED FROM PARENT COMMANDS
 .PP
 \fB\-\-cacert\fP=[]
-    path to load root certificates from (default: use system certificates)
+    \fB\fCfile\fR to load root certificates from (default: use system certificates)
 
 .PP
 \fB\-\-cache\-dir\fP=""
@@ -82,6 +82,10 @@ name is explicitly given, a list of migrations that can be applied is printed.
 \fB\-\-tls\-client\-cert\fP=""
     path to a file containing PEM encoded TLS client certificate and private key
 
+.PP
+\fB\-v\fP, \fB\-\-verbose\fP[=0]
+    be verbose (specify \-\-verbose multiple times or level \fB\fCn\fR)
+
 
 .SH SEE ALSO
 .PP
diff --git a/doc/man/restic-mount.1 b/doc/man/restic-mount.1
index 4f5f58dec..1aea52325 100644
--- a/doc/man/restic-mount.1
+++ b/doc/man/restic-mount.1
@@ -88,7 +88,7 @@ For details please see the documentation for time.Format() at:
 .SH OPTIONS INHERITED FROM PARENT COMMANDS
 .PP
 \fB\-\-cacert\fP=[]
-    path to load root certificates from (default: use system certificates)
+    \fB\fCfile\fR to load root certificates from (default: use system certificates)
 
 .PP
 \fB\-\-cache\-dir\fP=""
@@ -138,6 +138,10 @@ For details please see the documentation for time.Format() at:
 \fB\-\-tls\-client\-cert\fP=""
     path to a file containing PEM encoded TLS client certificate and private key
 
+.PP
+\fB\-v\fP, \fB\-\-verbose\fP[=0]
+    be verbose (specify \-\-verbose multiple times or level \fB\fCn\fR)
+
 
 .SH SEE ALSO
 .PP
diff --git a/doc/man/restic-prune.1 b/doc/man/restic-prune.1
index d97d28ea6..e66e6736e 100644
--- a/doc/man/restic-prune.1
+++ b/doc/man/restic-prune.1
@@ -28,7 +28,7 @@ referenced and therefore not needed any more.
 .SH OPTIONS INHERITED FROM PARENT COMMANDS
 .PP
 \fB\-\-cacert\fP=[]
-    path to load root certificates from (default: use system certificates)
+    \fB\fCfile\fR to load root certificates from (default: use system certificates)
 
 .PP
 \fB\-\-cache\-dir\fP=""
@@ -78,6 +78,10 @@ referenced and therefore not needed any more.
 \fB\-\-tls\-client\-cert\fP=""
     path to a file containing PEM encoded TLS client certificate and private key
 
+.PP
+\fB\-v\fP, \fB\-\-verbose\fP[=0]
+    be verbose (specify \-\-verbose multiple times or level \fB\fCn\fR)
+
 
 .SH SEE ALSO
 .PP
diff --git a/doc/man/restic-rebuild-index.1 b/doc/man/restic-rebuild-index.1
index e6c9da3ee..db9999295 100644
--- a/doc/man/restic-rebuild-index.1
+++ b/doc/man/restic-rebuild-index.1
@@ -28,7 +28,7 @@ repository.
 .SH OPTIONS INHERITED FROM PARENT COMMANDS
 .PP
 \fB\-\-cacert\fP=[]
-    path to load root certificates from (default: use system certificates)
+    \fB\fCfile\fR to load root certificates from (default: use system certificates)
 
 .PP
 \fB\-\-cache\-dir\fP=""
@@ -78,6 +78,10 @@ repository.
 \fB\-\-tls\-client\-cert\fP=""
     path to a file containing PEM encoded TLS client certificate and private key
 
+.PP
+\fB\-v\fP, \fB\-\-verbose\fP[=0]
+    be verbose (specify \-\-verbose multiple times or level \fB\fCn\fR)
+
 
 .SH SEE ALSO
 .PP
diff --git a/doc/man/restic-restore.1 b/doc/man/restic-restore.1
index 767355b93..8562d9f2f 100644
--- a/doc/man/restic-restore.1
+++ b/doc/man/restic-restore.1
@@ -56,7 +56,7 @@ repository.
 .SH OPTIONS INHERITED FROM PARENT COMMANDS
 .PP
 \fB\-\-cacert\fP=[]
-    path to load root certificates from (default: use system certificates)
+    \fB\fCfile\fR to load root certificates from (default: use system certificates)
 
 .PP
 \fB\-\-cache\-dir\fP=""
@@ -106,6 +106,10 @@ repository.
 \fB\-\-tls\-client\-cert\fP=""
     path to a file containing PEM encoded TLS client certificate and private key
 
+.PP
+\fB\-v\fP, \fB\-\-verbose\fP[=0]
+    be verbose (specify \-\-verbose multiple times or level \fB\fCn\fR)
+
 
 .SH SEE ALSO
 .PP
diff --git a/doc/man/restic-snapshots.1 b/doc/man/restic-snapshots.1
index 994e85bba..13d8a153c 100644
--- a/doc/man/restic-snapshots.1
+++ b/doc/man/restic-snapshots.1
@@ -47,7 +47,7 @@ The "snapshots" command lists all snapshots stored in the repository.
 .SH OPTIONS INHERITED FROM PARENT COMMANDS
 .PP
 \fB\-\-cacert\fP=[]
-    path to load root certificates from (default: use system certificates)
+    \fB\fCfile\fR to load root certificates from (default: use system certificates)
 
 .PP
 \fB\-\-cache\-dir\fP=""
@@ -97,6 +97,10 @@ The "snapshots" command lists all snapshots stored in the repository.
 \fB\-\-tls\-client\-cert\fP=""
     path to a file containing PEM encoded TLS client certificate and private key
 
+.PP
+\fB\-v\fP, \fB\-\-verbose\fP[=0]
+    be verbose (specify \-\-verbose multiple times or level \fB\fCn\fR)
+
 
 .SH SEE ALSO
 .PP
diff --git a/doc/man/restic-tag.1 b/doc/man/restic-tag.1
index 14ca445d7..4874c57a3 100644
--- a/doc/man/restic-tag.1
+++ b/doc/man/restic-tag.1
@@ -58,7 +58,7 @@ When no snapshot\-ID is given, all snapshots matching the host, tag and path fil
 .SH OPTIONS INHERITED FROM PARENT COMMANDS
 .PP
 \fB\-\-cacert\fP=[]
-    path to load root certificates from (default: use system certificates)
+    \fB\fCfile\fR to load root certificates from (default: use system certificates)
 
 .PP
 \fB\-\-cache\-dir\fP=""
@@ -108,6 +108,10 @@ When no snapshot\-ID is given, all snapshots matching the host, tag and path fil
 \fB\-\-tls\-client\-cert\fP=""
     path to a file containing PEM encoded TLS client certificate and private key
 
+.PP
+\fB\-v\fP, \fB\-\-verbose\fP[=0]
+    be verbose (specify \-\-verbose multiple times or level \fB\fCn\fR)
+
 
 .SH SEE ALSO
 .PP
diff --git a/doc/man/restic-unlock.1 b/doc/man/restic-unlock.1
index f08733462..09c55c43b 100644
--- a/doc/man/restic-unlock.1
+++ b/doc/man/restic-unlock.1
@@ -31,7 +31,7 @@ The "unlock" command removes stale locks that have been created by other restic
 .SH OPTIONS INHERITED FROM PARENT COMMANDS
 .PP
 \fB\-\-cacert\fP=[]
-    path to load root certificates from (default: use system certificates)
+    \fB\fCfile\fR to load root certificates from (default: use system certificates)
 
 .PP
 \fB\-\-cache\-dir\fP=""
@@ -81,6 +81,10 @@ The "unlock" command removes stale locks that have been created by other restic
 \fB\-\-tls\-client\-cert\fP=""
     path to a file containing PEM encoded TLS client certificate and private key
 
+.PP
+\fB\-v\fP, \fB\-\-verbose\fP[=0]
+    be verbose (specify \-\-verbose multiple times or level \fB\fCn\fR)
+
 
 .SH SEE ALSO
 .PP
diff --git a/doc/man/restic-version.1 b/doc/man/restic-version.1
index fad3190d4..135e27e60 100644
--- a/doc/man/restic-version.1
+++ b/doc/man/restic-version.1
@@ -28,7 +28,7 @@ and the version of this software.
 .SH OPTIONS INHERITED FROM PARENT COMMANDS
 .PP
 \fB\-\-cacert\fP=[]
-    path to load root certificates from (default: use system certificates)
+    \fB\fCfile\fR to load root certificates from (default: use system certificates)
 
 .PP
 \fB\-\-cache\-dir\fP=""
@@ -78,6 +78,10 @@ and the version of this software.
 \fB\-\-tls\-client\-cert\fP=""
     path to a file containing PEM encoded TLS client certificate and private key
 
+.PP
+\fB\-v\fP, \fB\-\-verbose\fP[=0]
+    be verbose (specify \-\-verbose multiple times or level \fB\fCn\fR)
+
 
 .SH SEE ALSO
 .PP
diff --git a/doc/man/restic.1 b/doc/man/restic.1
index b1f6b4ab4..4a8e7ff01 100644
--- a/doc/man/restic.1
+++ b/doc/man/restic.1
@@ -22,7 +22,7 @@ directories in an encrypted repository stored on different backends.
 .SH OPTIONS
 .PP
 \fB\-\-cacert\fP=[]
-    path to load root certificates from (default: use system certificates)
+    \fB\fCfile\fR to load root certificates from (default: use system certificates)
 
 .PP
 \fB\-\-cache\-dir\fP=""
@@ -76,7 +76,11 @@ directories in an encrypted repository stored on different backends.
 \fB\-\-tls\-client\-cert\fP=""
     path to a file containing PEM encoded TLS client certificate and private key
 
+.PP
+\fB\-v\fP, \fB\-\-verbose\fP[=0]
+    be verbose (specify \-\-verbose multiple times or level \fB\fCn\fR)
+
 
 .SH SEE ALSO
 .PP
-\fBrestic\-backup(1)\fP, \fBrestic\-cat(1)\fP, \fBrestic\-check(1)\fP, \fBrestic\-diff(1)\fP, \fBrestic\-dump(1)\fP, \fBrestic\-find(1)\fP, \fBrestic\-forget(1)\fP, \fBrestic\-generate(1)\fP, \fBrestic\-init(1)\fP, \fBrestic\-key(1)\fP, \fBrestic\-list(1)\fP, \fBrestic\-ls(1)\fP, \fBrestic\-migrate(1)\fP, \fBrestic\-mount(1)\fP, \fBrestic\-prune(1)\fP, \fBrestic\-rebuild\-index(1)\fP, \fBrestic\-restore(1)\fP, \fBrestic\-snapshots(1)\fP, \fBrestic\-tag(1)\fP, \fBrestic\-unlock(1)\fP, \fBrestic\-version(1)\fP
+\fBrestic\-backup(1)\fP, \fBrestic\-cache(1)\fP, \fBrestic\-cat(1)\fP, \fBrestic\-check(1)\fP, \fBrestic\-diff(1)\fP, \fBrestic\-dump(1)\fP, \fBrestic\-find(1)\fP, \fBrestic\-forget(1)\fP, \fBrestic\-generate(1)\fP, \fBrestic\-init(1)\fP, \fBrestic\-key(1)\fP, \fBrestic\-list(1)\fP, \fBrestic\-ls(1)\fP, \fBrestic\-migrate(1)\fP, \fBrestic\-mount(1)\fP, \fBrestic\-prune(1)\fP, \fBrestic\-rebuild\-index(1)\fP, \fBrestic\-restore(1)\fP, \fBrestic\-snapshots(1)\fP, \fBrestic\-tag(1)\fP, \fBrestic\-unlock(1)\fP, \fBrestic\-version(1)\fP
diff --git a/doc/zsh-completion.zsh b/doc/zsh-completion.zsh
index cd979180d..740d1c9d7 100644
--- a/doc/zsh-completion.zsh
+++ b/doc/zsh-completion.zsh
@@ -7,7 +7,7 @@ case $state in
   level1)
     case $words[1] in
       restic)
-        _arguments '1: :(backup cat check diff dump find forget generate help init key list ls migrate mount options prune rebuild-index restore snapshots tag unlock version)'
+        _arguments '1: :(backup cache cat check diff dump find forget generate help init key list ls migrate mount options prune rebuild-index restore snapshots tag unlock version)'
       ;;
       *)
         _arguments '*: :_files'