HADOOP-6375. Sync documentation for FsShell du with its implementation.

Contributed by Todd Lipcon


git-svn-id: https://svn.apache.org/repos/asf/hadoop/common/trunk@883206 13f79535-47bb-0310-9956-ffa450edef68

CHANGES.txt

@@ -1162,6 +1162,9 @@ Release 0.21.0 - Unreleased
     HADOOP-6347. run-test-core-fault-inject runs a test case twice if
     -Dtestcase is set (cos)
 
+    HADOOP-6375. Sync documentation for FsShell du with its implementation.
+    (Todd Lipcon via cdouglas)
+
 Release 0.20.2 - Unreleased
 
   NEW FEATURES

src/docs/src/documentation/content/xdocs/file_system_shell.xml

@@ -191,10 +191,16 @@
 		<section>
 			<title>du</title>
 			<p>
-				<code>Usage: hdfs dfs -du URI [URI &#x2026;]</code>
+				<code>Usage: hdfs dfs -du [-s] [-h] URI [URI &#x2026;]</code>
 			</p>
 			<p>
-	     Displays aggregate length of  files contained in the directory or the length of a file in case its just a file.<br/>
+	     Displays sizes of files and directories contained in the given directory or the length of a file in case its just a file.</p>
+             <p>Options:</p>
+             <ul>
+             <li>The <code>-s</code> option will result in an aggregate summary of file lengths being displayed, rather than the individual files.</li>
+             <li>The <code>-h</code> option will format file sizes in a &quot;human-readable&quot; fashion (e.g 64.0m instead of 67108864)</li>
+             </ul>
+             <p>
 	     Example:<br/><code>hdfs dfs -du /user/hadoop/dir1 /user/hadoop/file1 hdfs://nn.example.com/user/hadoop/dir1</code><br/>
 	     Exit Code:<br/><code> Returns 0 on success and -1 on error. </code><br/></p>
 		</section>
@@ -206,7 +212,7 @@
 				<code>Usage: hdfs dfs -dus &lt;args&gt;</code>
 			</p>
 			<p>
-	    Displays a summary of file lengths.
+	    Displays a summary of file lengths. This is an alternate form of <code>hdfs dfs -du -s</code>.
 	   </p>
 		</section>
 		

src/java/org/apache/hadoop/fs/FsShell.java

@@ -1339,7 +1339,7 @@ public class FsShell extends Configured implements Tool {
     String summary = "hadoop fs is the command to execute fs commands. " +
       "The full syntax is: \n\n" +
       "hadoop fs [-fs <local | file system URI>] [-conf <configuration file>]\n\t" +
-      "[-D <property=value>] [-ls <path>] [-lsr <path>] [-df [<path>]] [-du <path>]\n\t" + 
+      "[-D <property=value>] [-ls <path>] [-lsr <path>] [-df [<path>]] [-du [-s] [-h] <path>]\n\t" +
       "[-dus <path>] [-mv <src> <dst>] [-cp <src> <dst>] [-rm [-skipTrash] <src>]\n\t" + 
       "[-rmr [-skipTrash] <src>] [-put <localsrc> ... <dst>] [-copyFromLocal <localsrc> ... <dst>]\n\t" +
       "[-moveFromLocal <localsrc> ... <dst>] [" + 
@@ -1389,17 +1389,20 @@ public class FsShell extends Configured implements Tool {
       "\t\tIf the filesystem has multiple partitions, and no path to a particular partition\n"+
       "\t\tis specified, then the status of the root partitions will be shown.\n";
 
-    String du = "-du <path>: \tShow the amount of space, in bytes, used by the files that \n" +
-      "\t\tmatch the specified file pattern.  Equivalent to the unix\n" + 
-      "\t\tcommand \"du -sb <path>/*\" in case of a directory, \n" +
-      "\t\tand to \"du -b <path>\" in case of a file.\n" +
+    String du = "-du [-s] [-h] <path>: \tShow the amount of space, in bytes, used by the files that \n" +
+      "\t\tmatch the specified file pattern. The following flags are optional:\n" +
+      "\t\t  -s   Rather than showing the size of each individual file that\n" +
+      "\t\t       matches the pattern, shows the total (summary) size.\n" +
+      "\t\t  -h   Formats the sizes of files in a human-readable fashion\n" +
+      "\t\t       rather than a number of bytes.\n" +
+      "\n" + 
+      "\t\tNote that, even without the -s option, this only shows size summaries\n" +
+      "\t\tone level deep into a directory.\n" +
       "\t\tThe output is in the form \n" + 
-      "\t\t\tname(full path) size (in bytes)\n"; 
+      "\t\t\tsize\tname(full path)\n"; 
 
     String dus = "-dus <path>: \tShow the amount of space, in bytes, used by the files that \n" +
-      "\t\tmatch the specified file pattern.  Equivalent to the unix\n" + 
-      "\t\tcommand \"du -sb\"  The output is in the form \n" + 
-      "\t\t\tname(full path) size (in bytes)\n"; 
+      "\t\tmatch the specified file pattern. This is equivalent to -du -s above.\n";
     
     String mv = "-mv <src> <dst>:   Move files that match the specified file pattern <src>\n" +
       "\t\tto a destination <dst>.  When moving multiple files, the \n" +
@@ -1744,7 +1747,7 @@ public class FsShell extends Configured implements Tool {
       System.err.println("           [-ls <path>]");
       System.err.println("           [-lsr <path>]");
       System.err.println("           [-df [<path>]]");
-      System.err.println("           [-du <path>]");
+      System.err.println("           [-du [-s] [-h] <path>]");
       System.err.println("           [-dus <path>]");
       System.err.println("           [" + Count.USAGE + "]");
       System.err.println("           [-mv <src> <dst>]");