Time and date module API reference

The timedate module provides comprehensive time and date manipulation functions for bash scripts, with portable implementations supporting both GNU date and BSD date (macOS).

Portability

The module automatically detects the available date implementation:

GNU date - Full functionality with date arithmetic
BSD date (macOS) - Full functionality with adapted syntax
Pure bash fallback - Basic functionality when date features are limited

Timestamp functions

Unix timestamp operations for precise time tracking.

timedate::timestamp::unix()

Get current unix timestamp (seconds since epoch).Returns: Integer timestamp

ts=$(timedate::timestamp::unix)
echo "Current timestamp: $ts"

Implementation:

date +%s

timedate::timestamp::unix_ms()

Get current unix timestamp in milliseconds.Returns: Timestamp in milliseconds

ts_ms=$(timedate::timestamp::unix_ms)
echo "Timestamp: $ts_ms ms"

timedate::timestamp::unix_ns()

Get current unix timestamp in nanoseconds.Returns: Timestamp in nanoseconds

ts_ns=$(timedate::timestamp::unix_ns)

timedate::timestamp::to_human(timestamp, [format])

Convert unix timestamp to human-readable format.Parameters:

timestamp - Unix timestamp
format - strftime format (optional, default: “%Y-%m-%d %H:%M:%S”)

Returns: Formatted date string

timedate::timestamp::to_human 1700000000
# Returns: 2023-11-14 22:13:20

timedate::timestamp::to_human 1700000000 "%B %d, %Y"
# Returns: November 14, 2023

timedate::timestamp::from_human(date_string)

Convert human-readable date to unix timestamp.Parameters:

date_string - Date in “YYYY-MM-DD HH:MM:SS” format

Returns: Unix timestamp

ts=$(timedate::timestamp::from_human "2024-01-15 12:00:00")
echo "Timestamp: $ts"

Date functions

Date manipulation and querying operations.

Current date information

timedate::date::today()

Get current date in YYYY-MM-DD format.

today=$(timedate::date::today)
echo "Today: $today"  # e.g., 2024-03-15

timedate::date::format([format], [timestamp])

Format a date with custom format string.Parameters:

format - strftime format (optional, default: “%Y-%m-%d”)
timestamp - Unix timestamp (optional, default: now)

timedate::date::format "%B %d, %Y"  # March 15, 2024
timedate::date::format "%Y/%m/%d" 1700000000

timedate::date::year()

Get current year (YYYY).

year=$(timedate::date::year)  # e.g., 2024

timedate::date::month()

Get current month (01-12).

month=$(timedate::date::month)  # e.g., 03

timedate::date::day()

Get current day of month (01-31).

day=$(timedate::date::day)  # e.g., 15

timedate::date::day_of_week()

Get day of week (1=Monday, 7=Sunday, ISO 8601).

dow=$(timedate::date::day_of_week)
[[ $dow == 6 || $dow == 7 ]] && echo "Weekend!"

timedate::date::day_name()

Get full day name (e.g., Monday).

name=$(timedate::date::day_name)
echo "Today is $name"

timedate::date::day_name::short()

Get abbreviated day name (e.g., Mon).

short=$(timedate::date::day_name::short)  # Mon, Tue, etc.

timedate::date::day_of_year()

Get day of year (001-366).

doy=$(timedate::date::day_of_year)
echo "Day $doy of the year"

timedate::date::week_of_year()

Get ISO 8601 week number (01-53).

week=$(timedate::date::week_of_year)
echo "Week $week"

timedate::date::quarter()

Get quarter of year (1-4).

q=$(timedate::date::quarter)
echo "Q$q"

Date arithmetic

timedate::date::add_days(date, n)

Add n days to a date.Parameters:

date - Date in YYYY-MM-DD format
n - Number of days to add

Returns: New date in YYYY-MM-DD format

future=$(timedate::date::add_days "2024-01-15" 10)
echo "$future"  # 2024-01-25

timedate::date::sub_days(date, n)

