{"id":50687372,"url":"https://github.com/BurntSushi/bttf","last_synced_at":"2026-06-25T23:00:47.574Z","repository":{"id":292852382,"uuid":"945094389","full_name":"BurntSushi/bttf","owner":"BurntSushi","description":"A command line tool for datetime arithmetic, parsing, formatting and more.","archived":false,"fork":false,"pushed_at":"2026-05-29T03:49:51.000Z","size":345,"stargazers_count":710,"open_issues_count":1,"forks_count":11,"subscribers_count":2,"default_branch":"master","last_synced_at":"2026-06-13T21:22:27.337Z","etag":null,"topics":["cli","command-line","date","datetime","iana","jiff","recurrence-rule","rfc-5545","rust","strftime","strptime","time","time-zone","timezone","zone"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"unlicense","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/BurntSushi.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"COPYING","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":["BurntSushi"]}},"created_at":"2025-03-08T16:41:33.000Z","updated_at":"2026-06-13T20:44:53.000Z","dependencies_parsed_at":null,"dependency_job_id":"cbb709de-d7d8-4b71-897a-487a0e78e029","html_url":"https://github.com/BurntSushi/bttf","commit_stats":null,"previous_names":["burntsushi/biff","burntsushi/bttf"],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/BurntSushi/bttf","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BurntSushi%2Fbttf","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BurntSushi%2Fbttf/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BurntSushi%2Fbttf/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BurntSushi%2Fbttf/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/BurntSushi","download_url":"https://codeload.github.com/BurntSushi/bttf/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BurntSushi%2Fbttf/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34795436,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-25T02:00:05.521Z","response_time":101,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","command-line","date","datetime","iana","jiff","recurrence-rule","rfc-5545","rust","strftime","strptime","time","time-zone","timezone","zone"],"created_at":"2026-06-09T00:00:33.896Z","updated_at":"2026-06-25T23:00:47.554Z","avatar_url":"https://github.com/BurntSushi.png","language":"Rust","funding_links":["https://github.com/sponsors/BurntSushi"],"categories":["Rust"],"sub_categories":[],"readme":"bttf\n====\nA command line tool for datetime arithmetic, parsing, formatting and more.\n\n[![Build status](https://github.com/BurntSushi/bttf/workflows/ci/badge.svg)](https://github.com/BurntSushi/bttf/actions)\n[![Crates.io](https://img.shields.io/crates/v/bttf.svg)](https://crates.io/crates/bttf)\n\nDual-licensed under MIT or the [UNLICENSE](https://unlicense.org/).\n\n### Documentation\n\nThe [user guide] should be your first stop for understanding the high level\nconcepts that bttf deals with. Otherwise, consult `bttf --help` or\n`bttf \u003csub-command\u003e --help` for more specific details.\n\nAlternatively, there is a [comparison] between other similar tools that might\ngive you a quick sense of what bttf is like.\n\n\u003e [!TIP]\n\u003e This project was initially named Biff. It has been renamed to bttf.\n\n### Brief Examples\n\nPrint the current time:\n\n```console\n$ bttf\nSat, May 10, 2025, 8:02:04 AM EDT\n```\n\n\u003e [!TIP]\n\u003e If you get output like `2025 M05 10, Mon 08:02:04` instead, that's because\n\u003e you likely don't have [locale support][locale] support configured. Enabling\n\u003e locale support requires setting `BTTF_LOCALE` in your shell environment.\n\nPrint the current time in a format of your choosing:\n\n```console\n$ bttf time fmt -f rfc3339 now\n2025-05-10T08:08:30.101066734-04:00\n\n$ bttf time fmt -f rfc9557 now\n2025-05-10T08:08:33.420946447-04:00[America/New_York]\n\n$ bttf time fmt -f '%Y-%m-%d %H:%M:%S %Z' now\n2025-05-10 08:08:48 EDT\n```\n\nPrint multiple relative times in one command:\n\n```console\n$ bttf time fmt -f '%c' now -1d 'next sat' 'last monday' '9pm last mon'\nSat, May 10, 2025, 10:44:39 AM EDT\nFri, May 9, 2025, 10:44:39 AM EDT\nSat, May 17, 2025, 10:44:39 AM EDT\nMon, May 5, 2025, 10:44:39 AM EDT\nMon, May 5, 2025, 9:00:00 PM EDT\n```\n\nPrint the current time in another time zone, and round it the nearest 15 minute\nincrement:\n\n```console\n$ bttf time in Asia/Bangkok now | bttf time round -i 15 -s minute\n2025-05-10T19:15:00+07:00[Asia/Bangkok]\n```\n\nAdd a duration to the current time:\n\n```console\n$ bttf time add -1w now\n2025-05-03T10:34:30.819577918-04:00[America/New_York]\n\n$ bttf time add '1 week, 12 hours ago' now\n2025-05-02T22:34:44.114109514-04:00[America/New_York]\n\n$ bttf time add 6mo now\n2025-11-10T10:34:49.023321635-05:00[America/New_York]\n```\n\nFind the duration since a date in the past and round it to the desired\nprecision:\n\n```console\n$ bttf span since 2025-01-20T12:00\n2636h 1m 21s 324ms 691µs 216ns\n\n$ bttf span since 2025-01-20T12:00 -l year\n3mo 20d 21h 1m 25s 171ms 886µs 534ns\n\n$ bttf span since 2025-01-20T12:00 | bttf span round -l year -s day\n3mo 18d\n\n$ bttf span since 2025-01-20T12:00 | bttf span round -l day -s day\n110d\n```\n\nFind timestamps in a log file and reformat them into your local time in place:\n\n```console\n$ head -n3 /tmp/access.log\n2025-04-30T05:25:14Z    INFO    http.log.access.log0    handled request\n2025-04-30T05:25:17Z    INFO    http.log.access.log0    handled request\n2025-04-30T05:25:18Z    INFO    http.log.access.log0    handled request\n\n$ bttf tag lines /tmp/access.log | bttf time in system | bttf time fmt -f '%c' | head -n3 | bttf untag -s\nWed, Apr 30, 2025, 1:25:14 AM EDT       INFO    http.log.access.log0    handled request\nWed, Apr 30, 2025, 1:25:17 AM EDT       INFO    http.log.access.log0    handled request\nWed, Apr 30, 2025, 1:25:18 AM EDT       INFO    http.log.access.log0    handled request\n```\n\nGenerate a sequence of the next 5 days that are Monday, Wednesday or Friday\nat a specific time, and then format them in your locale:\n\n```console\n$ bttf time seq day today -c5 -H 9 -w mon,wed,fri | bttf time fmt -f '%c'\nMon, May 12, 2025, 9:00:00 AM EDT\nWed, May 14, 2025, 9:00:00 AM EDT\nFri, May 16, 2025, 9:00:00 AM EDT\nMon, May 19, 2025, 9:00:00 AM EDT\nWed, May 21, 2025, 9:00:00 AM EDT\n```\n\nPrint every day remaining in the current month:\n\n```console\n$ bttf time seq daily --until $(bttf time end-of month now) today\n2025-05-10T00:00:00-04:00[America/New_York]\n2025-05-11T00:00:00-04:00[America/New_York]\n2025-05-12T00:00:00-04:00[America/New_York]\n2025-05-13T00:00:00-04:00[America/New_York]\n[.. snip ..]\n```\n\nFind the last weekday in each of the next 12 months and print them in a\nsuccinct format:\n\n```console\n$ bttf time seq -c12 monthly -w mon,tue,wed,thu,fri --set-position -1 | bttf time fmt -f '%a, %Y-%m-%d'\nFri, 2025-05-30\nMon, 2025-06-30\nThu, 2025-07-31\nFri, 2025-08-29\nTue, 2025-09-30\nFri, 2025-10-31\nFri, 2025-11-28\nWed, 2025-12-31\nFri, 2026-01-30\nFri, 2026-02-27\nTue, 2026-03-31\nThu, 2026-04-30\n```\n\nOr print the second Tuesday of each month until the end of the year:\n\n```console\n$ bttf time seq monthly -w 2-tue --until $(bttf time end-of year now) | bttf time fmt -f '%a, %F'\nTue, 2025-05-13\nTue, 2025-06-10\nTue, 2025-07-08\nTue, 2025-08-12\nTue, 2025-09-09\nTue, 2025-10-14\nTue, 2025-11-11\nTue, 2025-12-09\n```\n\nFinally, this command will get the last commit date on each file in a git\nrepository, sort them in ascending order, format the datetime to a fixed-width\nformat and then print the data in a tabular format:\n\n```console\n$ git ls-files \\\n    | bttf tag exec git log -n1 --format='%aI' \\\n    | bttf time sort \\\n    | bttf time fmt -f '%Y-%m-%d %H:%M:%S %z' \\\n    | bttf untag -f '{tag}\\t{data}'\n[.. snip ..]\n2025-05-05 21:54:09 -0400       src/tz/timezone.rs\n2025-05-05 21:54:09 -0400       src/tz/tzif.rs\n2025-05-05 22:06:38 -0400       Cargo.toml\n2025-05-05 22:06:38 -0400       crates/jiff-static/Cargo.toml\n2025-05-07 18:55:23 -0400       scripts/test-various-feature-combos\n2025-05-07 18:55:23 -0400       src/error.rs\n2025-05-08 08:38:22 -0400       src/tz/system/mod.rs\n2025-05-08 16:52:55 -0400       crates/jiff-icu/Cargo.toml\n2025-05-08 16:52:55 -0400       crates/jiff-icu/src/lib.rs\n```\n\nTo see more examples, check out the [user guide] or the [comparison] between\nbttf and other datetime command line tools.\n\n### Installation\n\nThe binary name for bttf is `bttf`. It is also on\n[crates.io under the name `bttf`](https://crates.io/crates/bttf).\n\n**[Archives of precompiled binaries for bttf are available for Windows,\nmacOS and Linux.](https://github.com/BurntSushi/bttf/releases)** Linux and\nWindows binaries are static executables.\n\nAlternatively, if you're a **Rust programmer**, bttf can be installed with\n`cargo`. Note that the binary may be bigger than expected because it contains\ndebug symbols. This is intentional. To remove debug symbols and therefore\nreduce the file size, run `strip` on the binary.\n\n```console\ncargo install bttf\n```\n\nOr, if you want to disable [locale support][locale], install without default\nfeatures:\n\n```console\ncargo install bttf --no-default-features\n```\n\nThe benefit of disabling locale support is faster compile times and a smaller\n`bttf` binary.\n\n### bttf as a library\n\nThere is relatively little datetime logic inside of bttf proper.\n(Except for its RFC 5545 implementation, which may eventually move\nout to a library.) Most of the datetime logic is instead provided by\n[Jiff](https://github.com/BurntSushi/jiff). Additionally, localization is\nprovided by [ICU4X](https://docs.rs/icu) and integrated with Jiff via\n[jiff-icu](https://docs.rs/jiff-icu).\n\n### WARNING\n\nI may ship arbitrary and capricious breaking changes at this point. You have\nbeen warned.\n\nAlso, no compatibility with `date` is intended. This is not a drop-in\nreplacement. It is not intended to be. It never will be. And it doesn't give\na hoot about POSIX (other than the `TZ` environment variable). If you need a\n`date` compatible program, then go use an implementation of POSIX `date`.\nWith that said, bttf's `bttf time fmt` command generally supports a `strftime`\nsyntax that has a large amount of compatibility with GNU `date`.\n\nIf you have use cases serviced by `date` that aren't possible with bttf, I'd\nlike to hear about them.\n\n### Motivation\n\nI built this tool primarily as a way to expose some of the library\nfunctionality offered by [Jiff](https://github.com/BurntSushi/jiff) on the\ncommand line. I was after a succinct way to format datetimes or do arithmetic.\nSo I built this tool.\n\n`date` is one of those commands that I use infrequently enough, and its flags\nand behavior is weird enough, that I constantly have to re-read its manual in\norder to use it effectively. So perhaps there is room for improvement there.\n\nAs I progressed in constructing this tool, I quickly found it somewhat limited\nby the fact that the *only* data it could process was datetimes. To make bttf\nmuch more versatile, I added a `bttf tag` command that looks for datetimes in\narbitrary data and wraps them up into a JSON lines format. It's unclear to me\nhow broadly useful folks will find this functionality, but other datetime\nutilities don't seem to have it.\n\nI also wanted to use Jiff in \"anger,\" and in particular, as part of confidently\ngetting it to a 1.0 state. Is its performance acceptable? Are there APIs\nmissing that are needed for real world programs? And so on. For example,\nbecause of my development on bttf, I added a way to hook ICU4X localization\ninto Jiff's `jiff::fmt::strtime` APIs.\n\n### Building\n\nbttf is written in Rust, so you'll need to grab a\n[Rust installation](https://www.rust-lang.org/) in order to compile it.\n\nTo build bttf:\n\n```console\ngit clone https://github.com/BurntSushi/bttf\ncd bttf\ncargo build --release\n./target/release/bttf --version\n```\n\nLocale support is enabled by default. To build without it, disable default\nfeatures:\n\n```console\ncargo build --release --no-default-features\n```\n\nbttf can be built with the musl target on Linux by first installing the musl\nlibrary on your system (consult your friendly neighborhood package manager).\nThen you just need to add musl support to your Rust toolchain and rebuild\nbttf, which yields a fully static executable:\n\n```console\nrustup target add x86_64-unknown-linux-musl\ncargo build --release --target x86_64-unknown-linux-musl\n```\n\nApplying the `--no-default-features` flag from above should also work.\n\n### Running tests\n\nTo run both unit tests and integration tests, use:\n\n```console\ncargo test\n```\n\nfrom the repository root. If you're hacking on bttf and need to change or\nadd tests, bttf makes heavy use of [cargo insta] for snapshot testing. For\nexample, to run tests with Insta, use:\n\n```console\ncargo insta test\n```\n\nAnd if there are any snapshots to review, you can review them via:\n\n```console\ncargo insta review\n```\n\n[cargo insta]: https://insta.rs/docs/cli/\n[locale]: ./GUIDE.md#localization\n[user guide]: ./GUIDE.md\n[comparison]: ./COMPARISON.md\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FBurntSushi%2Fbttf","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FBurntSushi%2Fbttf","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FBurntSushi%2Fbttf/lists"}