{"id":21714372,"url":"https://github.com/mountaineerbr/shelldatediff","last_synced_at":"2026-04-01T22:03:18.381Z","repository":{"id":112521978,"uuid":"599862512","full_name":"mountaineerbr/shellDatediff","owner":"mountaineerbr","description":"Calculate time differences with shell builtins. Check moon phases, Easter dates and next Friday 13th.","archived":false,"fork":false,"pushed_at":"2026-03-21T18:45:41.000Z","size":321,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-22T08:15:09.257Z","etag":null,"topics":["bash","date-calculation","datediff","easter-calculation","ksh","lunar-phases","shell","time-interval","zsh"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mountaineerbr.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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}},"created_at":"2023-02-10T03:15:08.000Z","updated_at":"2026-03-21T18:39:34.000Z","dependencies_parsed_at":"2024-07-19T04:41:21.887Z","dependency_job_id":"99a4dcd9-d3e0-4c9f-9550-fe8e29720dc4","html_url":"https://github.com/mountaineerbr/shellDatediff","commit_stats":null,"previous_names":[],"tags_count":18,"template":false,"template_full_name":null,"purl":"pkg:github/mountaineerbr/shellDatediff","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mountaineerbr%2FshellDatediff","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mountaineerbr%2FshellDatediff/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mountaineerbr%2FshellDatediff/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mountaineerbr%2FshellDatediff/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mountaineerbr","download_url":"https://codeload.github.com/mountaineerbr/shellDatediff/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mountaineerbr%2FshellDatediff/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31292631,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-01T21:15:39.731Z","status":"ssl_error","status_checked_at":"2026-04-01T21:15:34.046Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["bash","date-calculation","datediff","easter-calculation","ksh","lunar-phases","shell","time-interval","zsh"],"created_at":"2024-11-26T00:34:41.389Z","updated_at":"2026-04-01T22:03:18.348Z","avatar_url":"https://github.com/mountaineerbr.png","language":"Shell","readme":"# shellDatediff\nCalculate time differences with shell builtins.\n\n\n![Showing off datediff.sh script](https://gitlab.com/mountaineerbr/etc/-/raw/main/gfx/datediff_intro.gif)\n\nShell utility for calculating time intervals between dates. Works with Ksh, Bash, and Zsh.\n\nThe project contains a small shell library to calculate **elapsed time between dates** as **compound time ranges** and as **single-unit fractions** - all while handling timezone offsets.\n\nThe script works with ISO-8601 and UNIX timestamps directly. It can optionally leverage `C-code date` to process diverse date formats as input.\n\nBeyond time intervals, it offers a few helpful calendar functions for day-to-day use.\n\n\n## Index\n\n\u003cdetails\u003e\n  \u003csummary\u003e★ Click to expand! ★\u003c/summary\u003e\n\n- 1. [Features](#-features)\n- 2. [Installation](#installation)\n- 3. [Usage Examples](#usage-examples)\n  - 3.1 [Time elapsed between two dates](#time-elapsed-between-two-dates)\n  - 3.2 [Result layout](#result-layout)\n  - 3.3 [Single time unit result](#single-time-unit-result)\n  - 3.4 [Decimal plates](#decimal-plates)\n  - 3.5 [Table view](#table-view)\n  - 3.6 [Next Friday the 13th](#check-next-friday-the-13th)\n  - 3.7 [Check leap years](#check-whether-year-is-leap)\n  - 3.8 [Lunar calendars](#generate-lunar-phase-calendar)\n  - 3.9 [Carnaval, Easter and Corpus Christi](#carnaval-easter-and-corpus-christi)\n- 4. [More Examples](#more-examples)\n- 5. [Dependencies](#dependecies)\n- 6. [Debugging dependencies](#debugging-dependencies)\n- 7. [Help](#help)\n- 8. [Project Source](#project-source)\n- 9. [See Also](#see-also)\n\n\u003c/details\u003e\n\n\n## ✨ Features\n\n- Date input as *ISO-8601* or *UNIX time*\n- Optionally warps `C-code date` to parse various date formats\n- Timezone offset aware, heeds environment `$TZ`\n- Check whether year is leap\n- Calculate moon / lunar phases\n- Calculate Easter, Carnaval, and Corpus Christi dates\n- Check for next Friday the 13th (or any day-of-week/month combination)\n- _Stdin_ _input_ (pipe) support\n\n\n## Installation\n\nPlace [datediff.sh](datediff.sh) in your `$PATH` and make it executable.\n\n```\nchmod +x /path/to/datediff.sh\n```\n\nThe script is compatible with `ksh`, `bash`, and `zsh`; the shebang may be changed as needed.\n\nArch Linux users can install the [PKGBUILD from the AUR](https://aur.archlinux.org/packages/datediff.sh) with an AUR helper:\n\n```\nyay -S datediff.sh\n```\n\n\n## Usage Examples\n\n### Time elapsed between two dates\n\nIf only one date is specified, the first date is assumed to be **now**.\n\u003c!-- (or **1970** as last fallback). --\u003e\n\n\n```\n% datediff.sh -u  2008-01-15  2024-09-11\n\nDATES\n2008-01-15T00:00:00+00:00       1200355200\n2024-09-11T00:00:00+00:00       1726012800\nRANGES\n16Y 07M 03W 06D  00h 00m 00s\n16.7 years | 199.9 months | 869.1 weeks | 6084.0 days | 146016.0 hours | 8760960.0 mins | 525657600 secs\n```\n\nSetting `option -u` performs all date calculations in UTC.\nIt also influences how the underlying `C-code date` programme processes dates.\n\nA single float time frame result may be calculated [when specified as the last positional argument](#single-time-unit-result).\n\u003c!-- When the last argument of the command line is exactly `y`, `mo`, `w`, `d`, `m`, or `s`, --\u003e\n\nSet `options -vvv` to filter the main output layout for specific fields (main function).\n\nFor example, calculate the **compound time range** _only_:\n\n\n```\n% datediff.sh -vv  2025-03-30T12:33:58  2031-04-17T04:34:10\n\n6Y 00M 02W 03D  16h 00m 12s\n```\n\nMind that input dates must be ISO-8601 or UNIX time.\nWhen available, `C-code date` is leveraged to parse\nuser input in various date formats.\n\n\u003c!--\nTo avoid wrapping the `C-code date` programme to process dates,\nset `options -DD`. --\u003e\n\n\u003c!--\n### Fun with History\n\nCalculate the age of the Apollo 11 mission at the moment of landing:\n\n```\n% datediff.sh -u  1969-07-20T20:17:40Z  now\n```\n--\u003e\n\n\n### Result layout\n\nThe main function is verbose by default and\nprints two sections with processed dates (**DATES**) and time range results (**RANGES**).\n\nThe user can filter out which fields are going to be calculated and displayed.\n\nSet the verbose `option -v` up to three times to select different layouts in\nthe main function. Setting `-v` in other functions decreases verbose.\n\n\nSet **option -v** once to print all single unit results _only_:\n\n```\n% datediff.sh -v  2008-01-15\n\n17.4 years | 209.3 months | 910.3 weeks | 6371.8 days | 152923.3 hours | 9175400.5 mins | 550524032 secs\n```\n\n**Note:**  Examples in this group run on 2025-06-25.\n\u003c!-- if only one date is specified,\nthe first date is assumed to be **now**. --\u003e\n\nCompound time range (`AST date` style):\n\n```\n% datediff.sh -vvv  2008-01-15\n\n17Y05M01W03D01h00m00s\n```\n\n\n### Single time unit result\n\nThe user can optionally set the last positional parameter as exactly\n`y`, `mo`, `w`, `d`, `m` or `s` to print only the specific single-unit result:\n\n\n```\n% datediff.sh  2008-01-15  2025-06-25  mo\n\n209.3 months\n```\n\n\n### Decimal plates\n\nThe number of decimal plates shown in float results can be set with `option -[num]`,\nwhere _num_ is an integer. For three decimal plates, the incantation should start as\n`datediff.sh -3`.\n\nResults are subject to rounding for improved precision!\n\n\n### Table view\n\n**Print results in table layout** with `options -tt` at the\ncommand line incantation (single-unit intervals):\n\n\n```\n% datediff.sh -3 -t -u  2008-01-15  2025-06-25\n\nYears          17.440\nMonths        209.323\nWeeks         910.143\nDays         6371.000\nHours      152904.000\nMins      9174240.000\nSecs    550454400\n```\n\n\n### Check **next Friday the 13th**\n\nUsing the _current date_ by default, run on _2025-06-25_:\n\n```\n% datediff.sh -F  Fri 13\n\nFri, 13 Feb 2026 is  233 days away\n```\n\n\nCheck any combination of **day-in-week** and **day-in-month**:\n\nOptionally specify a *start date* for the search.\n\n```\n% datediff.sh -F  Mon 1  2030-01-01\n\nMon, 01 Apr 2030 is   90 days away\n```\n\nSet `options -FF` to print the following 10 date matches as a list!\n\n\u003c!--\n% datediff.sh -FF Mon 1 2030\n\nMon, 01 Apr 2030 is   90 days away\nMon, 01 Jul 2030 is  181 days away\nMon, 01 Sep 2031 is  608 days away\nMon, 01 Dec 2031 is  699 days away\nMon, 01 Mar 2032 is  790 days away\nMon, 01 Nov 2032 is 1035 days away\nMon, 01 Aug 2033 is 1308 days away\nMon, 01 May 2034 is 1581 days away\nMon, 01 Jan 2035 is 1826 days away\nMon, 01 Oct 2035 is 2099 days away\n--\u003e\n\n\n### Check whether **year is leap**\n\n```\n% datediff.sh -l  2032\n\nleap year -- 2032\n```\n\nThe _exit code is 1_ if a year _is not_ leap.\n\nSet `option -v` to decrease verbose. \n\n\n### Generate **lunar phase calendar**\n\n```\n% datediff.sh -m  2030-01\n\n2030-01-01  Waning Crescent\n2030-01-03  New Moon\n2030-01-07  Waxing Crescent\n2030-01-10  First Quarter\n2030-01-14  Waxing Gibbous\n2030-01-18  Full Moon\n2030-01-21  Waning Gibbous\n2030-01-25  Last Quarter\n2030-01-29  Waning Crescent\n```\n\nPort of the NetHack `phase_of_the_moon()` code;\nas an approximation, its results may differ slightly from actual moon phases.\n\nFor multiple-month calendar:\n\n```\n% datediff.sh -m  2030-{01..12}\n\n#OR\n\n% datediff.sh -m  2030\n```\n\nSetting `option -m` without an argument shows the moon phase for current date.\n\n\n### **Carnaval**, **Easter** and **Corpus Christi**\n\n```\n% datediff.sh -ee  2030\n\n  Carnaval          Easter      CorpusChristi\n2030-03-05      2030-04-21      2030-06-20\n\n```\n\nSet multiple years to calculate a table of dates:\n\u003c!-- a nice `TSV`-formatted table --\u003e\n\n```\n% datediff.sh -ee  20{23..30}\n  Carnaval          Easter      CorpusChristi\n2023-02-21      2023-04-09      2023-06-08\n2024-02-13      2024-03-31      2024-05-30\n2025-03-04      2025-04-20      2025-06-19\n2026-02-17      2026-04-05      2026-06-04\n2027-02-09      2027-03-28      2027-05-27\n2028-02-29      2028-04-16      2028-06-15\n2029-02-13      2029-04-01      2029-05-31\n2030-03-05      2030-04-21      2030-06-20\n```\n\nThe dates are for the _Western_ _Church_.\n\n\n## More Examples\n\nCheck further [examples at the man page](man#examples).\n\n\n## Dependencies\n\n- `Ksh93`, `Bash`, or `Zsh`\n- `GNU`/`BSD`/`AST`/`Busybox` `date` (optional)\n- Basic Calculator `bc` and Desk Calculator `dc` (optional)\n\n\n### Debugging dependencies\n\n- `datedff.debug.sh` script\n- Hroptatyr's `C-code datediff`\n\n\n## Help\n\nPlease, check script help page with `datediff.sh -h`\nor the [online man page](man/README.md).\n\n\n## Project Source\n\n- GitLab \u003chttps://gitlab.com/fenixdragao/shelldatediff\u003e\n- GitHub \u003chttps://github.com/mountaineerbr/shellDatediff\u003e\n\nExtensively tested, see [testing scripts](tests/), [notes](tests/d-test.sh#L78-L186), and [man page](man/README.md).\n\n\n## See Also\n\n- C-code `dateutils/datediff`, *Hroptatyr*, \u003chttp://www.fresse.org/dateutils/\u003e.\n- C-code `datediff`, *William C. Hammel*, \u003chttps://graham.main.nc.us/~bhammel/graham/CPROGS/datediff.html\u003e.\n- Python `PDD`, *Jarun*, \u003chttps://github.com/jarun/pdd\u003e.\n- *AST* `date`, see elapsed time _option_ _-E_, \u003chttps://github.com/att/ast\u003e.\n- *GNU* `units`, \u003chttps://www.gnu.org/software/units/\u003e.\n- \\`\\`Calendrical calculation'', *Dershowitz* and *Reingold*, 1990,\t\u003chttp://www.cs.tau.ac.il/~nachum/papers/cc-paper.pdf\u003e.\n\n\n\u003c!--\n\n\tPlease, consider sending me a nickle!\n\t\t=) \tbc1qlxm5dfjl58whg6tvtszg5pfna9mn2cr2nulnjr\n\n        --\u003e\n\n---\n\n\u003cbr /\u003e\n\u003ca href=\"https://gitlab.com/fenixdragao/shelldatediff\"\u003e\u003cp align=\"center\"\u003e\n  \u003cimg width=\"128\" height=\"128\" alt=\"Datediff.sh script dark theme logo\"\n  src=\"https://gitlab.com/mountaineerbr/etc/-/raw/main/gfx/datediff_logo/out-8/datediff_dark-8-128.png\"\u003e\n  \u0026nbsp;\u0026nbsp;\u0026nbsp;\n  \u003cimg width=\"128\" height=\"128\" alt=\"Datediff.sh script light theme logo\"\n  src=\"https://gitlab.com/mountaineerbr/etc/-/raw/main/gfx/datediff_logo/out-8/datediff_light-8-128.png\"\u003e\n\u003c/p\u003e\u003c/a\u003e\n\n\n\u003c!-- User theme aware --\u003e \u003c!--\n\u003ca href=\"https://gitlab.com/fenixdragao/shelldatediff\"\u003e\u003cp align=\"center\"\u003e\n  \u003cpicture\u003e\n    \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"https://gitlab.com/mountaineerbr/etc/-/raw/main/gfx/datediff_logo/out-8/datediff_dark-8-128.png\"\u003e\n    \u003cimg width=\"128\" height=\"128\" alt=\"Datediff.sh script logo\" src=\"https://gitlab.com/mountaineerbr/etc/-/raw/main/gfx/datediff_logo/out-8/datediff_light-8-128.png\"\u003e\n  \u003c/picture\u003e\n\u003c/p\u003e\u003c/a\u003e\n--\u003e\n\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmountaineerbr%2Fshelldatediff","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmountaineerbr%2Fshelldatediff","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmountaineerbr%2Fshelldatediff/lists"}