From 0450a2f4379231b46d90bd97f69082db7c7862b1 Mon Sep 17 00:00:00 2001
From: Jamie Hannaford <jamie@limetree.org>
Date: Tue, 14 Nov 2017 16:43:35 +0100
Subject: [PATCH] Add docs

Signed-off-by: Jamie Hannaford <jamie@limetree.org>
---
 cli/command/container/logs_test.go | 12 ++++++------
 docs/reference/commandline/logs.md | 17 +++++++++++++++++
 man/src/container/logs.md          | 20 ++++++++++++++++----
 3 files changed, 39 insertions(+), 10 deletions(-)

diff --git a/cli/command/container/logs_test.go b/cli/command/container/logs_test.go
index 592989da4d..da64802454 100644
--- a/cli/command/container/logs_test.go
+++ b/cli/command/container/logs_test.go
@@ -13,6 +13,12 @@ import (
 	"github.com/stretchr/testify/assert"
 )
 
+var logFn = func(expectedOut string) func(string, types.ContainerLogsOptions) (io.ReadCloser, error) {
+	return func(container string, opts types.ContainerLogsOptions) (io.ReadCloser, error) {
+		return ioutil.NopCloser(strings.NewReader(expectedOut)), nil
+	}
+}
+
 func TestRunLogs(t *testing.T) {
 	inspectFn := func(containerID string) (types.ContainerJSON, error) {
 		return types.ContainerJSON{
@@ -21,12 +27,6 @@ func TestRunLogs(t *testing.T) {
 		}, nil
 	}
 
-	logFn := func(expectedOut string) func(string, types.ContainerLogsOptions) (io.ReadCloser, error) {
-		return func(container string, opts types.ContainerLogsOptions) (io.ReadCloser, error) {
-			return ioutil.NopCloser(strings.NewReader(expectedOut)), nil
-		}
-	}
-
 	var testcases = []struct {
 		doc           string
 		options       *logsOptions
diff --git a/docs/reference/commandline/logs.md b/docs/reference/commandline/logs.md
index a71251c2d5..d004b44f90 100644
--- a/docs/reference/commandline/logs.md
+++ b/docs/reference/commandline/logs.md
@@ -25,6 +25,7 @@ Options:
   -f, --follow         Follow log output
       --help           Print usage
       --since string   Show logs since timestamp (e.g. 2013-01-02T13:23:37) or relative (e.g. 42m for 42 minutes)
+      --until string   Show logs before timestamp (e.g. 2013-01-02T13:23:37) or relative (e.g. 42m for 42 minutes)
       --tail string    Number of lines to show from the end of the logs (default "all")
   -t, --timestamps     Show timestamps
 ```
@@ -66,3 +67,19 @@ 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.
+
+## Examples
+
+### Retrieve logs until a specific point in time
+
+In order to retrieve logs before a specific point in time, run:
+
+```bash
+$ docker run --name test -d busybox sh -c "while true; do $(echo date); sleep 1; done"
+$ date
+Tue 14 Nov 2017 16:40:00 CET
+$ docker logs -f --until=2s
+Tue 14 Nov 2017 16:40:00 CET
+Tue 14 Nov 2017 16:40:01 CET
+Tue 14 Nov 2017 16:40:02 CET
+```
\ No newline at end of file
diff --git a/man/src/container/logs.md b/man/src/container/logs.md
index c053f85758..f2b4ad6d2d 100644
--- a/man/src/container/logs.md
+++ b/man/src/container/logs.md
@@ -10,8 +10,8 @@ then continue streaming new output from the container's stdout and stderr.
 **Warning**: This command works only for the **json-file** or **journald**
 logging drivers.
 
-The `--since` option can be Unix timestamps, date formatted timestamps, or Go
-duration strings (e.g. `10m`, `1h30m`) computed relative to the client machine's
+The `--since` and `--until` options can be Unix timestamps, date formatted timestamps, 
+or Go duration strings (e.g. `10m`, `1h30m`) computed relative to the client machine's
 time. Supported formats for date formatted time stamps include RFC3339Nano,
 RFC3339, `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
@@ -20,9 +20,21 @@ 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.
+second no more than nine digits long. You can combine the `--since` or `--until` 
+options with either or both of the `--follow` or `--tail` options.
 
 The `docker container logs --details` command will add on extra attributes, such as
 environment variables and labels, provided to `--log-opt` when creating the
 container.
+
+In order to retrieve logs before a specific point in time, run:
+
+```bash
+$ docker run --name test -d busybox sh -c "while true; do $(echo date); sleep 1; done"
+$ date
+Tue 14 Nov 2017 16:40:00 CET
+$ docker logs -f --until=2s
+Tue 14 Nov 2017 16:40:00 CET
+Tue 14 Nov 2017 16:40:01 CET
+Tue 14 Nov 2017 16:40:02 CET
+```
\ No newline at end of file