mirror of
https://codeberg.org/scip/ts.git
synced 2025-12-17 20:41:03 +01:00
Doc improvements (#6)
* add default datetime format, fix default format usage * fixed format tests * make reference time configurable * improve doc
This commit is contained in:
T.v.Dein
GitHub
155
README.md
155
README.md
@@ -2,11 +2,137 @@
|
||||
|
||||
generic cli timestamp parser and calculator tool
|
||||
|
||||
## Usage
|
||||
## Introduction
|
||||
|
||||
This little utility is a commandline frontent to the amazing datetime
|
||||
parser module [anytime](https://github.com/ijt/go-anytime). It uses
|
||||
two other modules as fallback if anytime might fail:
|
||||
[now](https://github.com/jinzhu/now) and
|
||||
[dateparse](github.com/araddon/dateparse).
|
||||
|
||||
You can use it to print timestamps from plain english phrases like
|
||||
`next December 23rd AT 5:25 PM` or `two minutes from now`. In addition
|
||||
you can calculate the difference between two timestamps and you can
|
||||
add a duration to a timestamp.
|
||||
|
||||
|
||||
## Example Usage
|
||||
|
||||
In these examples the current time is always **2025-09-17T07:30:00+01:00**.
|
||||
|
||||
Show current date and time (same as `date`):
|
||||
```default
|
||||
% ts now
|
||||
Wed Sep 17 07:30:00 +0100 2025
|
||||
```
|
||||
|
||||
show timestamp for minus 1 hour
|
||||
```default
|
||||
% ts "1 hour ago"
|
||||
Wed Sep 17 06:30:00 +0100 2025
|
||||
```
|
||||
|
||||
... or from a couple days ago:
|
||||
```default
|
||||
% ts "4 days ago"
|
||||
Sat Sep 13 07:30:00 +0100 2025
|
||||
```
|
||||
There are much more ways to get timestamps, see `ts -e`.
|
||||
|
||||
We can also add times to timestamps, here we want to know the
|
||||
timestamp from now plus 10 days and 4 hours in the future:
|
||||
```default
|
||||
% ts -a now 10d4h
|
||||
Sat Sep 27 11:30:00 +0100 2025
|
||||
```
|
||||
|
||||
It doesn't make a difference where you position the `-a` parameter:
|
||||
```default
|
||||
% ts now -a 10d4h
|
||||
Sat Sep 27 11:30:00 +0100 2025
|
||||
```
|
||||
Of course you can also calculate the difference between two
|
||||
dates. Here we have two timestamps (maybe we took them from a log
|
||||
file) and want to know the dime elapsed between them:
|
||||
|
||||
```default
|
||||
This is ts, a timestamp tool.
|
||||
% ts 2025-09-17T07:30:00+01:00 2025-09-15T12:45:00+01:00
|
||||
42h45m0s
|
||||
```
|
||||
As you can see, if you do not provide a parameter, the default is to
|
||||
calculate the difference between the two args. To explicitly calculate
|
||||
the difference, use the `-d` parameter.
|
||||
|
||||
You can of course use english phrases for time differences as well:
|
||||
```default
|
||||
% ts "today 9 am" 2025-09-15T12:45:00+01:00
|
||||
44h15m0s
|
||||
```
|
||||
|
||||
Lets talk a little bit about formatting. You may have already
|
||||
recognized, that `ts` prints either whole timestamps or
|
||||
durations. Both output types can be modified with the `-f`
|
||||
parameter. There are predefined formats for timestamps:
|
||||
|
||||
```default
|
||||
% ts now
|
||||
Wed Sep 17 07:30:00 +0100 2025
|
||||
% ts now -f rfc3339
|
||||
2025-09-17T07:30:00+01:00
|
||||
% ts now -f date
|
||||
2025-09-17
|
||||
% ts now -f unix
|
||||
1758090600
|
||||
```
|
||||
|
||||
But you can also specify your own, you have to follow the [golang
|
||||
rules for timestamp formats](https://pkg.go.dev/time#Layout),
|
||||
basically:
|
||||
|
||||
* Year: "2006" "06"
|
||||
* Month: "Jan" "January" "01" "1"
|
||||
* Day of the week: "Mon" "Monday"
|
||||
* Day of the month: "2" "_2" "02"
|
||||
* Day of the year: "__2" "002"
|
||||
* Hour: "15" "3" "03" (PM or AM)
|
||||
* Minute: "4" "04"
|
||||
* Second: "5" "05"
|
||||
* AM/PM mark: "PM"
|
||||
|
||||
for example:
|
||||
```default
|
||||
% ts now -f "Mon, 02.January 2006"
|
||||
Wed, 17.September 2025
|
||||
```
|
||||
|
||||
Ok I admit look is kinda weird, complaints go the the golang dev team
|
||||
:).
|
||||
|
||||
Duration formatting is also customizable. By default a duration looks
|
||||
like we have seen above: `44h15m0s`. But sometimes we want to know the
|
||||
number of hours or minutes. Easy:
|
||||
|
||||
```default
|
||||
% ts now 2025-09-15T12:45:00+01:00 -f hours
|
||||
42.75
|
||||
% ts now 2025-09-15T12:45:00+01:00 -f minutes
|
||||
2565.00
|
||||
```
|
||||
|
||||
You may also add the `-u` parameter to have the unit shown as well:
|
||||
|
||||
```default
|
||||
% ts now 2025-09-15T12:45:00+01:00 -f hours -u
|
||||
42.75 hours
|
||||
% ts now 2025-09-15T12:45:00+01:00 -f minutes -u
|
||||
2565.00 minutes
|
||||
```
|
||||
|
||||
## Commandline parameters
|
||||
|
||||
Here is the list of all supported parameters:
|
||||
|
||||
```default
|
||||
Usage: ts <time string> [<time string>]
|
||||
-d --diff Calculate difference between two timestamps (default).
|
||||
-a --add Add two timestamps (second parameter must be a time).
|
||||
@@ -21,31 +147,6 @@ Usage: ts <time string> [<time string>]
|
||||
-e --examples Show examples or supported inputs.
|
||||
```
|
||||
|
||||
## Examples
|
||||
|
||||
```default
|
||||
# diff between to day and yesterday 10 am
|
||||
% date && ts today "10am yesterday"
|
||||
Wed Sep 24 02:05:03 PM CEST 2025
|
||||
14h0m0s
|
||||
|
||||
# show timestamp from a couple days ago
|
||||
% date && ts "3 days ago"
|
||||
Wed Sep 24 02:04:42 PM CEST 2025
|
||||
2025-09-21 14:04:42.428910108 +0200 CEST
|
||||
|
||||
# show timestamp of one hour and 45 minutes before (-d is the defaul)
|
||||
% date && ts -d now 1h45m
|
||||
Wed Sep 24 02:04:14 PM CEST 2025
|
||||
2025-09-24 12:19:14.932440045 +0200 CEST
|
||||
|
||||
# 10 hours from now
|
||||
% date && ts --add now 10h
|
||||
Wed Sep 24 02:03:31 PM CEST 2025
|
||||
2025-09-25 00:03:31.304518854 +0200 CEST
|
||||
```
|
||||
|
||||
To see a comprehensive list of supported inputs, call `ts -e`.
|
||||
|
||||
## Installation
|
||||
|
||||
|
||||
Reference in New Issue
Block a user