Subtract n days from a date.Parameters:

date - Date in YYYY-MM-DD format
n - Number of days to subtract

Returns: New date in YYYY-MM-DD format

past=$(timedate::date::sub_days "2024-01-15" 5)
echo "$past"  # 2024-01-10

timedate::date::add_months(date, n)

Add n months to a date.Parameters:

date - Date in YYYY-MM-DD format
n - Number of months to add

Returns: New date

future=$(timedate::date::add_months "2024-01-15" 3)
echo "$future"  # 2024-04-15

timedate::date::add_years(date, n)

Add n years to a date.Parameters:

date - Date in YYYY-MM-DD format
n - Number of years to add

Returns: New date

future=$(timedate::date::add_years "2024-01-15" 2)
echo "$future"  # 2026-01-15

timedate::date::days_between(date1, date2)

Calculate number of days between two dates.Parameters:

date1 - First date (YYYY-MM-DD)
date2 - Second date (YYYY-MM-DD)

Returns: Number of days (can be negative)

diff=$(timedate::date::days_between "2024-01-01" "2024-12-31")
echo "$diff days"  # 365

timedate::date::yesterday()

Get yesterday’s date.

yesterday=$(timedate::date::yesterday)

timedate::date::tomorrow()

Get tomorrow’s date.

tomorrow=$(timedate::date::tomorrow)

Date ranges

timedate::date::week_start()

Get start of current week (Monday).Returns: Date in YYYY-MM-DD format

monday=$(timedate::date::week_start)

timedate::date::week_end()

Get end of current week (Sunday).Returns: Date in YYYY-MM-DD format

sunday=$(timedate::date::week_end)

timedate::date::month_start()

Get first day of current month.

first=$(timedate::date::month_start)  # e.g., 2024-03-01

timedate::date::month_end()

Get last day of current month.

last=$(timedate::date::month_end)  # e.g., 2024-03-31

timedate::date::year_start()

Get first day of current year.

jan1=$(timedate::date::year_start)  # e.g., 2024-01-01

timedate::date::year_end()

Get last day of current year.

dec31=$(timedate::date::year_end)  # e.g., 2024-12-31

timedate::date::next_weekday(weekday_number)

Get next occurrence of a weekday from today.Parameters:

weekday_number - Day (1=Mon, 2=Tue, …, 7=Sun)

Returns: Date in YYYY-MM-DD format

next_friday=$(timedate::date::next_weekday 5)
next_monday=$(timedate::date::next_weekday 1)

timedate::date::prev_weekday(weekday_number)

Get previous occurrence of a weekday.Parameters:

weekday_number - Day (1=Mon, …, 7=Sun)

Returns: Date in YYYY-MM-DD format

last_friday=$(timedate::date::prev_weekday 5)

timedate::date::days_in_month(year, month)

Get number of days in a specific month.Parameters:

year - Year (YYYY)
month - Month (01-12)

Returns: Number of days (28-31)

days=$(timedate::date::days_in_month 2024 02)
echo "$days"  # 29 (2024 is leap year)

Date comparison

timedate::date::compare(date1, date2)

Compare two dates.Parameters:

date1 - First date (YYYY-MM-DD)
date2 - Second date (YYYY-MM-DD)

Returns: -1 (before), 0 (equal), or 1 (after)

result=$(timedate::date::compare "2024-01-15" "2024-12-31")
[[ $result == -1 ]] && echo "First date is earlier"

timedate::date::is_before(date1, date2)

Check if date1 is before date2.Returns: 0 if true, 1 if false

timedate::date::is_before "2024-01-01" "2024-12-31" && echo "Yes"

timedate::date::is_after(date1, date2)

Check if date1 is after date2.Returns: 0 if true, 1 if false

timedate::date::is_after "2024-12-31" "2024-01-01" && echo "Yes"

timedate::date::is_between(date, start, end)

Check if date falls between start and end (inclusive).Parameters:

date - Date to check
start - Range start
end - Range end

