bug#55401: date man page
On 14/05/2022 01:42, Pádraig Brady wrote:
On 13/05/2022 20:10, t0th wrote:
Man page of date command should make explicit that -d and -r options are
mutually exclusive.
Right. More accurately, we might have a sentence to say that:
"All options to specify the date to display are mutually exclusive.
I.e.: --date, --file, --reference, --resolution".
I've pushed the attached 2 patches
to document the current situation at least.
cheers,
Padraig
From b09a23ec3f20003729b652ff1141f76de5e29e7f Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?P=C3=A1draig=20Brady?=
Date: Sun, 24 Jul 2022 20:49:29 +0100
Subject: [PATCH] doc: date: clarify which options are mutually exclusive
* src/date.c (usage): Specify that --date, --file, --reference,
and --resolution are mutually exclusive.
* doc/coreutils.texi (Options for date): Likewise.
Addresses https://bugs.gnu.org/55401
---
doc/coreutils.texi | 4
src/date.c | 5 +
2 files changed, 9 insertions(+)
diff --git a/doc/coreutils.texi b/doc/coreutils.texi
index e0c87d1ad..53257f7d9 100644
--- a/doc/coreutils.texi
+++ b/doc/coreutils.texi
@@ -16426,6 +16426,10 @@ relative to Universal Time rather than to the local time zone.
The program accepts the following options. Also see @ref{Common options}.
Except for @option{-u}, these options are all GNU extensions to POSIX.
+All options that specify the date to display are mutually exclusive.
+I.e.: @option{--date}, @option{--file}, @option{--reference},
+@option{--resolution}.
+
@table @samp
@item -d @var{datestr}
diff --git a/src/date.c b/src/date.c
index 7f2ac801d..ff5c548c0 100644
--- a/src/date.c
+++ b/src/date.c
@@ -183,6 +183,11 @@ With -s, or with [MMDDhhmm[[CC]YY][.ss]], set the date and time.\n\
fputs (VERSION_OPTION_DESCRIPTION, stdout);
fputs (_("\
\n\
+All options that specify the date to display are mutually exclusive.\n\
+I.e.: --date, --file, --reference, --resolution.\n\
+"), stdout);
+ fputs (_("\
+\n\
FORMAT controls the output. Interpreted sequences are:\n\
\n\
%% a literal %\n\
--
2.26.2
From 854e0351216869b8e79391e08b156127d1508beb Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?P=C3=A1draig=20Brady?=
Date: Sun, 24 Jul 2022 19:24:18 +0100
Subject: [PATCH] date: --debug: diagnose discarded -d or -s options
* src/date.c: (main): Track and diagnose whether any
-d or -s options are dropped, as users may think
multiple options are supported, given they can be relative.
* tests/misc/date-debug.sh: Add a test case.
* NEWS: Mention the improvement.
---
NEWS | 5 +
src/date.c | 12
tests/misc/date-debug.sh | 10 ++
3 files changed, 27 insertions(+)
diff --git a/NEWS b/NEWS
index b5b8990f8..3113d4236 100644
--- a/NEWS
+++ b/NEWS
@@ -36,6 +36,11 @@ GNU coreutils NEWS-*- outline -*-
factor now accepts the --exponents (-h) option to print factors
in the form p^e, rather than repeating the prime p, e times.
+** Improvements
+
+ date --debug now diagnoses if multiple --date or --set options are
+ specified, as only the last specified is significant in that case.
+
* Noteworthy changes in release 9.1 (2022-04-15) [stable]
diff --git a/src/date.c b/src/date.c
index 9a282e2f5..7f2ac801d 100644
--- a/src/date.c
+++ b/src/date.c
@@ -403,6 +403,8 @@ main (int argc, char **argv)
char *reference = NULL;
struct stat refstats;
bool ok;
+ bool discarded_datestr = false;
+ bool discarded_set_datestr = false;
initialize_main (, );
set_program_name (argv[0]);
@@ -420,6 +422,8 @@ main (int argc, char **argv)
switch (optc)
{
case 'd':
+ if (datestr)
+discarded_datestr = true;
datestr = optarg;
break;
case DEBUG_DATE_PARSING_OPTION:
@@ -469,6 +473,8 @@ main (int argc, char **argv)
new_format = rfc_email_format;
break;
case 's':
+ if (set_datestr)
+discarded_set_datestr = true;
set_datestr = optarg;
set_date = true;
break;
@@ -511,6 +517,12 @@ main (int argc, char **argv)
usage (EXIT_FAILURE);
}
+ if (discarded_datestr && (parse_datetime_flags & PARSE_DATETIME_DEBUG))
+error (0, 0, _("only using last of multiple -d options"));
+
+ if (discarded_set_datestr && (parse_datetime_flags & PARSE_DATETIME_DEBUG))
+error (0, 0, _("only using last of multiple -s options"));
+
if (optind < argc)
{
if (optind + 1 < argc)
diff --git a/tests/misc/date-debug.sh b/tests/misc/date-debug.sh
index 0b5217611..5c38dee41 100755
--- a/tests/misc/date-debug.sh
+++ b/tests/misc/date-debug.sh
@@ -298,4 +298,14 @@ sed '1s/(Y-M-D) [0-9][0-9][0-9][0-9]-/(Y-M-D) -/' out9_t > out9 \
compare exp9 out9 || fail=1
+# Diagnose discarded -d arguments
+echo 'date: only using last of multiple -d options' > exp10 \
+|| framework_failure_
+cat exp9 >> exp10 || framework_failure_
+date -u
bug#55401: date man page
On 13/05/2022 20:10, t0th wrote:
Man page of date command should make explicit that -d and -r options are
mutually exclusive.
Right. More accurately, we might have a sentence to say that:
"All options to specify the date to display are mutually exclusive.
I.e.: --date, --file, --reference, --resolution".
However...
date -d -3 minutes -r tmp.txt "+%Y%m%d_%H%M"
date: the options to specify dates for printing are mutually exclusive
As you've seen, one might expect to be able to combine, as -d can be relative.
So theoretically we could support this (with the attached),
to honor the relative adjustment, but give precedence to a non relative date.
$ src/date -r src/ls.c -d '-3 minutes'
Fri 15 Apr 2022 16:30:53 IST
$ src/date -r src/ls.c -d '1/1/2022'
Sat 01 Jan 2022 00:00:00 GMT
In fact touch(1) behaves like this, which suggests date(1) should also.
From the info docs for the touch --reference option:
"--reference
Use the times of the reference FILE instead of the current time.
If this option is combined with the --date=TIME
(-d TIME) option, the reference FILES's time is
the origin for any relative TIMEs given, but is otherwise ignored."
BTW, one might also expect that multiple -d options might combine like this,
however currently we silently ignore multiple -d (or -s) options.
The attached also at least warns about this with --debug:
$ date --debug -d '15/4/2022' -d '-3 minutes'
date: discarding previous -d: ‘15/4/2022’
date: parsed relative part: -3 minutes
...
cheers,
Pádraigdiff --git a/doc/coreutils.texi b/doc/coreutils.texi
index 7bca37b71..ae6ec4def 100644
--- a/doc/coreutils.texi
+++ b/doc/coreutils.texi
@@ -16058,7 +16058,8 @@ is not set. @xref{TZ Variable,, Specifying the Time Zone with
@cindex formatting times
If given an argument that starts with a @samp{+}, @command{date} prints the
current date and time (or the date and time specified by the
-@option{--date} option, see below) in the format defined by that argument,
+@option{--date}, @option{--file}, or @option{--reference} options, see below)
+in the format defined by that argument,
which is similar to that of the @code{strftime} function. Except for
conversion specifiers, which start with @samp{%}, characters in the
format string are printed unchanged. The conversion specifiers are
@@ -16502,6 +16503,9 @@ for the @option{--date} (@option{-d}) and @option{--file}
@opindex --reference
Display the date and time of the last modification of @var{file},
instead of the current date and time.
+If this option is combined with the @option{--date} or @option{--file}
+options, the reference @var{file}'s time is
+the origin for any relative @var{time}s given, but is otherwise ignored.
@item --resolution
@opindex --resolution
diff --git a/src/date.c b/src/date.c
index 9a282e2f5..de94136fe 100644
--- a/src/date.c
+++ b/src/date.c
@@ -420,6 +420,8 @@ main (int argc, char **argv)
switch (optc)
{
case 'd':
+ if (datestr && (parse_datetime_flags & PARSE_DATETIME_DEBUG))
+error (0, 0, _("discarding previous -d: %s"), quote (datestr));
datestr = optarg;
break;
case DEBUG_DATE_PARSING_OPTION:
@@ -469,6 +471,8 @@ main (int argc, char **argv)
new_format = rfc_email_format;
break;
case 's':
+ if (set_datestr && (parse_datetime_flags & PARSE_DATETIME_DEBUG))
+error (0, 0, _("discarding previous -s: %s"), quote (set_datestr));
set_datestr = optarg;
set_date = true;
break;
@@ -494,8 +498,7 @@ main (int argc, char **argv)
}
}
- int option_specified_date = (!!datestr + !!batch_file + !!reference
- + get_resolution);
+ int option_specified_date = (!!datestr + !!batch_file + get_resolution);
if (option_specified_date > 1)
{
@@ -511,6 +514,9 @@ main (int argc, char **argv)
usage (EXIT_FAILURE);
}
+ /* Use as base for other "relative" specified dates. */
+ option_specified_date += !!reference;
+
if (optind < argc)
{
if (optind + 1 < argc)
@@ -597,7 +603,8 @@ main (int argc, char **argv)
die (EXIT_FAILURE, errno, "%s", quotef (reference));
when = get_stat_mtime ();
}
- else if (get_resolution)
+
+ if (get_resolution)
{
long int res = gettime_res ();
when.tv_sec = res / TIMESPEC_HZ;
@@ -605,9 +612,10 @@ main (int argc, char **argv)
}
else
{
+ struct timespec *now = reference ? : NULL;
if (set_datestr)
datestr = set_datestr;
- valid_date = parse_datetime2 (, datestr, NULL,
+ valid_date = parse_datetime2 (, datestr, now,
parse_datetime_flags,
tz, tzstring);
}
bug#55401: date man page
Man page of date command should make explicit that -d and -r options are mutually exclusive. date -d -3 minutes -r tmp.txt "+%Y%m%d_%H%M" date: the options to specify dates for printing are mutually exclusive
