I'm the author of Bttf. I just wanted to share a really cool example of something that Bttf can do that I _think_ is kinda hard to do otherwise. (And also, I want to make an assertion about it and I hope this will lead to me being wrong and learning something new.)

The use case is: "I want to see a list of all files in a repository, sorted in ascending order of when it was most recently changed according to source control. I also want to highlight the time with color, make it be in local time and format it in my own bespoke way using strftime." Here's the full command (run from the root of https://github.com/BurntSushi/ripgrep):

    $ git ls-files |
        bttf tag exec git log -n1 --format='%aI' |
        bttf time in system |
        bttf time sort |
        bttf time fmt -f '%a %Y-%m-%d %H:%M:%S' |
        bttf untag -f '{tag}|t{data}'
    ...
    Thu 2025-10-30 13:30:14 crates/ignore/Cargo.toml
    Sat 2025-11-29 14:11:38 crates/core/flags/lowargs.rs
    Wed 2025-12-17 11:38:12 tests/misc.rs
    Wed 2025-12-17 11:38:12 tests/util.rs
    Thu 2026-02-12 20:39:46 crates/ignore/src/default_types.rs
    Fri 2026-02-20 16:06:29 crates/core/flags/config.rs
    Fri 2026-02-27 11:25:19 GUIDE.md
    Fri 2026-02-27 11:25:19 crates/core/flags/defs.rs
    Mon 2026-05-25 23:56:53 CONTRIBUTING.md
    Tue 2026-05-26 08:32:43 AI_POLICY.md

Or even ask for a specific time window:

    $ git ls-files |
        bttf tag exec git log -n1 --format='%aI' |
        bttf time in system |
        bttf time cmp ge 2026-01-01 |
        bttf time cmp lt 2026-04-01 |
        bttf time sort |
        bttf time fmt -f '%a %Y-%m-%d %H:%M:%S' |
        bttf untag -f '{tag}|t{data}'
    Thu 2026-02-12 20:39:46 crates/ignore/src/default_types.rs
    Fri 2026-02-20 16:06:29 crates/core/flags/config.rs
    Fri 2026-02-27 11:25:19 GUIDE.md
    Fri 2026-02-27 11:25:19 crates/core/flags/defs.rs