Returns: 0 if in range, 1 otherwise

timedate::date::is_between "2024-06-15" "2024-01-01" "2024-12-31"

Time functions

Time-of-day operations and time checking.

timedate::time::now()

Get current time in HH:MM:SS format.

time=$(timedate::time::now)
echo "Current time: $time"

timedate::time::format([format])

Get current time in custom format.Parameters:

format - strftime format (optional, default: “%H:%M:%S”)

timedate::time::format "%I:%M %p"  # 02:30 PM

timedate::time::hour()

Get current hour (00-23).

hour=$(timedate::time::hour)

timedate::time::minute()

Get current minute (00-59).

minute=$(timedate::time::minute)

timedate::time::second()

Get current second (00-59).

second=$(timedate::time::second)

timedate::time::timezone()

Get timezone abbreviation (e.g., UTC, EST, PST).

tz=$(timedate::time::timezone)

timedate::time::timezone_offset()

Get timezone offset from UTC (e.g., +0800, -0500).

offset=$(timedate::time::timezone_offset)

Time checking

timedate::time::is_before(HH:MM)

Check if current time is before specified time.Parameters:

Time in HH:MM format

Returns: 0 if true, 1 if false

timedate::time::is_before "12:00" && echo "It's morning"

timedate::time::is_after(HH:MM)

Check if current time is after specified time.

timedate::time::is_after "17:00" && echo "Work day done"

timedate::time::is_between(start, end)

Check if current time is between two times.Parameters:

start - Start time (HH:MM)
end - End time (HH:MM)

timedate::time::is_between "09:00" "17:00" && echo "Business hours"

timedate::time::is_business_hours([start], [end])

Check if currently business hours (Mon-Fri, 09:00-17:00 default).Parameters:

start - Start time (optional, default: 09:00)
end - End time (optional, default: 17:00)

Returns: 0 if business hours, 1 otherwise

timedate::time::is_business_hours && echo "Office is open"
timedate::time::is_business_hours "08:00" "18:00"

timedate::time::is_morning()

Check if currently morning (00:00-11:59).

timedate::time::is_morning && echo "Good morning!"

timedate::time::is_afternoon()

Check if currently afternoon (12:00-17:59).

timedate::time::is_afternoon && echo "Good afternoon!"

timedate::time::is_evening()

Check if currently evening (18:00-23:59).

timedate::time::is_evening && echo "Good evening!"

Timing utilities

timedate::time::sleep(seconds, [message])

Sleep with a progress indicator.Parameters:

seconds - Duration to sleep
message - Status message (optional, default: “Waiting”)

timedate::time::sleep 5 "Processing"
# Output: Processing... 5s, 4s, 3s, 2s, 1s, done

timedate::time::stopwatch::start()

Start a stopwatch, returns a token.Returns: Timestamp token for later use

token=$(timedate::time::stopwatch::start)
# ... do work ...
elapsed=$(timedate::time::stopwatch::stop $token)
echo "Took $elapsed ms"

timedate::time::stopwatch::stop(token)

Stop a stopwatch and get elapsed time.Parameters:

token - Token from stopwatch::start

Returns: Elapsed milliseconds

start=$(timedate::time::stopwatch::start)
sleep 2
elapsed=$(timedate::time::stopwatch::stop $start)
echo "Duration: $elapsed ms"

Duration functions

Human-readable duration formatting and parsing.

timedate::duration::format(seconds)

Format seconds into human-readable duration.Parameters:

seconds - Total seconds

Returns: Formatted string (e.g., “1d 2h 3m 4s”)

timedate::duration::format 90061
# Returns: 1d 1h 1m 1s

timedate::duration::format 3665
# Returns: 1h 1m 5s

timedate::duration::format_ms(milliseconds)

Format milliseconds into human-readable duration.Parameters:

milliseconds - Total milliseconds

Returns: Formatted string

timedate::duration::format_ms 500
# Returns: 500ms

timedate::duration::format_ms 65000
# Returns: 1m 5s

