s3: implement --s3-version-at flag - Fixes #1776

docs/content/s3.md

@@ -394,7 +394,13 @@ Likewise when you delete a file, the old version will be marked hidden
 and still be available.
 
 Old versions of files, where available, are visible using the
-`--s3-versions` flag.
+[`--s3-versions`](#s3-versions) flag.
+
+It is also possible to view a bucket as it was at a certain point in
+time, using the [`--s3-version-at`](#s3-version-at) flag. This will
+show the file versions as they were at that time, showing files that
+have been deleted afterwards, and hiding files that were created
+since.
 
 If you wish to remove all the old versions then you can use the
 [`rclone backend cleanup-hidden remote:bucket`](#cleanup-hidden)
@@ -2635,6 +2641,26 @@ Properties:
 - Type:        bool
 - Default:     false
 
+#### --s3-version-at
+
+Show file versions as they were at the specified time.
+
+The parameter should be a date, "2006-01-02", datetime "2006-01-02
+15:04:05" or a duration for that long ago, eg "100d" or "1h".
+
+Note that when using this no file write operations are permitted,
+so you can't upload files or delete them.
+
+See [the time option docs](/docs/#time-option) for valid formats.
+
+
+Properties:
+
+- Config:      version_at
+- Env Var:     RCLONE_S3_VERSION_AT
+- Type:        Time
+- Default:     off
+
 ### Metadata
 
 User metadata is stored as x-amz-meta- keys. S3 metadata keys are case insensitive and are always returned in lower case.