If you run this on a big repository, it will take quite a lot of time because `git log -n1` takes a long time. I think this is the fastest way to get the most recent commit time on a single file? (That's the assertion that I hope someone can correct me on!) In any case, `bttf tag exec` is using parallelism under the hood to make this even faster.

    $ git ls-files |
        bttf tag exec git log -n1 --format='%aI' |
        bttf time in system |
        bttf time sort |
        bttf time fmt -f '%a %Y-%m-%d %H:%M:%S' |
        bttf untag -f '{tag}|t{data}'
    ...
    Thu 2025-10-30 13:30:14 crates/ignore/Cargo.toml
    Sat 2025-11-29 14:11:38 crates/core/flags/lowargs.rs
    Wed 2025-12-17 11:38:12 tests/misc.rs
    Wed 2025-12-17 11:38:12 tests/util.rs
    Thu 2026-02-12 20:39:46 crates/ignore/src/default_types.rs
    Fri 2026-02-20 16:06:29 crates/core/flags/config.rs
    Fri 2026-02-27 11:25:19 GUIDE.md
    Fri 2026-02-27 11:25:19 crates/core/flags/defs.rs
    Mon 2026-05-25 23:56:53 CONTRIBUTING.md
    Tue 2026-05-26 08:32:43 AI_POLICY.md

Or even ask for a specific time window:

    $ git ls-files |
        bttf tag exec git log -n1 --format='%aI' |
        bttf time in system |
        bttf time cmp ge 2026-01-01 |
        bttf time cmp lt 2026-04-01 |
        bttf time sort |
        bttf time fmt -f '%a %Y-%m-%d %H:%M:%S' |
        bttf untag -f '{tag}|t{data}'
    Thu 2026-02-12 20:39:46 crates/ignore/src/default_types.rs
    Fri 2026-02-20 16:06:29 crates/core/flags/config.rs
    Fri 2026-02-27 11:25:19 GUIDE.md
    Fri 2026-02-27 11:25:19 crates/core/flags/defs.rs

Everyone talking about "biff" should be aware that it's actually "bttf" like "back to the future"

Respect for programming this. I did some date/time calculations a few years ago using Perl and it was full of corner cases and trouble. Did I enjoy it? I enjoyed seeing it work. Hopefully with the right answers! This tool looks great.

I remember when biff was what we ran in a CSH to be informed of new email. I don’t remember if this was a local UCB tool or if it was part of BSD.

The thing Biff gets right that gnu `date` and most stdlib datetime APIs get wrong: it treats "civil time" and "absolute instants" as different types. You cannot answer "what's 30 days from 2024-03-08 in America/New_York" without picking a side — DST means that's either 29d23h or 30d0h of elapsed time, and most APIs silently pick one without telling you.

Jiff (the underlying Rust crate) gets this from Temporal in TC39, which is the first time JS standards have led anything datetime-shaped. Hopefully the rest of the ecosystem catches up — Python's `zoneinfo` only landed in 3.9 and `datetime.timezone` still has sharp edges.

I am a happy user of dateutils [0], but I will try out Biff and see which one is more ergonomic.

[0]: https://www.fresse.org/dateutils/

Same dude that made jiff. Love that library, so I'm assuming biff is built on top of jiff.

been hand-rolling date -d plus a wrapper script for newsletter scheduling for years. Stuff like "next second Tuesday after a holiday" and "convert these timestamps to a reader's local time before send". biff time seq monthly -w 2-tue would have replaced about 40 lines of bash for me.

% biff

2026 M05 28, Thu 17:27:46

Ahh, the month of M05

No, Biff informs the system whether you want to be notified when mail arrives during the current terminal session.

This is pretty neat. My proficiency with the command line is woefully underdeveloped and seeing examples like this help me see the possibilities.

Thank you for making cool stuff and sharing it with us.

Quick Note: You can put the pipe operator where your backslash is and you won’t have to escape the newline character. Works in bash, zsh and ksh (what I’ve tested).

This is pretty neat. My proficiency with the command line is woefully underdeveloped and seeing examples like this help me see the possibilities.

Everyone talking about "biff" should be aware that it's actually "bttf" like "back to the future"

I remember when biff was what we ran in a CSH to be informed of new email. I don’t remember if this was a local UCB tool or if it was part of BSD.

I am a happy user of dateutils [0], but I will try out Biff and see which one is more ergonomic.

[0]: https://www.fresse.org/dateutils/

Yes! dateutils is great! I have a comparison about it here: https://github.com/BurntSushi/biff/blob/master/COMPARISON.md...

The comparison with GNU date is also likely informative.

Same dude that made jiff. Love that library, so I'm assuming biff is built on top of jiff.

Yes!!! To spell it out (with the new biff -> bttf name):

    $ bttf time seq monthly -w 2-tue -u 1y | bttf time fmt -f '%c'
    Tue, Jun 9, 2026, 11:15:11 AM EDT
    Tue, Jul 14, 2026, 11:15:11 AM EDT
    Tue, Aug 11, 2026, 11:15:11 AM EDT
    Tue, Sep 8, 2026, 11:15:11 AM EDT
    Tue, Oct 13, 2026, 11:15:11 AM EDT
    Tue, Nov 10, 2026, 11:15:11 AM EST
    Tue, Dec 8, 2026, 11:15:11 AM EST
    Tue, Jan 12, 2027, 11:15:11 AM EST
    Tue, Feb 9, 2027, 11:15:11 AM EST
    Tue, Mar 9, 2027, 11:15:11 AM EST
    Tue, Apr 13, 2027, 11:15:11 AM EDT
    Tue, May 11, 2027, 11:15:11 AM EDT

More examples here: https://github.com/BurntSushi/biff/blob/master/GUIDE.md#date...

Implementing the RFC 5545 recurrence rules was quite a lot of fun: https://github.com/BurntSushi/biff/blob/4c75d5cf6e09310e74ca...

I'm quite proud of it, because if you look at the implementation, it's almost entirely about dealing with the specification rules. All of the datetime bullshit (including handling time zones) is all deferred to Jiff.

Plus, the tests are nearly 4,000 lines. While the implementation is 2,000 lines.

% biff

2026 M05 28, Thu 17:27:46

Ahh, the month of M05

This is a fair critique actually. And this shouldn't be the default. It is for now because I haven't gotten around to making Biff read your POSIX locale settings and converting them to a Unicode locale. If you build with `cargo build --release --features locale` (or get Biff from a release binary), then you can do:

    $ BIFF_LOCALE=en-US biff
    Thu, May 28, 2026, 6:38:09 AM EDT

If that doesn't work, then you can enable logging to see an error message:

    $ BIFF_LOCALE=watwat BIFF_LOG=warn biff
    2026-05-28T06:39:08.876336708-04:00[America/New_York]|WARN|src/main.rs:76: reading `BIFF_LOCALE` failed, using unknown locale `und`: failed to parse `BIFF_LOCALE` environment variable: The given language subtag is invalid
    2026 M05 28, Thu 06:39:08

What you're seeing is what ICU4X does when the user's locale is unknown or undetermined. The `M` prefix occurs to indicate that the number is the month, and is unrelated to the name. For example:

    $ BIFF_LOCALE=watwat biff time fmt -f '%c' '1 month'
    2026 M06 28, Sun 06:39:50

just between a04 and j06 yes

No, Biff informs the system whether you want to be notified when mail arrives during the current terminal session.

I.e.,

    NAME
       biff -- be notified if mail arrives and who it is from
    
    […]
    
    HISTORY
       The biff command appeared in 4.0BSD.  It was named  after  the  dog  of
       Heidi Stettner. He died in August 1993, at 15.

* https://man.freebsd.org/cgi/man.cgi?query=biff

    Eric Cooper, a student contemporary to Foderero and 
    Stettner, reports that the dog would bark at the mail 
    carrier,[4][5] making it a natural choice for the name 
    of a mail notification system. Stettner herself 
    contradicts this.[3][6]

* https://en.wikipedia.org/wiki/Biff_(Unix)

Yeah the name collision is unfortunate, but probably fine. The name Biff was just too good to pass up.

The name comes from the fact that Biff is a character in Back to the Future, and it rhymes with Jiff[1]. Jiff is the datetime library that Biff uses.

"Make like a tree and get out of here!" https://www.youtube.com/shorts/9Jabplo2pZU

[1]: https://github.com/BurntSushi/jiff

All short names, that is, pronounceable strings of 4 or maybe even 5 letters are already taken. Some of them taken many times over.

I think fewer people now care about mail notifications in a terminal session than about wrangling datetimes on the command line.

exactly. and chromium is a good looking space shooter with too few levels!

Thank you for making cool stuff and sharing it with us.

Yes! dateutils is great! I have a comparison about it here: https://github.com/BurntSushi/biff/blob/master/COMPARISON.md...

The comparison with GNU date is also likely informative.

I.e.,

    NAME
       biff -- be notified if mail arrives and who it is from
    
    […]
    
    HISTORY
       The biff command appeared in 4.0BSD.  It was named  after  the  dog  of
       Heidi Stettner. He died in August 1993, at 15.

* https://man.freebsd.org/cgi/man.cgi?query=biff

    Eric Cooper, a student contemporary to Foderero and 
    Stettner, reports that the dog would bark at the mail 
    carrier,[4][5] making it a natural choice for the name 
    of a mail notification system. Stettner herself 
    contradicts this.[3][6]

* https://en.wikipedia.org/wiki/Biff_(Unix)

Yeah the name collision is unfortunate, but probably fine. The name Biff was just too good to pass up.

The name comes from the fact that Biff is a character in Back to the Future, and it rhymes with Jiff[1]. Jiff is the datetime library that Biff uses.

"Make like a tree and get out of here!" https://www.youtube.com/shorts/9Jabplo2pZU

[1]: https://github.com/BurntSushi/jiff

> Yeah the name collision is unfortunate, but probably fine.

collisions, lol

  % apt-cache search biff
  biff - a mail notification tool
  gnubiff - mail notification program for GNOME (and others)
  wmbiff - Dockable app that displays information about mailboxes
  xlbiff - mail notification pop-up with configurable message scans

(along with 9 more matches without biff in command name)

> Yeah the name collision is unfortunate, but probably fine. The name Biff was just too good to pass up.

So if I do an "apt install biff" on Debian (or Ubuntu) what will happen?

* https://packages.debian.org/search?keywords=biff

If I type in "biff" on a Debian CLI, what should I expect the behaviour of the program that is executed to be? Will it be something about mail or time?

It was a great opportunity to name a unix tool "mcfly" or just "Marty" for time manipulation. Better luck next time, I guess.

As the author of a different project also named Biff, I do have to warn you that half the comments on your HN posts will be people quoting back to the future--though I haven't decided yet if that's annoying or an engagement hack!

[1] https://github.com/jacobobryant/biff

Griff is still available for future projects or Buford if you create a throwback project.

B1FF IS LIMITED TO 22 COLUMNZ

All short names, that is, pronounceable strings of 4 or maybe even 5 letters are already taken. Some of them taken many times over.

I think fewer people now care about mail notifications in a terminal session than about wrangling datetimes on the command line.

exactly. and chromium is a good looking space shooter with too few levels!

Yes I'm sure root is anxious to read all the mail in their local mailbox

Quick Note: You can put the pipe operator where your backslash is and you won’t have to escape the newline character. Works in bash, zsh and ksh (what I’ve tested).

So this is who I get to "blame" for LLMs constantly saying "I want to use `rg` but I see that it's not installed on this system...".

And xsv. Burntsushi projects have certain quiet sensibility that I appreciate.

    $ BIFF_LOCALE=en-US biff
    Thu, May 28, 2026, 6:38:09 AM EDT

If that doesn't work, then you can enable logging to see an error message:

    $ BIFF_LOCALE=watwat BIFF_LOG=warn biff
    2026-05-28T06:39:08.876336708-04:00[America/New_York]|WARN|src/main.rs:76: reading `BIFF_LOCALE` failed, using unknown locale `und`: failed to parse `BIFF_LOCALE` environment variable: The given language subtag is invalid
    2026 M05 28, Thu 06:39:08

What you're seeing is what ICU4X does when the user's locale is unknown or undetermined. The `M` prefix occurs to indicate that the number is the month, and is unrelated to the name. For example:

    $ BIFF_LOCALE=watwat biff time fmt -f '%c' '1 month'
    2026 M06 28, Sun 06:39:50

I came here to complain about this. Please read `LANG` like everything else :)

