ref-filter.c: sort formatted dates by byte value

Update the ref sorting functions of 'ref-filter.c' so that when date fields
are specified with a format string (such as in 'git for-each-ref
--sort=creatordate:<something>'), they are sorted by their formatted string
value rather than by the underlying numeric timestamp. Currently, date
fields are always sorted by timestamp, regardless of whether formatting
information is included in the '--sort' key.

Leaving the default (unformatted) date sorting unchanged, sorting by the
formatted date string adds some flexibility to 'for-each-ref' by allowing
for behavior like "sort by year, then by refname within each year" or "sort
by time of day". Because the inclusion of a format string previously had no
effect on sort behavior, this change likely will not affect existing usage
of 'for-each-ref' or other ref listing commands.

Additionally, update documentation & tests to document the new sorting
mechanism.

Signed-off-by: Victoria Dye <vdye@github.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>

diff --git a/Documentation/git-for-each-ref.txt b/Documentation/git-for-each-ref.txt
index be9543f6840be3c6a477fb8537d014b0f7dfba7b..3a9ad91b7af89a66cdd460f5ce73eaf533dad719 100644 (file)
--- a/Documentation/git-for-each-ref.txt
+++ b/Documentation/git-for-each-ref.txt
@@ -359,9 +359,11 @@ In any case, a field name that refers to a field inapplicable to
 the object referred by the ref does not cause an error.  It
 returns an empty string instead.
 
-As a special case for the date-type fields, you may specify a format for
-the date by adding `:` followed by date format name (see the
-values the `--date` option to linkgit:git-rev-list[1] takes).
+As a special case for the date-type fields, you may specify a format for the
+date by adding `:` followed by date format name (see the values the `--date`
+option to linkgit:git-rev-list[1] takes). If this formatting is provided in
+a `--sort` key, references will be sorted according to the byte-value of the
+formatted string rather than the numeric value of the underlying timestamp.
 
 Some atoms like %(align) and %(if) always require a matching %(end).
 We call them "opening atoms" and sometimes denote them as %($open).

diff --git a/ref-filter.c b/ref-filter.c
index 35b989e1dfe59e9d274afead3d397f97ed624b26..be14b56e32489dd76de97a099059aab95c8fef0c 100644 (file)
--- a/ref-filter.c
+++ b/ref-filter.c
@@ -1611,6 +1611,12 @@ static void grab_date(const char *buf, struct atom_value *v, const char *atomnam
        if (formatp) {
                formatp++;
                parse_date_format(formatp, &date_mode);
+
+               /*
+                * If this is a sort field and a format was specified, we'll
+                * want to compare formatted date by string value.
+                */
+               v->atom->type = FIELD_STR;
        }
 
        if (!eoemail)

diff --git a/t/t6300-for-each-ref.sh b/t/t6300-for-each-ref.sh
index 843a7fe14313b52d1bb3267d9b1f82152f3ccb96..eb6c8204e8bd0edd653d74102eb92db3da720202 100755 (executable)
--- a/t/t6300-for-each-ref.sh
+++ b/t/t6300-for-each-ref.sh
@@ -1356,6 +1356,52 @@ test_expect_success '--no-sort without subsequent --sort prints expected refs' '
        test_cmp expected actual
 '
 
+test_expect_success 'set up custom date sorting' '
+       # Dates:
+       # - Wed Feb 07 2024 21:34:20 +0000
+       # - Tue Dec 14 1999 00:05:22 +0000
+       # - Fri Jun 04 2021 11:26:51 +0000
+       # - Mon Jan 22 2007 16:44:01 GMT+0000
+       i=1 &&
+       for when in 1707341660 945129922 1622806011 1169484241
+       do
+               GIT_COMMITTER_DATE="@$when +0000" \
+               GIT_COMMITTER_EMAIL="user@example.com" \
+               git tag -m "tag $when" custom-dates-$i &&
+               i=$(($i+1)) || return 1
+       done
+'
+
+test_expect_success 'sort by date defaults to full timestamp' '
+       cat >expected <<-\EOF &&
+       945129922 refs/tags/custom-dates-2
+       1169484241 refs/tags/custom-dates-4
+       1622806011 refs/tags/custom-dates-3
+       1707341660 refs/tags/custom-dates-1
+       EOF
+
+       git for-each-ref \
+               --format="%(creatordate:unix) %(refname)" \
+               --sort=creatordate \
+               "refs/tags/custom-dates-*" >actual &&
+       test_cmp expected actual
+'
+
+test_expect_success 'sort by custom date format' '
+       cat >expected <<-\EOF &&
+       00:05:22 refs/tags/custom-dates-2
+       11:26:51 refs/tags/custom-dates-3
+       16:44:01 refs/tags/custom-dates-4
+       21:34:20 refs/tags/custom-dates-1
+       EOF
+
+       git for-each-ref \
+               --format="%(creatordate:format:%H:%M:%S) %(refname)" \
+               --sort="creatordate:format:%H:%M:%S" \
+               "refs/tags/custom-dates-*" >actual &&
+       test_cmp expected actual
+'
+
 test_expect_success 'do not dereference NULL upon %(HEAD) on unborn branch' '
        test_when_finished "git checkout main" &&
        git for-each-ref --format="%(HEAD) %(refname:short)" refs/heads/ >actual &&