diff --git a/docs/reference/commandline/logs.md b/docs/reference/commandline/logs.md
index 2c98415ae24c..4a2ef037a320 100644
--- a/docs/reference/commandline/logs.md
+++ b/docs/reference/commandline/logs.md
@@ -9,14 +9,14 @@ Fetch the logs of a container
### Options
-| Name | Type | Default | Description |
-|:---------------------|:---------|:--------|:---------------------------------------------------------------------------------------------------|
-| `--details` | | | Show extra details provided to logs |
-| `-f`, `--follow` | | | Follow log output |
-| `--since` | `string` | | Show logs since timestamp (e.g. `2013-01-02T13:23:37Z`) or relative (e.g. `42m` for 42 minutes) |
-| `-n`, `--tail` | `string` | `all` | Number of lines to show from the end of the logs |
-| `-t`, `--timestamps` | | | Show timestamps |
-| [`--until`](#until) | `string` | | Show logs before a timestamp (e.g. `2013-01-02T13:23:37Z`) or relative (e.g. `42m` for 42 minutes) |
+| Name | Type | Default | Description |
+|:---------------------|:---------|:--------|:-------------------------------------------------------------------------------------------------------------------------------|
+| `--details` | | | Show extra details provided to logs |
+| `-f`, `--follow` | | | Follow log output |
+| [`--since`](#since) | `string` | | Show logs after a [timestamp](#date_formats) (e.g. `2013-01-02T13:23:37Z`) or relative to now (e.g. `42m` for 42 minutes ago) |
+| `-n`, `--tail` | `string` | `all` | Number of lines to show from the end of the logs |
+| `-t`, `--timestamps` | | | Show timestamps |
+| [`--until`](#until) | `string` | | Show logs before a [timestamp](#date_formats) (e.g. `2013-01-02T13:23:37Z`) or relative to now (e.g. `42m` for 42 minutes ago) |
@@ -43,18 +43,32 @@ The `docker logs --details` command will add on extra attributes, such as
environment variables and labels, provided to `--log-opt` when creating the
container.
-The `--since` option shows only the container logs generated after
-a given date. You can specify the date as an RFC 3339 date, a UNIX
-timestamp, or a Go duration string (e.g. `1m30s`, `3h`). Besides RFC3339 date
-format you may also use RFC3339Nano, `2006-01-02T15:04:05`,
-`2006-01-02T15:04:05.999999999`, `2006-01-02Z07:00`, and `2006-01-02`. The local
-timezone on the client will be used if you do not provide either a `Z` or a
-`+-00:00` timezone offset at the end of the timestamp. When providing Unix
-timestamps enter seconds[.nanoseconds], where seconds is the number of seconds
-that have elapsed since January 1, 1970 (midnight UTC/GMT), not counting leap
-seconds (aka Unix epoch or Unix time), and the optional .nanoseconds field is a
-fraction of a second no more than nine digits long. You can combine the
-`--since` option with either or both of the `--follow` or `--tail` options.
+The `--since` option shows only the container logs generated **after**
+a given [timestamp](#date_formats). You can combine the `--since` option with
+either or both of the `--follow` or `--tail` options.
+
+The `--until` option shows only the container logs generated **before** a given
+[timestamp](#date_formats). You can combine the `--since` option with either or
+both of the `--follow` (for timestamps in the future) or `--tail` options.
+
+### Supported timestamp formats
+
+The date values for `--since/--until` can be specified in the following ways:
+* an RFC3339 or RFC3339Nano date string.
+* date strings of the following formats: `2006-01-02`, `2006-01-02Z07:00`,
+ `2006-01-02T15:04:05`, and `2006-01-02T15:04:05.999999999`. Note that if you
+ do not provide either a `Z` or a `+-00:00` timezone offset at the end of the
+ timestamp, the local timezone on the client will be used.
+* Unix timestamps of the form `seconds[.nanoseconds]`, representing the number
+ of seconds that have elapsed since January 1, 1970 (midnight UTC/GMT),
+ not counting leap seconds (aka Unix epoch or Unix time) and an optional
+ `.nanoseconds` field with no more than nine digits for representing
+ fractions of a second.
+* a Go duration string (e.g. `90s`, `1.5m`, `1h30m`) which is subtracted from
+ the Docker client's current time to get the equivalent timestamp. Specifying
+ a negative value (e.g. `-60m`) will lead to a timestamp in the future.
+ Accepts all time measurement units accepted by [`time.ParseDuration()`](https://pkg.go.dev/time#ParseDuration).
+
## Examples
@@ -64,10 +78,30 @@ In order to retrieve logs before a specific point in time, run:
```console
$ docker run --name test -d busybox sh -c "while true; do $(echo date); sleep 1; done"
+$ sleep 5
+$ date
+Tue 14 Nov 2017 16:40:00 CET
+$ docker logs --until=3s test
+Tue 14 Nov 2017 16:39:55 CET
+Tue 14 Nov 2017 16:39:56 CET
+Tue 14 Nov 2017 16:39:57 CET
+
+```
+
+### Follow logs after a specific point in time (--since)
+
+In order to follow logs after a specific point in time, run:
+
+```console
+$ docker run --name test -d busybox sh -c "while true; do $(echo date); sleep 1; done"
+$ sleep 5
$ date
Tue 14 Nov 2017 16:40:00 CET
-$ docker logs -f --until=2s test
+$ docker logs -f --since=3s test
+Tue 14 Nov 2017 16:39:57 CET
+Tue 14 Nov 2017 16:39:58 CET
+Tue 14 Nov 2017 16:39:59 CET
Tue 14 Nov 2017 16:40:00 CET
Tue 14 Nov 2017 16:40:01 CET
-Tue 14 Nov 2017 16:40:02 CET
+...
```