Yes!!! To spell it out (with the new biff -> bttf name):

    $ bttf time seq monthly -w 2-tue -u 1y | bttf time fmt -f '%c'
    Tue, Jun 9, 2026, 11:15:11 AM EDT
    Tue, Jul 14, 2026, 11:15:11 AM EDT
    Tue, Aug 11, 2026, 11:15:11 AM EDT
    Tue, Sep 8, 2026, 11:15:11 AM EDT
    Tue, Oct 13, 2026, 11:15:11 AM EDT
    Tue, Nov 10, 2026, 11:15:11 AM EST
    Tue, Dec 8, 2026, 11:15:11 AM EST
    Tue, Jan 12, 2027, 11:15:11 AM EST
    Tue, Feb 9, 2027, 11:15:11 AM EST
    Tue, Mar 9, 2027, 11:15:11 AM EST
    Tue, Apr 13, 2027, 11:15:11 AM EDT
    Tue, May 11, 2027, 11:15:11 AM EDT

More examples here: https://github.com/BurntSushi/biff/blob/master/GUIDE.md#date...

Implementing the RFC 5545 recurrence rules was quite a lot of fun: https://github.com/BurntSushi/biff/blob/4c75d5cf6e09310e74ca...

Plus, the tests are nearly 4,000 lines. While the implementation is 2,000 lines.

