bug#17937: Getting gnu touch and gnu date to play nicely

[Bob Proulx]

address@hidden wrote:
> -d, --date=STRING
> parse STRING and use it instead of current time

The syntax of the command line is documented mostly the same for all
of the tools.  The challenge is to document these in the online --help
documentation (also used for the man page) succinctly and yet still
accurately convey the needed information.  The above is the standard
way all of the GNU coreutils uses to document options.

This style of syntax documentation is further described in the "Common
options" section of the manual.  If you have GNU Coreutils installed
then this will be available on your system directly with:

  info coreutils 'Common options'

An online web copy of the most current version is here:

  https://www.gnu.org/software/coreutils/manual/coreutils.html#Common-options

> ~$ touch -d="now" file
> touch: invalid date format ‘=now’

Literally the -d option takes one argument.  In the above you are
passing the "=now" option to the touch -d option.  This is reflected
in the error message.  Notice that it says "=now" including the '='
character?

The single letter option is the traditional way to specify Unix
options.  GNU extends with this long names for options.  Long options
are nice because they are self-documenting for scripts.  And by
avoiding the single letter namespace they can be created without
consuming the very few single letters available.  In order to specify
long options we use two dashes "--" to signify that a long option is
coming next.  Literally that is one '-' to start option processing on
the string and another '-' to indicate that it is a long option.

But then with long options there is a problem.  When does the long
option stop?  We use an equal '=' character to signify the end of the
long string option name.  The '-' and '=' are bookends for the option
name.  The value occurs after the '='.  But that is only when using
the long option syntax.  These are equivalent

  $ touch -d now foo
  $ touch --date=now foo

> ~$ touch -d="$(date)" file
> touch: invalid date format ‘=Fri Jul 4 06:05:22 EDT 2014’
> ~$ touch -d="$(date -R)" file
> touch: invalid date format ‘=Fri, 04 Jul 2014 06:05:30 -0400’
> ~$ touch -d="$(date -u)" file
> touch: invalid date format ‘=Fri Jul 4 10:05:33 UTC 2014’

Notice the '=' in each of the error messages.  If you had tried the
same using date you would see the same problem.

  $ date -d=now
  date: invalid date ‘=now’

However if you use the expected syntax then date works okay.

  $ date -d now
  $ date --date=now

> Is it possible that touch could get an update to support the common output
> provided by the gnu version of `date`?

Of course by now you already know that it does and the problem was
simply one of usage with an extra '=' character. :-)

But let me take this opportunity to point out that 'touch' is one the
commands standardized by POSIX and this includes standardizing the -d
option.  But note that while GNU extends the capabilities of many
utilities and here date parsing quite a large amount the other
operating systems do not include those extensions.  Other operating
systems do what they have always done before.  POSIX is standardizing
on the portable behavior between operating systems.  This means that
if you use the portable syntax that it will be ensured to operate the
same everywhere.  Therefore I recommend using the portable syntax for
the least amount of problems.

  http://pubs.opengroup.org/onlinepubs/9699919799/utilities/touch.html

The syntax specified there is YYYY-MM-DDThh:mm:SS[.frac][tz] or the
form with a ',' for the radix mark and many examples are included in
that reference.  Therefore I recommend using the same syntax.

  $ date +%FT%T.%N%z
  2014-07-04T14:00:10.142621255-0600

And nicely the above is also the same as --iso=8601=ns option.

  $ date --iso-8601=ns
  2014-07-04T14:00:19,278445062-0600

If that syntax is used then touch is happy.  I mention that since you
were using date's output as input to touch that it is that format
which would be best.

  $ touch -d $(date +%FT%T.%N%z) foo

  $ touch -d $(date --iso-8601=ns) foo

Obviously there isn't much reason to use date like above with touch
since that is the default behavior for touch without it.  I am sure
the reason to use date was to do date calculations.  I was just
keeping it simple for the above example.  But I realize that in a real
example it should include some type of date calculation.

  $ touch -d $(date -d "last thursday 12:00" +%FT%T.%N%z) foo

As in the FAQ entry on date it is good to always perform date
calculations either at a specific time such as noon to avoid Daylight
Savings Time issues or use UTC to avoid DST issues.  Here is the date
FAQ entry.

  
https://www.gnu.org/software/coreutils/faq/#The-date-command-is-not-working-right_002e

Hope this discussion helps,
Bob