Merge pull request #554 from ThomasWaldmann/update-docs

update docs / make them more clear about -v

docs/quickstart.rst

@@ -46,7 +46,7 @@ A step by step example
 
 3. The next day create a new archive called *Tuesday*::
 
-    $ borg create --stats /mnt/backup::Tuesday ~/src ~/Documents
+    $ borg create -v --stats /mnt/backup::Tuesday ~/src ~/Documents
 
    This backup will be a lot quicker and a lot smaller since only new never
    before seen data is stored. The ``--stats`` option causes |project_name| to
@@ -101,7 +101,7 @@ certain number of old archives::
 
     # Backup all of /home and /var/www except a few
     # excluded directories
-    borg create --stats                             \
+    borg create -v --stats                          \
         $REPOSITORY::`hostname`-`date +%Y-%m-%d`    \
         /home                                       \
         /var/www                                    \

docs/usage.rst

@@ -29,6 +29,10 @@ Log levels: DEBUG < INFO < WARNING < ERROR < CRITICAL
 While you can set misc. log levels, do not expect that every command will
 give different output on different log levels - it's just a possibility.
 
+..warning:: While some options (like --stats or --list) will emit more
+informational messages, you have to use INFO (or lower) log level to make
+them show up in log output. Use `-v` or a logging configuration.
+
 Return codes
 ~~~~~~~~~~~~
 
@@ -269,7 +273,7 @@ Examples
     $ borg extract /mnt/backup::my-files
 
     # Extract entire archive and list files while processing
-    $ borg extract -v /mnt/backup::my-files
+    $ borg extract -v --list /mnt/backup::my-files
 
     # Extract the "src" directory
     $ borg extract /mnt/backup::my-files home/USERNAME/src
@@ -453,7 +457,7 @@ Here are misc. notes about topics that are maybe not covered in enough detail in
 Item flags
 ~~~~~~~~~~
 
-`borg create -v` outputs a verbose list of all files, directories and other
+`borg create -v --list` outputs a verbose list of all files, directories and other
 file system items it considered (no matter whether they had content changes
 or not). For each item, it prefixes a single-letter flag that indicates type
 and/or status of the item.