I implemented those recursion rules (probably very poorly) years ago. I still often think about the ways I did and probably should have handled those. It was an interesting problem.

just between a04 and j06 yes

Looking forward to the J07 04 holiday

I implemented those recursion rules (probably very poorly) years ago. I still often think about the ways I did and probably should have handled those. It was an interesting problem.

Looking forward to the J07 04 holiday

> Yeah the name collision is unfortunate, but probably fine.

collisions, lol

  % apt-cache search biff
  biff - a mail notification tool
  gnubiff - mail notification program for GNOME (and others)
  wmbiff - Dockable app that displays information about mailboxes
  xlbiff - mail notification pop-up with configurable message scans

(along with 9 more matches without biff in command name)

Those are:

1. Not precise name collisions.

2. All mail-notification utilities, as was the original biff.

And since we're mentioning Debian, it has a policy requiring unique names within the Debian archive to be unique. Precedence goes to the earlier software packaged. Installed programs must also have unique names within a given system. The datetime Swiss army knife utility discussed here violates both policies.

As Debian policy is used both for Debian and derived distros (see: <https://en.wikipedia.org/wiki/List_of_Linux_distributions#De...> for a partial listing), it has considerable influence.

> Yeah the name collision is unfortunate, but probably fine. The name Biff was just too good to pass up.

So if I do an "apt install biff" on Debian (or Ubuntu) what will happen?

* https://packages.debian.org/search?keywords=biff

If I type in "biff" on a Debian CLI, what should I expect the behaviour of the program that is executed to be? Will it be something about mail or time?

Per Debian policy and precedence of the email notification utility, you'll install biff, the command-line email notification utility:

<https://www.debian.org/doc/debian-policy/ch-binary.html#the-...>

<https://packages.debian.org/trixie/biff>

I know that if you want `fd` (https://github.com/sharkdp/fd) you need to `apt install fd-find` and which installs the binary `fdfind` (!).

I honestly don't know. Which is... Not Great.

It was a great opportunity to name a unix tool "mcfly" or just "Marty" for time manipulation. Better luck next time, I guess.

docbrown would be more appropriate, as the character who's actually doing the time manipulation.

That's... not terrible. Biff isn't exactly popular (yet?), so a name change isn't out of the question. Both of those names (and `biff`) are already taken on crates.io. Which is maybe not a huge problem. IDK. Naming is hard.

[1] https://github.com/jacobobryant/biff

Back to the Future jokes never get old. I love it.

I still want one of those hover boards!

Griff is still available for future projects or Buford if you create a throwback project.

B1FF IS LIMITED TO 22 COLUMNZ

From the excellent "A Quarter Century of UNIX" (by the late Peter H. Salus):

Heidi would bring her dog with her to class and to her office. He was a very friendly dog, and a lot of the students enjoyed throwing a ball for him down the corridor to fetch. He even had his picture on the bulletin board with the graduate students: the legend read that he was working on his Ph.Dog. John decided to name the program after the dog: Biff. According to Heidi, John and Bill Joy then spent a lot of time trying to compose an explanation for biff - they came up with "Be notified if mail arrived." Biff, who died in August 1993, at 15, once got a B in a compiler class. According to Heidi, the story of Biff barking at the mailman is a scurrilous canard.

One of my favourite bits of trivia from that excellent book, but hardly anyone I bump into these days knows anything about that kind of multi-user Unix experience/environment these days. I barely caught any of it myself.

So this is who I get to "blame" for LLMs constantly saying "I want to use `rg` but I see that it's not installed on this system...".

ripgrep is a required dependency of codex when installing it via brew on macOS. So you should at least not see it if you fall into that scenario. :-)

I came here to complain about this. Please read `LANG` like everything else :)