timedate::duration::parse(duration_string)

Parse a duration string into seconds.Parameters:

duration_string - String like “1d 2h 3m 4s”

Returns: Total seconds

seconds=$(timedate::duration::parse "1h 30m")
echo "$seconds"  # 5400

timedate::duration::relative(timestamp)

Convert timestamp to relative time description.Parameters:

timestamp - Unix timestamp

Returns: Human-readable relative time

ts=$(date -d "2 hours ago" +%s)
timedate::duration::relative $ts
# Returns: "2 hours ago"

future=$(date -d "3 days" +%s)
timedate::duration::relative $future
# Returns: "in 3 days"

Calendar functions

Calendar calculations and holiday determination.

timedate::calendar::is_leap_year(year)

Check if a year is a leap year.Parameters:

year - Year (YYYY)

Returns: 0 if leap year, 1 otherwise

timedate::calendar::is_leap_year 2024 && echo "Leap year"
timedate::calendar::is_leap_year 2023 || echo "Not leap year"

timedate::calendar::days_in_year(year)

Get number of days in a year.Parameters:

year - Year (YYYY)

Returns: 365 or 366

days=$(timedate::calendar::days_in_year 2024)  # 366

timedate::calendar::is_weekend(date)

Check if a date falls on Saturday or Sunday.Parameters:

date - Date in YYYY-MM-DD format

Returns: 0 if weekend, 1 otherwise

timedate::calendar::is_weekend "2024-03-16" && echo "Weekend!"

timedate::calendar::is_weekday(date)

Check if a date falls on a weekday (Monday-Friday).Parameters:

date - Date in YYYY-MM-DD format

Returns: 0 if weekday, 1 otherwise

timedate::calendar::is_weekday "2024-03-15" && echo "Workday"

timedate::calendar::iso_week(date)

Get ISO week number for a date.Parameters:

date - Date in YYYY-MM-DD format

Returns: Week number (01-53)

week=$(timedate::calendar::iso_week "2024-06-15")

timedate::calendar::day_of_year(date)

Get day of year for a date.Parameters:

date - Date in YYYY-MM-DD format

Returns: Day number (001-366)

doy=$(timedate::calendar::day_of_year "2024-12-31")  # 366

timedate::calendar::quarter(date)

Get quarter for a date.Parameters:

date - Date in YYYY-MM-DD format

Returns: Quarter (1-4)

q=$(timedate::calendar::quarter "2024-06-15")  # 2

timedate::calendar::easter(year)

Calculate Easter date using Meeus/Jones/Butcher algorithm.Parameters:

year - Year (YYYY)

Returns: Easter date in YYYY-MM-DD format

easter=$(timedate::calendar::easter 2024)
echo "Easter 2024: $easter"  # 2024-03-31

timedate::calendar::weekdays_between(start, end)

Count weekdays between two dates.Parameters:

start - Start date (YYYY-MM-DD)
end - End date (YYYY-MM-DD)

Returns: Number of weekdays

days=$(timedate::calendar::weekdays_between "2024-01-01" "2024-01-31")
echo "$days business days"

timedate::calendar::month([year], [month])

Display calendar for a month (like cal command).Parameters:

year - Year (optional, default: current)
month - Month (optional, default: current)

timedate::calendar::month 2024 12
# Displays December 2024 calendar

Timezone functions

Timezone conversion and information.

timedate::tz::convert(timestamp, timezone)

Convert a timestamp to a different timezone.Parameters:

timestamp - Unix timestamp
timezone - TZ database name (e.g., “America/New_York”)

Returns: Formatted date/time in target timezone

timedate::tz::convert 1700000000 "America/New_York"
# Returns: 2023-11-14 17:13:20 EST

timedate::tz::convert 1700000000 "Asia/Tokyo"
# Returns: 2023-11-15 07:13:20 JST

timedate::tz::now(timezone)

Get current time in a specific timezone.Parameters:

timezone - TZ database name

Returns: Current date/time in timezone

