DATESORT(1)

📦 version 0.4.11, in alpine 3.24, nixos 26.05, nixpkgs unstable, opensuse-leap 16.0

👑 DATESORT(1) — the datesort page 👑

ok so this is datesort, from the User Commands section of the manual, and bestie… it sorts your files by when things happened, not by boring alphabet things. iconic behavior honestly 💅

✨ NAME ✨

datesort — sort the contents of FILE chronologically 🕰️

🌸 SYNOPSIS 🌸

datesort [OPTION]...  [FILE]...

💖 DESCRIPTION 💖

It sorts the contents of FILE chronologically. And if you just… don't give it a FILE? No stress, it reads from stdin like a good little program 🫶

The first date/time value on each line is the sort key, periodt. That's the whole vibe.

Now here's the hierarchy, and yes it matters:

  • Dates without times count as a smaller value than any date/time on that same day.
  • Times without dates count as a smaller value than any date or date/time.
  • And if a line has no dates or times or date/times in it at all? It gets sorted towards the front. main character line, zero timestamps 😭

✨ Recognized OPTIONs ✨

  • -h, --help — print help and dip out
  • -V, --version — print the version and dip out
  • -i, --input-format=STRING... — the input format, and ngl you can pass this multiple times. Each date/time gets handed to the input format parsers in the order you gave them, and if a date/time can be read successfully with a given input format specifier string, that value gets used. first one to slay wins 💅
  • -b, --base=DT — for underspecified input, use DT as a fallback to fill in the missing fields. It's also used for ambiguous format specifiers, to position their range on the absolute time line. It must be a date/time in ISO8601 format. If you omit it, it defaults to the current date/time ⏰
  • -e, --backslash-escapes — turn on interpretation of backslash escapes in the input format specifier strings 🦋
  • --from-locale=LOCALE — interpret dates on stdin or the command line as coming from the locale LOCALE. Heads up: this would only affect month and weekday names, since input formats have to be specified explicitly 🙈
  • --from-zone=ZONE — interpret dates on stdin or the command line as coming from the time zone ZONE 🌍
  • -r, --reverse — reverse the sort order. flip it and reverse it 🔄
  • -u, --unique — print at most one line per date/time value. no duplicates, we don't do that here 🎀

🧚 FORMAT SPECS 🧚

So the format specs in dateutils are similar to posix' strftime().

However — and this is the tea ☕ — because dateutils supports a broader range of calendars, it has to employ different rules. so don't come for it.

