Add --map-user --map-group --map-uid and --map-gid options to restore.

[bup.git] / Documentation / bup-ls.md

diff --git a/Documentation/bup-ls.md b/Documentation/bup-ls.md
index cef01be05210827d18c33ddfaf4bcd8bfb877e72..359d91486a3a088e3f8b8dc79f9c9f3ac57932b3 100644 (file)
--- a/Documentation/bup-ls.md
+++ b/Documentation/bup-ls.md
@@ -8,7 +8,7 @@ bup-ls - list the contents of a bup repository
 
 # SYNOPSIS
 
-bup ls [-s] [-a] <paths...>
+bup ls [-s] [-a] \<paths...\>
 
 # DESCRIPTION
 
@@ -21,6 +21,13 @@ the `-n` option in `bup save`), the next level is the date
 of the backup, and subsequent levels correspond to files in
 the backup.
 
+When `bup ls` is asked to output on a tty, it formats its output
+in columns so that it can list as much as possible in as few lines
+as possible. However, when `bup ls` is asked to output to something
+other than a tty (say you pipe the output to another command, or you
+redirect it to a file), it will output one file name per line. This
+makes the listing easier to parse with external tools.
+
 Note that `bup ls` doesn't show hidden files by default and one needs to use
 the `-a` option to show them. Files are hidden when their name begins with a
 dot. For example, on the topmost level, the special directories named `.commit`
@@ -31,12 +38,18 @@ you can view its contents using `bup join` or `git show`.
 
 # OPTIONS
 
--s, --hash
+-s, \--hash
 :   show hash for each file/directory.
 
--a, --all
+-a, \--all
 :   show hidden files.
 
+-l
+:   show file sizes.
+
+\--human-readable
+:   print human readable file sizes (i.e. 3.9K, 4.7M)
+
 # EXAMPLE
 
     bup ls /myserver/latest/etc/profile