{"id":13408772,"url":"https://github.com/jftuga/DateTimeMate","last_synced_at":"2025-03-14T13:32:03.476Z","repository":{"id":247769307,"uuid":"822237426","full_name":"jftuga/DateTimeMate","owner":"jftuga","description":"Golang package and CLI to compute the difference between date, time or duration","archived":false,"fork":false,"pushed_at":"2024-08-11T17:26:28.000Z","size":44,"stargazers_count":14,"open_issues_count":0,"forks_count":0,"subscribers_count":3,"default_branch":"main","last_synced_at":"2024-08-11T18:45:26.884Z","etag":null,"topics":["calculator","command-line","command-line-tool","date","date-formatting","date-time","datetime","duration","go","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-30T17:04:00.000Z","updated_at":"2024-08-11T17:18:26.000Z","dependencies_parsed_at":"2024-07-28T12:46:04.179Z","dependency_job_id":"dd15fd6b-ac1d-4804-9120-25ff11b67322","html_url":"https://github.com/jftuga/DateTimeMate","commit_stats":null,"previous_names":["jftuga/datetimemate"],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jftuga%2FDateTimeMate","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jftuga%2FDateTimeMate/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jftuga%2FDateTimeMate/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jftuga%2FDateTimeMate/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jftuga","download_url":"https://codeload.github.com/jftuga/DateTimeMate/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243584457,"owners_count":20314765,"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":["calculator","command-line","command-line-tool","date","date-formatting","date-time","datetime","duration","go","golang","time"],"created_at":"2024-07-30T20:00:55.146Z","updated_at":"2025-03-14T13:32:03.452Z","avatar_url":"https://github.com/jftuga.png","language":"Go","funding_links":[],"categories":["\u003ca name=\"calc\"\u003e\u003c/a\u003eCalculators"],"sub_categories":[],"readme":"# DateTimeMate\nGolang package and CLI to compute the difference between date, time or duration\n\nThe command-line program, `dtmate` *(along with the golang package)* allows you to answer these inquiries:\n\n\u003cdetails open\u003e\n\u003csummary\u003e1. What is the duration between two different dates and/or times?\u003c/summary\u003e\n\n`dtmate diff \"2024-06-01 11:22:33\" \"2024-07-19 21:07:19\"`\n* answer: `6 weeks 6 days 9 hours 44 minutes 46 seconds`\n* answer with the `-b` option: `6W6D9h44m46s`\n* start and end can be in various formats, such as:\n* * `11:22:33`, `2024-06-01`, `\"2024-06-01 11:22:33\"`, `2024-06-01T11:22:33.456Z`\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e2. What is the datetime when adding or subtracting a duration?\u003c/summary\u003e\n\n`dtmate dur \"2024-06-01 11:22:33\" 6W6D9h44m46s -a`\n* answer: `2024-04-14 01:37:47 -0400 EDT`\n* answer with the `-f \"%Y-%m-%d %H:%M:%S\"` option: `2024-04-14 01:37:47`\n* Duration examples include:\n* * `5 minutes 5 seconds or 5m5s`\n* * `3 weeks 4 days 5 hours or 3W4D5h`\n* * `1 year 2 months 3 days 4 hours 5 minutes 6 second 7 milliseconds 8 microseconds 9 nanoseconds or 1Y2M3D4h5m6s7ms8us9ns`\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e3. Similar to previous question, but repeats a period multiple times or until a certain date/time is encountered.\u003c/summary\u003e\n\n* adding dates, repeat twice: `dtmate dur \"2024-06-01 12:00:00\" 1h5m10s -r 2 -a`\n* subtracting until a date is exceeded: `dtmate dur \"12:00:00\" 1h5m10s -u \"09:48\" -s`\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e4. Convert from one group of date/time units to another\u003c/summary\u003e\n\n* convert from seconds to weeks, days, hours, minutes, seconds: `dtmate conv 25771401s WDhms`\n* * 42 weeks 4 days 6 hours 43 minutes 21 seconds\n* convert weeks, days, hours, minutes, seconds to just seconds, with brief output format: `dtmate conv \"42 weeks 4 days 6 hours 43 minutes 21 seconds\" seconds -b`\n* * 25771401s\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e5. Reformat a date/time\u003c/summary\u003e\n\n* convert the output of the `date` utility: `dtmate fmt \"$(date)\" \"%F %T\"`\n* * where `($date)` equals `Mon Jul 22 22:49:18 EDT 2024`\n* * output: 2024-07-22 22:49:18\n\u003c/details\u003e\n\n## Installation\n\n* Library: `go get -u github.com/jftuga/DateTimeMate`\n* Command line tool: `go install -ldflags=\"-s -w\" github.com/jftuga/DateTimeMate/cmd/dtmate@latest`\n* * Binaries for all platforms are provided in the [releases](https://github.com/jftuga/DateTimeMate/releases) section.\n* Homebrew (MacOS / Linux):\n* * `brew tap jftuga/homebrew-tap; brew update; brew install jftuga/tap/dtmate`\n\n## Library Usage\n\u003cdetails open\u003e\n\u003csummary\u003eExample 1 - duration between two dates\u003c/summary\u003e\n\nSupported date time formats are listed in: https://go.dev/src/time/format.go\n\n```golang\nimport \"github.com/jftuga/DateTimeMate\"\n\n// example 1 - duration between two dates\nstart := \"2024-06-01\"\nend := \"2024-08-05 00:01:02\"\nbrief := true\ndiff := DateTimeMate.NewDiff(DateTimeMate.DiffWithStart(start), DateTimeMate.DiffWithEnd(end),\n\tDateTimeMate.DiffWithBrief(brief))\nresult, duration, err := diff.CalculateDiff()\nif err != nil { ... }\nfmt.Println(result, duration)  // 9W2D1m2s 1560h1m2s\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eExample 2 - add a duration\u003c/summary\u003e\n\n```go\n// example 2 - add a duration and repeat it until the \"until\" date is exceeded\nfrom := \"2024-06-01\"\nd := \"1 year 7 days 6 hours 5 minutes\"\nuntil := \"2027-06-22 18:15:11\"\nofmt := \"%Y%m%d.%H%M%S\"\ndur := DateTimeMate.NewDur(DateTimeMate.DurWithFrom(from), DateTimeMate.DurWithDur(d),\n\tDateTimeMate.DurWithRepeat(0), DateTimeMate.DurWithUntil(until),\n\tDateTimeMate.DurWithOutputFormat(ofmt))\nadd, err := dur.Add()\nif err != nil { ... }\nfmt.Println(add) // [20250608.060500 20260615.121000 20270622.181500]\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eExample 3 - convert date/time units\u003c/summary\u003e\n\n```go\nsource := \"1367h29m13s\"\ntarget := \"Dhms\" // days, hours, minutes, seconds\nconv := DateTimeMate.NewConv(\nDateTimeMate.ConvWithSource(source),\nDateTimeMate.ConvWithTarget(target))\nnewDuration, err := conv.ConvertDuration()\nif err != nil { ... }\nfmt.Println(\"new duration:\", newDuration) // 56 days 23 hours 29 minutes 13 seconds\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eExample 4 - reformat a date/time\u003c/summary\u003e\n\n```go\nsource := \"Mon Jul 22 08:40:33 EDT 2024\"\noutputFormat := \"%F %T\"\nnewFormat, err := DateTimeMate.Reformat(source, outputFormat)\nif err != nil { ... }\nfmt.Println(\"new format:\", newFormat) // 2024-07-22 08:40:33\n```\n\u003c/details\u003e\n\n\nSee also the [example](cmd/example/main.go) program.\n\n\n## Command Line Usage\n\u003cdetails\u003e\n\n\u003csummary\u003eShow\u003c/summary\u003e\n\n```\ndtmate: output the difference between date, time or duration\n\nUsage:\n  dtmate [flags]\n  dtmate [command]\n\nAvailable Commands:\n  conv        Convert a duration from group of units to another\n  diff        Output the difference between two date/times\n  dur         Output a date/time when given a starting date/time and duration\n  fmt         reformat a date/time\n  help        Help about any command\n\nFlags:\n  -e, --examples    show command-line examples\n  -h, --help        help for dtmate\n  -n, --nonewline   do not output a newline character\n  -v, --version     version for dtmate\n\nUse \"dtmate [command] --help\" for more information about a command.\n\n---\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\n---\n\nBrief Durations:\n(dates are always uppercase, times are always lowercase)\nY    M    W    D\nh    m    s    ms    us    ns\nexamples: 1Y2M3W4D5h6m7s8ms9us1ns, '1Y 2M 3W 4D 5h 6m 7s 8ms 9us 1ns'\n\n---\n\nRelative Date Shortcuts:\nnow\ntoday (returns same value as now)\nyesterday (exactly 24 hours behind of the current time)\ntomorrow (exactly 24 hours ahead the current time)\nexample: dtmate dur today 7h10m -a -u tomorrow\n\n---\n\nConversions:\n1 year is equal to 365.25 days\nMonths are not a unit since their lengths vary between 28 and 31 days\nSeparate sub-second brief units with a dot\nexample: dtmate conv 4321s123456789ns hms.msusns\n```\n\n\u003c/details\u003e\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 emit a comma-delimited output\n* * Example: `dtmate dur now 1h -a -n -r 3`\n\n## Command Line Examples\n\n\u003cdetails\u003e\n\u003csummary\u003eShow\u003c/summary\u003e\n\n```shell\n\n########################### \"dtmate diff\" examples ###########################\n\n# difference between two times on the same day\n$ dtmate diff 12:00:00 15:30:45\n3 hours 30 minutes 45 seconds\n\n# same input, using brief output\n$ dtmate diff 12:00:00 15:30:45 -b\n3h30m45s\n\n# using AM/PM and not 24-hour times\n$ dtmate diff \"11:00AM\" \"11:00PM\"\n12 hours\n\n# using ISO-8601 dates\n$ dtmate diff 2024-06-07T08:00:00Z 2024-06-08T09:02:03Z\n1 day 1 hour 2 minutes 3 seconds\n\n# same input, also convert to seconds only, brief format\n$ dtmate diff 2024-06-07T08:00:00Z 2024-06-08T09:02:03Z --conv s -b\n90123s\n\n# using timezone offset\n$ dtmate diff 2024-06-07T08:00:00Z 2024-06-07T08:05:05-05:00\n5 hours 5 minutes 5 seconds\n\n# same input, also convert duration to minutes and seconds\n$ dtmate diff 2024-06-07T08:00:00Z 2024-06-07T08:05:05-05:00 -c ms\n305 minutes 5 seconds\n\n# differentiate sub-second durations with a dot\n# note the \"ms\" on both sides of the dot: minutes \u0026 seconds vs milliseconds\n$ diff now \"2020-01-01 11:12:13.123456789\" -c ms.msusns\n-2566445 minutes 40 seconds 876 milliseconds 542 microseconds 985 nanoseconds\n\n# using a format which includes spaces\n$ dtmate diff \"2024-06-07 08:01:02\" \"2024-06-07 08:02\"\n58 seconds\n\n# using the built-in MacOS date program and do not include a newline character\n$ dtmate diff \"$(date -R)\" \"$(date -v+1M -v+30S)\" -n\n1 minute 30 seconds%\n\n# using the cross-platform date program, ending time starting first\n$ dtmate diff \"$(date)\" 2020\n-4 years 24 weeks 1 day 7 hours 21 minutes 53 seconds\n\n# same input, using brief output\n$ dtmate diff \"$(date)\" 2020 -b\n-4Y24W1D7h21m53s\n\n# using microsecond formatting\n$ dtmate diff 2024-06-07T08:00:00Z 2024-06-07T08:00:00.000123Z\n123 microseconds\n\n# using millisecond formatting, adding -b returns: 1m2s345ms\n$ dtmate diff 2024-06-07T08:00:00Z 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$ dtmate diff -i -n\n15:16:15,15:17\n45 seconds%\n\n# same as above, include newline character\n$ echo 15:16:15,15:17 | dtmate diff -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\" | dtmate diff -i\n1 minute 5 seconds\n\n# use relative start date with brief output\n$ dtmate diff today 2024-07-07 -b\n3D16h38m47s\n\n########################### \"dtmate dur\" examples ###########################\n\n# add time\n# can also use \"years\", \"months\", \"weeks\", \"days\"\n$ dtmate dur 2024-01-01 \"1 hour 30 minutes 45 seconds\" -a\n2024-01-01 01:30:45 -0500 EST\n\n# subtract time\n# can also use \"milliseconds\", \"microseconds\"\n$ dtmate dur \"2024-01-02 01:02:03\" \"1 day 1 hour 2 minutes 3 seconds\" -s\n2024-01-01 00:00:00 -0500 EST\n\n# output multiple occurrences: add 5 weeks, for 3 intervals\n$ dtmate dur \"2024-01-02\" \"5W\" -r 3 -a\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$ dtmate dur 15:20 5m -u 15:00 -s\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$ dtmate dur today 7h10m -u tomorrow -a\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# set the output format\n$ dtmate dur \"2024-07-01 12:00:00\" 1W2D3h4m5s -a -f \"%Y%m%d.%H%M%S\"\n20240710.150405\n\n########################### \"dtmate conv\" examples ###########################\n\n# convert from one group of date/time units to another\n$ dtmate conv 25771401s WDhms\n42 weeks 4 days 6 hours 43 minutes 21 seconds\n\n# another conversion, in the opposite direction, brief output\n$ dtmate conv 42W4D6h43m21s seconds -b\n25771401s\n\n########################### \"dtmate fmt\" examples ###########################\n\n# reformat date/times\n$ dtmate fmt \"2024-07-22 08:21:44\" \"%T %D\"\n08:21:44 07/22/24\n\n$ dtmate fmt \"2024-07-22 08:21:44\" \"%v %r\"\n22-Jul-2024 08:21:44 AM\n\n$ dtmate fmt \"2024-07-22 08:21:44\" \"%Y%m%d.%H%M%S\"\n20240722.082144\n\n$ dtmate fmt \"2024-02-29T23:59:59Z\" \"%Y%m%d.%H%M%S\"\n20240229.235959\n\n$ dtmate fmt \"2024-02-29T23:59:59Z\" \"%Z\"\nUTC\n\n$ dtmate fmt \"Mon Jul 22 08:40:33 EDT 2024\" \"%Z %z\"\nEDT -0400\n\n# convert to unix (epoch) time seconds\n$ dtmate fmt \"2024-11-16 14:01:02\" \"%s\"\n1731783662\n\n# from unix (epoch) time seconds\n$ dtmate fmt 1704085262 \"%F %T\"\n2024-01-01 00:01:02\n\n# also from milliseconds\n$ dtmate fmt 1704085262999 \"%F %T\"\n2024-01-01 00:01:02\n```\n\u003c/details\u003e\n\n## LICENSE\n\n[MIT LICENSE](LICENSE)\n\n## Acknowledgements\n\n\u003cdetails\u003e\n\u003csummary\u003eImported Modules\u003c/summary\u003e\n\n* carbon - https://github.com/golang-module/carbon\n* cobra - https://github.com/spf13/cobra\n* durafmt - https://github.com/hako/durafmt\n* parsetime - https://github.com/tkuchiki/parsetime\n* strftime - https://github.com/lestrrat-go/strftime\n\n\u003c/details\u003e\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\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjftuga%2FDateTimeMate","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjftuga%2FDateTimeMate","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjftuga%2FDateTimeMate/lists"}