{"id":22180638,"url":"https://github.com/jftuga/dtdiff","last_synced_at":"2025-07-26T17:32:24.695Z","repository":{"id":243970517,"uuid":"813918706","full_name":"jftuga/dtdiff","owner":"jftuga","description":"Golang package and command line tool to return or output the difference between date, time or duration","archived":false,"fork":false,"pushed_at":"2024-07-10T11:46:56.000Z","size":33,"stargazers_count":33,"open_issues_count":1,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2024-07-10T13:53:30.819Z","etag":null,"topics":["command-line","command-line-tool","date","datetime","diff","duration","duration-parsing","go-package","golang","time"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jftuga.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}},"created_at":"2024-06-12T01:59:58.000Z","updated_at":"2024-07-10T11:46:54.000Z","dependencies_parsed_at":"2024-07-10T13:48:16.919Z","dependency_job_id":null,"html_url":"https://github.com/jftuga/dtdiff","commit_stats":null,"previous_names":["jftuga/dtdiff"],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jftuga%2Fdtdiff","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jftuga%2Fdtdiff/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jftuga%2Fdtdiff/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jftuga%2Fdtdiff/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jftuga","download_url":"https://codeload.github.com/jftuga/dtdiff/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":227700391,"owners_count":17806365,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["command-line","command-line-tool","date","datetime","diff","duration","duration-parsing","go-package","golang","time"],"created_at":"2024-12-02T09:18:58.665Z","updated_at":"2024-12-02T09:18:58.896Z","avatar_url":"https://github.com/jftuga.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# DEPRECATION NOTICE\n\nThis project has been superseded by another one of my projects:\n\n[DateTimeMate](https://github.com/jftuga/DateTimeMate)\n\n**Please use that instead as it has better functionality.**\n\n### Reasons behind this change:\n\n* `dtdiff` is actually the name of a [Debian binary](https://manpages.debian.org/testing/device-tree-compiler/dtdiff.1.en.html) as discussed in this [issue](https://github.com/jftuga/dtdiff/issues/5).\n* I initially wrote this program to find the difference between two date/times. However, adding or subtracting a duration from a date/time turned out to be a more interesting problem to solve.\n* I went down a cobra CLI \u0026 Usage rabbit hole, especially with custom output, thus making the code more complicated than necessary. This is no longer needed in the new code base.\n* This library's features were bolted on instead of rebuilt from the ground up. [DateTimeMate](https://github.com/jftuga/DateTimeMate) uses the [golang options pattern](https://dave.cheney.net/2014/10/17/functional-options-for-friendly-apis) which should easily allow for backward-compatible library updates in the future.\n* In the new code base, I decided to use the word `repeat` instead of `recurrence`, which is more concise \u0026 understandable.\n\n___\n\n\n\n\n# dtdiff\nGolang package and command line tool to return or output the difference between date, time or duration\n\n`dtdiff` allows you to answer three types of questions:\n\n1. What is the duration between two different dates and/or times?\n* start and end can be in various formats, such as:\n* * 11:22:33\n* * 2024-06-01\n* * \"2024-06-01 11:22:33\"\n* * 2024-06-01T11:22:33.456Z\n2. What is the datetime when adding or subtracting a duration?\n* Duration examples include:\n* * 5 minutes 5 seconds *(or 5m5s)*\n* * 3 weeks 4 days 5 hours *(or 3W4D5h)*\n* * 8 months 7 days 6 hours 5 minutes 4 seconds *(or 8M7D6h5m4s)*\n* * 1 year 2 months 3 days 4 hours 5 minutes 6 second 7 milliseconds 8 microseconds 9 nanoseconds *(or 1Y2M3D4h5m6s7ms8us9ns)*\n3. Similar to question two, but repeats a period multiple times or until a certain datetime is encountered.\n\n## Installation\n\n* Library: `go get -u github.com/jftuga/dtdiff`\n* Run: `go install github.com/jftuga/dtdiff/cmd/dtdiff@latest`\n* Command line tool: Binaries for all platforms are provided in the [releases](https://github.com/jftuga/dtdiff/releases) section.\n* Homebrew (MacOS / Linux):\n* * `brew tap jftuga/homebrew-tap; brew update; brew install jftuga/tap/dtdiff`\n\n\n## Library Usage\n\nSupported date time formats are listed in: https://go.dev/src/time/format.go\n\n**Code Snippet:**\n\n```golang\n// import \"github.com/jftuga/dtdiff\"\n\n// example 1 - difference between two dates\ndt := dtdiff.New(\"2024-01-01 00:00:00\", \"2025-12-31 23:59:59\")\nformat, _, err := dt.DtDiff()\nfmt.Println(format) // 2 years 23 hours 59 minutes 59 seconds\n// alternatively, use the brief format:\ndt.SetBrief(true)\nformat, _, _ = dt.DtDiff()\nfmt.Println(format) // 2Y23h59m59s\n\n// example 2 - duration\nfrom := \"2024-01-01 00:00:00\"\nperiod := \"1 day 1 hour 2 minutes 3 seconds\" // can also use: \"1D1h2m3s\"\nfuture, _ := dtdiff.Add(from, period)\nfmt.Println(future) // 2024-01-02 01:02:03\npast, _ := dtdiff.Sub(from, period)\nfmt.Println(past) // 2023-12-30 22:57:57\n\n// example 3 - duration with five intervals\nfrom := \"2024-06-28T04:25:41Z\"\nperiod := \"1M1W1h1m2s\"\nrecurrence := 5\nall, _ := dtdiff.AddWithRecurrence(from, period, recurrence) // can also use SubWithRecurrence\nfor _, a := range all {\n    fmt.Println(a)\n}\n\n// example 4 - repeat interval until a datetime is encountered\nfrom := \"2024-06-28T04:25:41Z\"\nperiod := \"1M1W1h1m2s\"\nuntil := \"2025-01-01 09:30:51\"\nall, err := dtdiff.AddUntil(from, until, period) // can also use SubUntil\nfor _, a := range all {\n    fmt.Println(a)\n}\n```\n\n**Full Example:**\n\nSee the [example](cmd/example/main.go) program and its [expected output](cmd/example/expected-output.txt).\n\n\n## Command Line Usage\n\n```\ndtdiff: output the difference between date, time or duration\n\nUsage:\n dtdiff [flags]\n\nGlobals:\n  -h, --help\t\thelp for dtdiff\n  -n, --nonewline\tdo not output a newline character\n  -v, --version\t\tversion for dtdiff\n\nFlag Group 1 (mutually exclusive with Flag Group 2):\n  -b, --brief\t\toutput in brief format, such as: 1Y2M3D4h5m6s7ms8us9ns\n  -e, --end string\tend date, time, or a datetime\n  -s, --start string\tstart date, time, or a datetime\n  -i, --stdin\t\tread from STDIN instead of using -s/-e\n\nFlag Group 2:\n  -A, --add string\tadd: a duration to use with -F, such as '1 day 2 hours 3 seconds'\n  -F, --from string\ta base date, time or datetime to use with -A or -S\n  -R, --recurrence int\trepeat period this number of times (mutually exclusive with -U)\n  -S, --sub string\tsubtract: a duration to use with -F, such as '5 months 4 weeks 3 days'\n  -U, --until string\trepeat period until date/time is exceeded\n\nDurations:\nyears months weeks days\nhours minutes seconds milliseconds microseconds nanoseconds\nexample: \"1 year 2 months 3 days 4 hours 1 minute 6 seconds\"\n\nBrief Durations: (dates are upper, times are lower)\nY    M    W    D\nh    m    s    ms    us    ns\nexamples: 1Y2M3W4D5h6m7s8ms9us1ns, \"1Y 2M 3W 4D 5h 6m 7s 8ms 9us 1ns\"\n\nRelative Dates:\nfor the -s, -e, -F, and -U flags, you can use these shortcuts:\nnow\ntoday (returns same value as now)\nyesterday\ntomorrow\nexample: dtdiff -F today -A 7h10m -U tomorrow\n```\n\n**Note:** The `-i` switch can accept two different types of input:\n\n1. one line with start and end separated by a comma\n2. two lines with start on the first line and end on the second line\n\n**Note:** The `-n` switch along with `-R` will use a comma-delimited output\n\n## Examples\n\n```shell\n# difference between two times on the same day\n$ dtdiff -s 12:00:00 -e 15:30:45\n3 hours 30 minutes 45 seconds\n\n# same input, using brief output\n$ dtdiff -s 12:00:00 -e 15:30:45\n3h30m45s\n\n# using AM/PM and not 24-hour times\n$ dtdiff -s \"11:00AM\" -e \"11:00PM\"\n12 hours\n\n# using ISO-8601 dates\n$ dtdiff -s 2024-06-07T08:00:00Z -e 2024-06-08T09:02:03Z\n1 day 1 hour 2 minutes 3 seconds\n\n# using timezone offset\n$ dtdiff -s 2024-06-07T08:00:00Z -e 2024-06-07T08:05:05-05:00\n5 hours 5 minutes 5 seconds\n\n# using a format which includes spaces\n$ dtdiff -s \"2024-06-07 08:01:02\" -e \"2024-06-07 08:02\"\n58 seconds\n\n# using the built-in MacOS date program and do not include a newline character\n$ dtdiff -s \"$(date -R)\" -e \"$(date -v+1M -v+30S)\" -n\n1 minute 30 seconds%\n\n# using the cross-platform date program, ending time starting first\n$ dtdiff -s \"$(date)\" -e 2020\n-4 years 24 weeks 1 day 7 hours 21 minutes 53 seconds\n\n# same input, using brief output\n$ dtdiff -s \"$(date)\" -e 2020 -b\n-4Y24W1D7h21m53s\n\n# using microsecond formatting\n$ dtdiff -s 2024-06-07T08:00:00Z -e 2024-06-07T08:00:00.000123Z\n123 microseconds\n\n# using millisecond formatting, adding -b returns: 1m2s345ms\n$ dtdiff -s 2024-06-07T08:00:00Z -e 2024-06-07T08:01:02.345Z\n1 minute 2 seconds 345 milliseconds\n\n# read from STDIN in CSV format and do not include a newline character\n$ dtdiff -i -n\n15:16:15,15:17\n45 seconds%\n\n# same as above, include newline character\n$ echo 15:16:15,15:17 | dtdiff -i\n45 seconds\n\n# read from STDIN with start on first line and end on second line\n$ printf \"15:16:15\\n15:17:20\" | dtdiff -i\n1 minute 5 seconds\n\n# add time\n# can also use \"years\", \"months\", \"weeks\", \"days\"\n$ dtdiff -F 2024-01-01 -A \"1 hour 30 minutes 45 seconds\"\n2024-01-01 01:30:45 -0500 EST\n\n# subtract time\n# can also use \"milliseconds\", \"microseconds\"\n$ dtdiff -F \"2024-01-02 01:02:03\" -S \"1 day 1 hour 2 minutes 3 seconds\"\n2024-01-01 00:00:00 -0500 EST\n\n# output multiple occurrences: add 5 weeks, for 3 intervals\n$ dtdiff -F \"2024-01-02\" -A \"5W\" -R 3\n2024-02-06 00:00:00 -0500 EST\n2024-03-12 00:00:00 -0400 EDT\n2024-04-16 00:00:00 -0400 EDT\n\n# repeat until a certain datetime is encountered: subtract 5 minutes until 15:00\n$ dtdiff -F 15:20 -S 5m -U 15:00\n2024-06-30 15:15:00 -0400 EDT\n2024-06-30 15:10:00 -0400 EDT\n2024-06-30 15:05:00 -0400 EDT\n2024-06-30 15:00:00 -0400 EDT\n\n# use relative date until tomorrow\n$ dtdiff -F today -A 7h10m -U tomorrow\n2024-07-03 14:29:28 -0400 EDT\n2024-07-03 21:39:28 -0400 EDT\n2024-07-04 04:49:28 -0400 EDT\n\n# use relative start date with brief output\n$ dtdiff -s today -e 2024-07-07 -b\n3D16h38m47s\n```\n\n## LICENSE\n\n[MIT LICENSE](LICENSE)\n\n## Acknowledgements - Imported Modules\n\n* carbon - https://github.com/golang-module/carbon/\n* cobra - https://github.com/spf13/cobra\n* durafmt - https://github.com/hako/durafmt\n* now - https://github.com/jinzhu/now\n\n## Disclosure Notification\n\nThis program is my own original idea and was completely developed\non my own personal time, for my own personal benefit, and on my\npersonally owned equipment.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjftuga%2Fdtdiff","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjftuga%2Fdtdiff","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjftuga%2Fdtdiff/lists"}