GitHub - BurntSushi/bttf: A command line tool for datetime arithmetic, parsing, formatting and more. · GitHub
Skip to content
Navigation Menu
Toggle navigation
Sign in
Appearance settings
PlatformAI CODE CREATIONGitHub CopilotWrite better code with AIGitHub SparkBuild and deploy intelligent appsGitHub ModelsManage and compare promptsMCP RegistryNewIntegrate external toolsDEVELOPER WORKFLOWSActionsAutomate any workflowCodespacesInstant dev environmentsIssuesPlan and track workCode ReviewManage code changesAPPLICATION SECURITYGitHub Advanced SecurityFind and fix vulnerabilitiesCode securitySecure your code as you buildSecret protectionStop leaks before they startEXPLOREWhy GitHubDocumentationBlogChangelogMarketplaceView all featuresSolutionsBY COMPANY SIZEEnterprisesSmall and medium teamsStartupsNonprofitsBY USE CASEApp ModernizationDevSecOpsDevOpsCI/CDView all use casesBY INDUSTRYHealthcareFinancial servicesManufacturingGovernmentView all industriesView all solutionsResourcesEXPLORE BY TOPICAISoftware DevelopmentDevOpsSecurityView all topicsEXPLORE BY TYPECustomer storiesEvents & webinarsEbooks & reportsBusiness insightsGitHub SkillsSUPPORT & SERVICESDocumentationCustomer supportCommunity forumTrust centerPartnersView all resourcesOpen SourceCOMMUNITYGitHub SponsorsFund open source developersPROGRAMSSecurity LabMaintainer CommunityAcceleratorGitHub StarsArchive ProgramREPOSITORIESTopicsTrendingCollectionsEnterpriseENTERPRISE SOLUTIONSEnterprise platformAI-powered developer platformAVAILABLE ADD-ONSGitHub Advanced SecurityEnterprise-grade security featuresCopilot for BusinessEnterprise-grade AI featuresPremium SupportEnterprise-grade 24/7 supportPricing
Search or jump to...
Search code, repositories, users, issues, pull requests...
Search
Clear
Search syntax tips
Provide feedback
We read every piece of feedback, and take your input very seriously.
Include my email address so I can be contacted
Cancel
Submit feedback
Saved searches
Use saved searches to filter your results more quickly
Name
Query
To see all available qualifiers, see our documentation.
Cancel
Create saved search
Sign in
Sign up
Appearance settings
Resetting focus
You signed in with another tab or window. Reload to refresh your session.
You signed out in another tab or window. Reload to refresh your session.
You switched accounts on another tab or window. Reload to refresh your session.
Dismiss alert
BurntSushi
/
bttf
Public
Uh oh!
There was an error while loading. Please reload this page.
Notifications
You must be signed in to change notification settings
Fork
10
Star
490
Code
Issues
0
Pull requests
2
Discussions
Actions
Security and quality
0
Insights
Additional navigation options
Code
Issues
Pull requests
Discussions
Actions
Security and quality
Insights
BurntSushi/bttf
masterBranchesTagsGo to fileCodeOpen more actions menuFolders and filesNameNameLast commit messageLast commit dateLatest commit History35 Commits35 Commits.cargo.cargo .github.github cici pkg/windowspkg/windows srcsrc teststests .gitignore.gitignore .rgignore.rgignore COMPARISON.mdCOMPARISON.md COPYINGCOPYING Cargo.lockCargo.lock Cargo.tomlCargo.toml GUIDE.mdGUIDE.md LICENSE-MITLICENSE-MIT README.mdREADME.md UNLICENSEUNLICENSE build.rsbuild.rs rustfmt.tomlrustfmt.toml View all filesRepository files navigationREADMEUnlicense licenseLicenseMIT licensebttf
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
TipIf 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
About
A command line tool for datetime arithmetic, parsing, formatting and more.
Topics
rust
cli
time
command-line
datetime
date
timezone
zone
iana
strftime
time-zone
rfc-5545
strptime
jiff
recurrence-rule
Resources
Readme
License
Unlicense and 2 other licenses found
Licenses found
Unlicense
UNLICENSE
Unknown
COPYING
MIT
LICENSE-MIT
Uh oh!
There was an error while loading. Please reload this page.
Activity
Stars
490
stars
Watchers
1
watching
Forks
10
forks
Report repository
Releases
4
0.1.4
Latest
May 28, 2026
+ 3 releases
Sponsor this project
Sponsor
Uh oh!
There was an error while loading. Please reload this page.
Learn more about GitHub Sponsors
Uh oh!
There was an error while loading. Please reload this page.
Contributors
Uh oh!
There was an error while loading. Please reload this page.
Languages
Rust
99.9%
Shell
0.1%
Footer
© 2026 GitHub, Inc.
Footer navigation
Terms
Privacy
Security
Status
Community
Docs
Contact
Manage cookies
Do not share my personal information
You can’t perform that action at this time. |
bttf is a command line utility designed to perform various operations involving datetime arithmetic, parsing, and formatting. It is licensed under the MIT or UNLICENSE. The tool provides a wide array of functionality demonstrated through examples such as printing the current time, formatting time according to various standards like RFC 3339 or RFC 9557, calculating relative time differences between dates, adding specified durations to a time point, and determining the span between two dates, often offering precision adjustments. Furthermore, bttf supports complex scheduling tasks, allowing users to generate sequences of future dates based on specific day-of-the-week criteria, compute remaining days in a month, identify recurring dates like the second Tuesday of a month, and extract and format temporal data from log files. It also includes capabilities for processing timestamps extracted from arbitrary data, manipulating time zones, and performing time zone conversions with rounding increments.
Technically, the tool is implemented in the Rust programming language. Its core datetime logic is largely derived from the Jiff library, while localization capabilities are integrated through ICU4X and jiff-icu. The project was motivated by the desire to expose the functionality of the Jiff library through a more succinct command-line interface, aiming to improve upon the existing behavior of standard commands like date. To enhance its utility beyond simple date manipulation, the developer added features such as a tag command to extract and format datetimes from unstructured data, and integrated localization mechanisms.
The installation process involves compiling the Rust source code using cargo, allowing for standard builds or specialized builds that include locale support. Options are available for building static executables, including using the musl target on Linux, which facilitates creating statically linked binaries. A significant warning accompanies the tool, emphasizing that bttf is not intended to be a drop-in replacement for POSIX date implementations or date-compatible programs, as it does not guarantee compatibility with the date standard. Despite this limitation, the bttf time fmt command generally supports a strftime syntax that offers a high degree of compatibility with GNU date. The repository structure indicates that bttf leverages git to process repository metadata, specifically demonstrating how it can extract and format commit timestamps from files into a tabular format. |