timedate::tz::now "Europe/London"
timedate::tz::now "Australia/Sydney"

timedate::tz::current()

Get current timezone name.Returns: Timezone abbreviation

tz=$(timedate::tz::current)
echo "Current timezone: $tz"  # e.g., UTC, EST

timedate::tz::offset_seconds()

Get UTC offset in seconds.Returns: Offset in seconds (can be negative)

offset=$(timedate::tz::offset_seconds)
hours=$((offset / 3600))
echo "UTC offset: $hours hours"

timedate::tz::is_dst()

Check if currently in daylight saving time.Returns: 0 if DST, 1 otherwise

timedate::tz::is_dst && echo "Daylight saving time active"

timedate::tz::list()

List all available timezones.Returns: List of TZ database names

timedate::tz::list | head -20

timedate::tz::list::region(region)

List timezones filtered by region.Parameters:

region - Region name (e.g., “America”, “Europe”)

Returns: Filtered list of timezones

timedate::tz::list::region America
# Lists: America/New_York, America/Chicago, etc.

Usage examples

Task scheduler with date checking

#!/bin/bash
source timedate.sh

# Run task only on weekdays during business hours
if timedate::calendar::is_weekday "$(timedate::date::today)" && \
   timedate::time::is_business_hours; then
    echo "Running scheduled task..."
    ./backup.sh
else
    echo "Outside business hours, skipping"
fi

Calculate age from birthdate

birth="1990-05-15"
today=$(timedate::date::today)
days=$(timedate::date::days_between "$birth" "$today")
years=$((days / 365))
echo "Approximately $years years old"

Benchmark script execution

start=$(timedate::time::stopwatch::start)

# Run your script
./process_data.sh

elapsed=$(timedate::time::stopwatch::stop $start)
echo "Processing took: $(timedate::duration::format_ms $elapsed)"

Multi-timezone meeting planner

meeting_ts=$(timedate::timestamp::from_human "2024-03-20 14:00:00")

echo "Meeting times:"
echo "New York: $(timedate::tz::convert $meeting_ts 'America/New_York')"
echo "London:   $(timedate::tz::convert $meeting_ts 'Europe/London')"
echo "Tokyo:    $(timedate::tz::convert $meeting_ts 'Asia/Tokyo')"

Calculate project deadline

start=$(timedate::date::today)
workdays=60

# Add weekdays only
count=0
current="$start"
while [[ $count -lt $workdays ]]; do
    current=$(timedate::date::add_days "$current" 1)
    timedate::calendar::is_weekday "$current" && ((count++))
done

echo "60 business days from now: $current"

Text & Data

System & Runtime

User Interface

Utilities

External Tools

Time and date module API reference

Portability

Timestamp functions

Date functions

Current date information

Date arithmetic

Date ranges

Date navigation

Date comparison

Time functions

Time checking

Timing utilities

Duration functions

Calendar functions

Timezone functions

Usage examples

Task scheduler with date checking

Calculate age from birthdate

Benchmark script execution

Multi-timezone meeting planner

Calculate project deadline

Build docs developers (and LLMs) love

Text & Data

System & Runtime

User Interface

Utilities

External Tools

​Portability

​Timestamp functions

​Date functions

​Current date information

​Date arithmetic

​Date ranges

​Date navigation

​Date comparison

​Time functions

​Time checking

​Timing utilities

​Duration functions

​Calendar functions

​Timezone functions

​Usage examples

​Task scheduler with date checking

​Calculate age from birthdate

​Benchmark script execution

​Multi-timezone meeting planner

​Calculate project deadline

Build docs developers (and LLMs) love

Portability

Timestamp functions

Date functions

Current date information

Date arithmetic

Date ranges

Date navigation

Date comparison

Time functions

Time checking

Timing utilities

Duration functions

Calendar functions

Timezone functions

Usage examples

Task scheduler with date checking

Calculate age from birthdate

Benchmark script execution

Multi-timezone meeting planner

Calculate project deadline