From 7fb49a48d140cf7ed3c99d7c6c551a1262151499 Mon Sep 17 00:00:00 2001
From: He Xiaoqiao <hexiaoqiao@apache.org>
Date: Sun, 14 Mar 2021 18:09:50 +0800
Subject: [PATCH] HADOOP-17585. Correct timestamp format in the docs for the
 touch command. Contributed by Stephen O'Donnell.

(cherry picked from commit b1dc6c40a0695fedd8269a2a30a74da43e1d0ae7)
---
 .../java/org/apache/hadoop/fs/shell/TouchCommands.java | 10 ++++++----
 .../hadoop-common/src/site/markdown/FileSystemShell.md |  8 ++++----
 .../hadoop-common/src/test/resources/testConf.xml      |  6 +++---
 3 files changed, 13 insertions(+), 11 deletions(-)

diff --git a/hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/fs/shell/TouchCommands.java b/hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/fs/shell/TouchCommands.java
index 66b9059c05f..d67e8f9d6b4 100644
--- a/hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/fs/shell/TouchCommands.java
+++ b/hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/fs/shell/TouchCommands.java
@@ -102,8 +102,8 @@ public class TouchCommands extends FsCommand {
     public static final String NAME = "touch";
     public static final String USAGE = "[-" + OPTION_CHANGE_ONLY_ACCESS_TIME
         + "] [-" + OPTION_CHANGE_ONLY_MODIFICATION_TIME + "] [-"
-        + OPTION_USE_TIMESTAMP + " TIMESTAMP ] [-" + OPTION_DO_NOT_CREATE_FILE
-        + "] <path> ...";
+        + OPTION_USE_TIMESTAMP + " TIMESTAMP (yyyyMMdd:HHmmss) ] "
+        + "[-" + OPTION_DO_NOT_CREATE_FILE + "] <path> ...";
     public static final String DESCRIPTION =
         "Updates the access and modification times of the file specified by the"
             + " <path> to the current time. If the file does not exist, then a zero"
@@ -114,7 +114,8 @@ public class TouchCommands extends FsCommand {
             + OPTION_CHANGE_ONLY_MODIFICATION_TIME
             + " Change only the modification time \n" + "-"
             + OPTION_USE_TIMESTAMP + " TIMESTAMP"
-            + " Use specified timestamp (in format yyyyMMddHHmmss) instead of current time \n"
+            + " Use specified timestamp instead of current time\n"
+            + " TIMESTAMP format yyyyMMdd:HHmmss\n"
             + "-" + OPTION_DO_NOT_CREATE_FILE + " Do not create any files";
 
     private boolean changeModTime = false;
@@ -183,7 +184,8 @@ public class TouchCommands extends FsCommand {
           time = dateFormat.parse(timestamp).getTime();
         } catch (ParseException e) {
           throw new IllegalArgumentException(
-              "Unable to parse the specified timestamp " + timestamp, e);
+              "Unable to parse the specified timestamp "+ timestamp
+              + ". The expected format is " + dateFormat.toPattern(), e);
         }
       }
       if (changeModTime ^ changeAccessTime) {
diff --git a/hadoop-common-project/hadoop-common/src/site/markdown/FileSystemShell.md b/hadoop-common-project/hadoop-common/src/site/markdown/FileSystemShell.md
index 09a4cc28499..4f58e507b7d 100644
--- a/hadoop-common-project/hadoop-common/src/site/markdown/FileSystemShell.md
+++ b/hadoop-common-project/hadoop-common/src/site/markdown/FileSystemShell.md
@@ -757,7 +757,7 @@ timestamp of that URI.
 
 * Use -a option to change only the access time
 * Use -m option to change only the modification time
-* Use -t option to specify timestamp (in format yyyyMMddHHmmss) instead of current time
+* Use -t option to specify timestamp (in format yyyyMMdd:HHmmss) instead of current time
 * Use -c option to not create file if it does not exist
 
 The timestamp format is as follows
@@ -767,13 +767,13 @@ The timestamp format is as follows
 * HH Two digit hour of the day using 24 hour notation (e.g. 23 stands for 11 pm, 11 stands for 11 am)
 * mm Two digit minutes of the hour
 * ss Two digit seconds of the minute
-e.g. 20180809230000 represents August 9th 2018, 11pm
+e.g. 20180809:230000 represents August 9th 2018, 11pm
 
 Example:
 
 * `hadoop fs -touch pathname`
-* `hadoop fs -touch -m -t 20180809230000 pathname`
-* `hadoop fs -touch -t 20180809230000 pathname`
+* `hadoop fs -touch -m -t 20180809:230000 pathname`
+* `hadoop fs -touch -t 20180809:230000 pathname`
 * `hadoop fs -touch -a pathname`
 
 Exit Code: Returns 0 on success and -1 on error.
diff --git a/hadoop-common-project/hadoop-common/src/test/resources/testConf.xml b/hadoop-common-project/hadoop-common/src/test/resources/testConf.xml
index 1874621e1b5..6ebb9c461ba 100644
--- a/hadoop-common-project/hadoop-common/src/test/resources/testConf.xml
+++ b/hadoop-common-project/hadoop-common/src/test/resources/testConf.xml
@@ -819,7 +819,7 @@
       <comparators>
         <comparator>
           <type>RegexpComparator</type>
-          <expected-output>^-touch \[-a\] \[-m\] \[-t TIMESTAMP \] \[-c\] &lt;path&gt; \.\.\. :( )*</expected-output>
+          <expected-output>^-touch \[-a\] \[-m\] \[-t TIMESTAMP \(yyyyMMdd\:HHmmss\) \] \[-c\] &lt;path&gt; \.\.\. :( )*</expected-output>
         </comparator>
         <comparator>
           <type>RegexpComparator</type>
@@ -847,11 +847,11 @@
         </comparator>
         <comparator>
           <type>RegexpComparator</type>
-          <expected-output>^\s*-t\s+TIMESTAMP\s+Use specified timestamp \(in format yyyyMMddHHmmss\) instead of</expected-output>
+          <expected-output>^\s*-t\s+TIMESTAMP\s+Use specified timestamp instead of current time( )*</expected-output>
         </comparator>
         <comparator>
           <type>RegexpComparator</type>
-          <expected-output>^\s*current time( )*</expected-output>
+          <expected-output>^\s*TIMESTAMP format yyyyMMdd\:HHmmss</expected-output>
         </comparator>
         <comparator>
           <type>RegexpComparator</type>