Oh yes definitely. Was always the plan. I was honestly just hoping someone would publish a crate to do that for me.

To be clear, I don't mean publishing a crate to read an environment variable. Of course. I mean a crate that converts a POSIX locale into a Unicode locale.

I guess there's probably a 20% solution that gets 80% of the way there. e.g.,

    $ BTTF_LOCALE="$(echo $LANG | sed 's/_/-/' | sed 's/\..*//')" bttf
    Thu, May 28, 2026, 11:46:21 AM EDT

If Biff just did that as a stop-gap until the full solution lands, I bet it would work in lots of cases.

And xsv. Burntsushi projects have certain quiet sensibility that I appreciate.

I only recently realized that xsv is now unmaintained. The author now suggests using qsv or xan.

Oh yes definitely. Was always the plan. I was honestly just hoping someone would publish a crate to do that for me.

To be clear, I don't mean publishing a crate to read an environment variable. Of course. I mean a crate that converts a POSIX locale into a Unicode locale.

I guess there's probably a 20% solution that gets 80% of the way there. e.g.,

    $ BTTF_LOCALE="$(echo $LANG | sed 's/_/-/' | sed 's/\..*//')" bttf
    Thu, May 28, 2026, 11:46:21 AM EDT

If Biff just did that as a stop-gap until the full solution lands, I bet it would work in lots of cases.

ripgrep is a required dependency of codex when installing it via brew on macOS. So you should at least not see it if you fall into that scenario. :-)

I only recently realized that xsv is now unmaintained. The author now suggests using qsv or xan.

docbrown would be more appropriate, as the character who's actually doing the time manipulation.

Those are:

1. Not precise name collisions.

2. All mail-notification utilities, as was the original biff.