🌈 Date specs 🌈

  • %a — the abbreviated weekday name
  • %A — the full weekday name
  • %_a — the weekday name shortened to a single character (MTWRFAS)
  • %b — the abbreviated month name
  • %B — the full month name
  • %_b — the month name shortened to a single character (FGHJKMNQUVXZ)
  • %c — the count of the weekday within the month (range 00 to 05)
  • %C — the count of the weekday within the year (range 00 to 53)
  • %d — the day of the month, 2 digits (range 00 to 31)
  • %D — the day of the year, 3 digits (range 000 to 366)
  • %F — equivalent to %Y-%m-%d (ymd's canonical format) 👑
  • %g — ISO week date year without the century (range 00 to 99)
  • %G — ISO week date year including the century
  • %j — equivalent to %D
  • %m — the month in the current calendar (range 00 to 12)
  • %Q — the quarter of the year (range Q1 to Q4)
  • %q — the number of the quarter (range 01 to 04)
  • %s — the number of seconds since the Epoch.
  • %u — the weekday as number (range 01 to 07, Sunday being 07)
  • %U — the week count, day of week is Sun (range 00 to 53)
  • %V — the ISO week count, day of week is Mon (range 01 to 53)
  • %w — the weekday as number (range 00 to 06, Sunday being 00)
  • %W — the week count, day of week is Mon (range 00 to 53)
  • %y — the year without a century (range 00 to 99)
  • %Y — the year including the century
  • %_y — the year shortened to a single digit
  • %Z — the zone offset in hours and minutes (HH:MM), with a preceding sign (+ for offsets east of UTC, - for offsets west of UTC)

and the roman numeral girlies 🏛️:

  • %Od — the day as roman numerals
  • %Om — the month as roman numerals
  • %Oy — the two digit year as roman numerals
  • %OY — the year including the century as roman numerals

and the calendar-specific ones:

  • %rs — in time systems whose Epoch is different from the unix Epoch, this selects the number of seconds since then.
  • %rY — in calendars with years that don't coincide with the Gregorian years, this selects the calendar's year.

and the ordinal/business-day cuties 🎀:

  • %dth — the day of the month as an ordinal number, 1st, 2nd, 3rd, etc.
  • %mth — the month of the year as an ordinal number, 1st, 2nd, 3rd, etc.
  • %db — the business day of the month (since last month's ultimo)
  • %dB — number of business days until this month's ultimo

🦋 Time specs 🦋

  • %H — the hour of the day using a 24h clock, 2 digits (range 00 to 23)
  • %I — the hour of the day using a 12h clock, 2 digits (range 01 to 12)
  • %M — the minute (range 00 to 59)
  • %N — the nanoseconds (range 000000000 to 999999999)
  • %p — the string AM or PM, noon is PM and midnight is AM.
  • %P — like %p but in lowercase
  • %S — The (range 00 to 60, 60 is for leap seconds)
  • %T — equivalent to %H:%M:%S
nope, there is genuinely a missing word in the original %S line. we're reporting it exactly as found, not inventing a description, bestie 😭 (60 is for leap seconds though, slay)

💜 General specs 💜

  • %n — a newline character
  • %t — a tab character
  • %% — a literal % character

⭐ Modifiers ⭐

  • %O — modifier to turn decimal numbers into Roman numerals
  • %r — modifier to turn units into real units
  • %0 — modifier to turn on zero prefixes
  • %SPC — modifier to turn on space prefixes
  • %- — modifier to turn off prefixes altogether
  • th — suffix, read and print ordinal numbers
  • b — suffix, treat days as business days
🚨 real talk: by design, dates before 1601-01-01 are not supported. don't try it. it's not going to work and it's not going to be cute.

🍓 Calendar designators 🍓

For conformity, here's a list of calendar designators and their corresponding format string:

  • ymd — %Y-%m-%d
  • ymcw — %Y-%m-%c-%w
  • ywd — %rY-W%V-%u
  • bizda — %Y-%m-%db
  • lilian — n/a
  • ldn — n/a
  • julian — n/a
  • jdn — n/a
  • matlab — n/a
  • mdn — n/a

These designators can be used as output format string, moreover, @code{lilian}/@code{ldn} and @code{julian}/@code{jdn} can also be used as input format string. iykyk 🧚

🔥 EXAMPLES 🔥

bestie just look at them go:

$ dsort < "$@{srcdir@}/caev_01.txt"
2009-06-03 caev="DVCA" secu="VOD" exch="XLON" xdte="2009-06-03" nett/GBX="5.2"
2010-11-17 caev="DVCA" secu="VOD" exch="XLON" xdte="2010-11-17" nett/GBX="2.85"
2011-11-16 caev="DVCA" secu="VOD" exch="XLON" xdte="2011-11-16" nett/GBX="3.05"
2012-06-06 caev="DVCA" secu="VOD" exch="XLON" xdte="2012-06-06" nett/GBX="6.47"
2013-06-12 caev="DVCA" secu="VOD" exch="XLON" xdte="2013-06-12" nett/GBX="6.92"
2013-11-20 caev="DVCA" secu="VOD" exch="XLON" xdte="2013-11-20" nett/GBX="3.53"
$
$ dsort "$@{srcdir@}/caev_01.txt"
2009-06-03 caev="DVCA" secu="VOD" exch="XLON" xdte="2009-06-03" nett/GBX="5.2"
2010-11-17 caev="DVCA" secu="VOD" exch="XLON" xdte="2010-11-17" nett/GBX="2.85"
2011-11-16 caev="DVCA" secu="VOD" exch="XLON" xdte="2011-11-16" nett/GBX="3.05"
2012-06-06 caev="DVCA" secu="VOD" exch="XLON" xdte="2012-06-06" nett/GBX="6.47"
2013-06-12 caev="DVCA" secu="VOD" exch="XLON" xdte="2013-06-12" nett/GBX="6.92"
2013-11-20 caev="DVCA" secu="VOD" exch="XLON" xdte="2013-11-20" nett/GBX="3.53"
$
$ dsort -r < "$@{srcdir@}/caev_01.txt"
2013-11-20 caev="DVCA" secu="VOD" exch="XLON" xdte="2013-11-20" nett/GBX="3.53"
2013-06-12 caev="DVCA" secu="VOD" exch="XLON" xdte="2013-06-12" nett/GBX="6.92"
2012-06-06 caev="DVCA" secu="VOD" exch="XLON" xdte="2012-06-06" nett/GBX="6.47"
2011-11-16 caev="DVCA" secu="VOD" exch="XLON" xdte="2011-11-16" nett/GBX="3.05"
2010-11-17 caev="DVCA" secu="VOD" exch="XLON" xdte="2010-11-17" nett/GBX="2.85"
2009-06-03 caev="DVCA" secu="VOD" exch="XLON" xdte="2009-06-03" nett/GBX="5.2"
$
$ dsort -r "$@{srcdir@}/caev_01.txt"
2013-11-20 caev="DVCA" secu="VOD" exch="XLON" xdte="2013-11-20" nett/GBX="3.53"
2013-06-12 caev="DVCA" secu="VOD" exch="XLON" xdte="2013-06-12" nett/GBX="6.92"
2012-06-06 caev="DVCA" secu="VOD" exch="XLON" xdte="2012-06-06" nett/GBX="6.47"
2011-11-16 caev="DVCA" secu="VOD" exch="XLON" xdte="2011-11-16" nett/GBX="3.05"
2010-11-17 caev="DVCA" secu="VOD" exch="XLON" xdte="2010-11-17" nett/GBX="2.85"
2009-06-03 caev="DVCA" secu="VOD" exch="XLON" xdte="2009-06-03" nett/GBX="5.2"
$
$ dsort -u < "$@{srcdir@}/caev_02.txt"
2009-06-03 caev="DVCA" secu="VOD" exch="XLON" xdte="2009-06-03" nett/GBX="5.2"
2010-11-17 caev="XXXX" secu="VOD" exch="XLON" xdte="2010-11-17"
2011-11-16 caev="DVCA" secu="VOD" exch="XLON" xdte="2011-11-16" nett/GBX="3.05"
2012-06-06 caev="DVCA" secu="VOD" exch="XLON" xdte="2012-06-06" nett/GBX="6.47"
2013-06-12 caev="DVCA" secu="VOD" exch="XLON" xdte="2013-06-12" nett/GBX="6.92"
2013-11-20 caev="DVCA" secu="VOD" exch="XLON" xdte="2013-11-20" nett/GBX="3.53"
$
$ dsort -u "$@{srcdir@}/caev_02.txt"
2009-06-03 caev="DVCA" secu="VOD" exch="XLON" xdte="2009-06-03" nett/GBX="5.2"
2010-11-17 caev="XXXX" secu="VOD" exch="XLON" xdte="2010-11-17"
2011-11-16 caev="DVCA" secu="VOD" exch="XLON" xdte="2011-11-16" nett/GBX="3.05"
2012-06-06 caev="DVCA" secu="VOD" exch="XLON" xdte="2012-06-06" nett/GBX="6.47"
2013-06-12 caev="DVCA" secu="VOD" exch="XLON" xdte="2013-06-12" nett/GBX="6.92"
2013-11-20 caev="DVCA" secu="VOD" exch="XLON" xdte="2013-11-20" nett/GBX="3.53"
$

🫶 AUTHOR 🫶

Written by Sebastian Freundt <freundt@fresse.org> — ty for your service king 💜

💀 REPORTING BUGS 💀

Report bugs to: https://github.com/hroptatyr/dateutils/issues

(be nice about it, they're doing their best 🥺)

🌟 SEE ALSO 🌟

The full documentation for datesort is maintained as a Texinfo manual. And if the info and datesort programs are properly installed at your site, this command:

info (dateutils)datesort

should give you access to the complete manual. go read it, it's giving lore 📚✨

and that's the whole page bestie!! 💅 this is dateutils 0.4.11, dated January 2024 — go sort something chronologically and think of me 🦋💖🎀

📦 where this page comes from