As Debian policy is used both for Debian and derived distros (see: <https://en.wikipedia.org/wiki/List_of_Linux_distributions#De...> for a partial listing), it has considerable influence.

I've renamed the project to bttf :-)

Per Debian policy and precedence of the email notification utility, you'll install biff, the command-line email notification utility:

<https://www.debian.org/doc/debian-policy/ch-binary.html#the-...>

<https://packages.debian.org/trixie/biff>

I know that if you want `fd` (https://github.com/sharkdp/fd) you need to `apt install fd-find` and which installs the binary `fdfind` (!).

I honestly don't know. Which is... Not Great.

Back to the Future jokes never get old. I love it.

I still want one of those hover boards!

Yes I'm sure root is anxious to read all the mail in their local mailbox

Sending mail to root@<whatever> really did use to be a pretty reliable way of getting somebody useful's attention - the early-to-mid 90s equivalent of making a "Can someone from Google please unlock my account?" post on HN.

I've renamed the project to bttf :-)

https://crates.io/search?q=bttf

// backronym bttf stands for biff time to format

Naming is hard, sure, but doing some due diligence up front to see what's already being used isn't very difficult. Very neat tool.

From the excellent "A Quarter Century of UNIX" (by the late Peter H. Salus):

Yeah this was before my time. I never did email from a terminal. Which probably explains why I was okay with naming it Biff.

In any case, I've renamed the project to bttf: https://github.com/BurntSushi/bttf/pull/14

Under Debian/Ubuntu, when Postfix is installed, part of the standard list of questions that dpkg-reconfigure asks you is how you want mail flow to work: you can give it a central smarthost. So any local mail gets sent on, and on the central mail hub you can tell it to send root@ to someplace useful:

* https://wiki.debian.org/Postfix#Forward_Emails

That works on Debian ;-)

<https://packages.debian.org/search?keywords=btff>

Might want to ping the mods (hn@ycombinator.com) to update this submission title.

Naming is hard, sure, but doing some due diligence up front to see what's already being used isn't very difficult. Very neat tool.

I did. I always do. I just missed this one. Or if I saw it, it didn't register for me and felt like it was just an old archaic tool. Which... is probably still true, but I under-estimated its mindshare. Just an honest unknown unknown.

https://crates.io/search?q=bttf

// backronym bttf stands for biff time to format

You win the naming contest. The project has been renamed: https://github.com/BurntSushi/bttf/pull/14

Yeah this was before my time. I never did email from a terminal. Which probably explains why I was okay with naming it Biff.

In any case, I've renamed the project to bttf: https://github.com/BurntSushi/bttf/pull/14

That works on Debian ;-)

<https://packages.debian.org/search?keywords=btff>

Might want to ping the mods (hn@ycombinator.com) to update this submission title.

* https://wiki.debian.org/Postfix#Forward_Emails

Thank you for helping maintain the Unix lore.

I dont think it's part of the unix standard. Biff sounds perfect

You win the naming contest. The project has been renamed: https://github.com/BurntSushi/bttf/pull/14

@dang - Could you update the post title please to say "bttf" instead of "Biff"? Thank you!

This is the fastest rebranding after a Show HN I think I’ve seen haha

Thank you for helping maintain the Unix lore.

This is the fastest rebranding after a Show HN I think I’ve seen haha

also: back to the future

I dont think it's part of the unix standard. Biff sounds perfect

My decisions about naming aren't limited or prescribed by what is in a standard or not. :-)

@dang - Could you update the post title please to say "bttf" instead of "Biff"? Thank you!

My decisions about naming aren't limited or prescribed by what is in a standard or not. :-)

I don't think @ tags have any effect on HN, you'll want to email the mods directly: hn@ycombinator.com

also: back to the future

Intersting to notice that the name has been changed now when reading the post 12h late :-D

Burntsushi to the future

I don't think @ tags have any effect on HN, you'll want to email the mods directly: hn@ycombinator.com

Intersting to notice that the name has been changed now when reading the post 12h late :-D

Burntsushi to the future

bttf

A command line tool for datetime arithmetic, parsing, formatting and more.

Dual-licensed under MIT or the UNLICENSE.

Documentation

The user guide should be your first stop for understanding the high level concepts that bttf deals with. Otherwise, consult bttf --help or bttf <sub-command> --help for more specific details.

Alternatively, there is a comparison between other similar tools that might give you a quick sense of what bttf is like.

Brief Examples

Print the current time:

$ bttf
Sat, May 10, 2025, 8:02:04 AM EDT

[!TIP] If you get output like 2025 M05 10, Mon 08:02:04 instead, that's because you likely don't have locale support support configured. That requires setting BTTF_LOCALE and using a GitHub release binary or building bttf with the locale feature enabled.

Print the current time in a format of your choosing:

$ bttf time fmt -f rfc3339 now
2025-05-10T08:08:30.101066734-04:00

$ bttf time fmt -f rfc9557 now
2025-05-10T08:08:33.420946447-04:00[America/New_York]

$ bttf time fmt -f '%Y-%m-%d %H:%M:%S %Z' now
2025-05-10 08:08:48 EDT

Print multiple relative times in one command:

$ bttf time fmt -f '%c' now -1d 'next sat' 'last monday' '9pm last mon'
Sat, May 10, 2025, 10:44:39 AM EDT
Fri, May 9, 2025, 10:44:39 AM EDT
Sat, May 17, 2025, 10:44:39 AM EDT
Mon, May 5, 2025, 10:44:39 AM EDT
Mon, May 5, 2025, 9:00:00 PM EDT

Print the current time in another time zone, and round it the nearest 15 minute increment:

$ bttf time in Asia/Bangkok now | bttf time round -i 15 -s minute
2025-05-10T19:15:00+07:00[Asia/Bangkok]

Add a duration to the current time:

$ bttf time add -1w now
2025-05-03T10:34:30.819577918-04:00[America/New_York]

$ bttf time add '1 week, 12 hours ago' now
2025-05-02T22:34:44.114109514-04:00[America/New_York]

$ bttf time add 6mo now
2025-11-10T10:34:49.023321635-05:00[America/New_York]

Find the duration since a date in the past and round it to the desired precision:

$ bttf span since 2025-01-20T12:00
2636h 1m 21s 324ms 691µs 216ns

$ bttf span since 2025-01-20T12:00 -l year
3mo 20d 21h 1m 25s 171ms 886µs 534ns

$ bttf span since 2025-01-20T12:00 | bttf span round -l year -s day
3mo 18d

$ bttf span since 2025-01-20T12:00 | bttf span round -l day -s day
110d

Find timestamps in a log file and reformat them into your local time in place:

$ head -n3 /tmp/access.log
2025-04-30T05:25:14Z    INFO    http.log.access.log0    handled request
2025-04-30T05:25:17Z    INFO    http.log.access.log0    handled request
2025-04-30T05:25:18Z    INFO    http.log.access.log0    handled request

$ bttf tag lines /tmp/access.log | bttf time in system | bttf time fmt -f '%c' | head -n3 | bttf untag -s
Wed, Apr 30, 2025, 1:25:14 AM EDT       INFO    http.log.access.log0    handled request
Wed, Apr 30, 2025, 1:25:17 AM EDT       INFO    http.log.access.log0    handled request
Wed, Apr 30, 2025, 1:25:18 AM EDT       INFO    http.log.access.log0    handled request

Generate a sequence of the next 5 days that are Monday, Wednesday or Friday at a specific time, and then format them in your locale:

$ bttf time seq day today -c5 -H 9 -w mon,wed,fri | bttf time fmt -f '%c'
Mon, May 12, 2025, 9:00:00 AM EDT
Wed, May 14, 2025, 9:00:00 AM EDT
Fri, May 16, 2025, 9:00:00 AM EDT
Mon, May 19, 2025, 9:00:00 AM EDT
Wed, May 21, 2025, 9:00:00 AM EDT

Print every day remaining in the current month:

$ bttf time seq daily --until $(bttf time end-of month now) today
2025-05-10T00:00:00-04:00[America/New_York]
2025-05-11T00:00:00-04:00[America/New_York]
2025-05-12T00:00:00-04:00[America/New_York]
2025-05-13T00:00:00-04:00[America/New_York]
[.. snip ..]

Find the last weekday in each of the next 12 months and print them in a succinct format:

$ bttf time seq -c12 monthly -w mon,tue,wed,thu,fri --set-position -1 | bttf time fmt -f '%a, %Y-%m-%d'
Fri, 2025-05-30
Mon, 2025-06-30
Thu, 2025-07-31
Fri, 2025-08-29
Tue, 2025-09-30
Fri, 2025-10-31
Fri, 2025-11-28
Wed, 2025-12-31
Fri, 2026-01-30
Fri, 2026-02-27
Tue, 2026-03-31
Thu, 2026-04-30

Or print the second Tuesday of each month until the end of the year:

$ bttf time seq monthly -w 2-tue --until $(bttf time end-of year now) | bttf time fmt -f '%a, %F'
Tue, 2025-05-13
Tue, 2025-06-10
Tue, 2025-07-08
Tue, 2025-08-12
Tue, 2025-09-09
Tue, 2025-10-14
Tue, 2025-11-11
Tue, 2025-12-09

Finally, this command will get the last commit date on each file in a git repository, sort them in ascending order, format the datetime to a fixed-width format and then print the data in a tabular format:

$ git ls-files \
    | bttf tag exec git log -n1 --format='%aI' \
    | bttf time sort \
    | bttf time fmt -f '%Y-%m-%d %H:%M:%S %z' \
    | bttf untag -f '{tag}\t{data}'
[.. snip ..]
2025-05-05 21:54:09 -0400       src/tz/timezone.rs
2025-05-05 21:54:09 -0400       src/tz/tzif.rs
2025-05-05 22:06:38 -0400       Cargo.toml
2025-05-05 22:06:38 -0400       crates/jiff-static/Cargo.toml
2025-05-07 18:55:23 -0400       scripts/test-various-feature-combos
2025-05-07 18:55:23 -0400       src/error.rs
2025-05-08 08:38:22 -0400       src/tz/system/mod.rs
2025-05-08 16:52:55 -0400       crates/jiff-icu/Cargo.toml
2025-05-08 16:52:55 -0400       crates/jiff-icu/src/lib.rs

To see more examples, check out the user guide or the comparison between bttf and other datetime command line tools.

Installation

The binary name for bttf is bttf. It is also on crates.io under the name bttf.

Archives of precompiled binaries for bttf are available for Windows, macOS and Linux. Linux and Windows binaries are static executables.

Alternatively, if you're a Rust programmer, bttf can be installed with cargo. Note that the binary may be bigger than expected because it contains debug symbols. This is intentional. To remove debug symbols and therefore reduce the file size, run strip on the binary.

cargo install bttf

Or, if you want locale support (which is enabled in the binaries distributed on GitHub), then install with the locale feature enabled:

cargo install bttf --features locale

bttf as a library

There is relatively little datetime logic inside of bttf proper. (Except for its RFC 5545 implementation, which may eventually move out to a library.) Most of the datetime logic is instead provided by Jiff. Additionally, localization is provided by ICU4X and integrated with Jiff via jiff-icu.

WARNING

I may ship arbitrary and capricious breaking changes at this point. You have been warned.

Also, no compatibility with date is intended. This is not a drop-in replacement. It is not intended to be. It never will be. And it doesn't give a hoot about POSIX (other than the TZ environment variable). If you need a date compatible program, then go use an implementation of POSIX date. With that said, bttf's bttf time fmt command generally supports a strftime syntax that has a large amount of compatibility with GNU date.

If you have use cases serviced by date that aren't possible with bttf, I'd like to hear about them.

Motivation

I built this tool primarily as a way to expose some of the library functionality offered by Jiff on the command line. I was after a succinct way to format datetimes or do arithmetic. So I built this tool.

date is one of those commands that I use infrequently enough, and its flags and behavior is weird enough, that I constantly have to re-read its manual in order to use it effectively. So perhaps there is room for improvement there.

As I progressed in constructing this tool, I quickly found it somewhat limited by the fact that the only data it could process was datetimes. To make bttf much more versatile, I added a bttf tag command that looks for datetimes in arbitrary data and wraps them up into a JSON lines format. It's unclear to me how broadly useful folks will find this functionality, but other datetime utilities don't seem to have it.

I also wanted to use Jiff in "anger," and in particular, as part of confidently getting it to a 1.0 state. Is its performance acceptable? Are there APIs missing that are needed for real world programs? And so on. For example, because of my development on bttf, I added a way to hook ICU4X localization into Jiff's jiff::fmt::strtime APIs.

Building

bttf is written in Rust, so you'll need to grab a Rust installation in order to compile it.

To build bttf:

git clone https://github.com/BurntSushi/bttf
cd bttf
cargo build --release
./target/release/bttf --version

Additionally, optional locale support can be built with bttf by enabling the locale feature:

cargo build --release --features locale

bttf can be built with the musl target on Linux by first installing the musl library on your system (consult your friendly neighborhood package manager). Then you just need to add musl support to your Rust toolchain and rebuild bttf, which yields a fully static executable:

rustup target add x86_64-unknown-linux-musl
cargo build --release --target x86_64-unknown-linux-musl

Applying the --features locale flag from above should also work.

Running tests

To run both unit tests and integration tests, use:

cargo test

from the repository root. If you're hacking on bttf and need to change or add tests, bttf makes heavy use of cargo insta for snapshot testing. For example, to run tests with Insta, use:

cargo insta test

And if there are any snapshots to review, you can review them via:

cargo insta review

Hacker Times