Path Argument Type¶

Whenever using a command, at least one path argument must be specified. Thereare two types of path arguments:LocalPath andS3Uri.

LocalPath: represents the path of a local file or directory. It can bewritten as an absolute path or relative path.

S3Uri: represents the location of a S3 object, prefix, or bucket. Thismust be written in the forms3://amzn-s3-demo-bucket/mykey whereamzn-s3-demo-bucket isthe specified S3 bucket,mykey is the specified S3 key. The path argumentmust begin withs3:// in order to denote that the path argument refers toa S3 object. Note that prefixes are separated by forward slashes. Forexample, if the S3 objectmyobject had the prefixmyprefix, theS3 key would bemyprefix/myobject, and if the object was in the bucketamzn-s3-demo-bucket, theS3Uri would bes3://amzn-s3-demo-bucket/myprefix/myobject.

S3Uri also supports S3 access points. To specify an access point, thisvalue must be of the forms3://<access-point-arn>/<key>. For example ifthe access pointmyaccesspoint to be used has the ARN:arn:aws:s3:us-west-2:123456789012:accesspoint/myaccesspoint and the objectbeing accessed has the keymykey, then theS3URI used must be:s3://arn:aws:s3:us-west-2:123456789012:accesspoint/myaccesspoint/mykey.Similar to bucket names, you can also use prefixes with access point ARNs fortheS3Uri. For example:s3://arn:aws:s3:us-west-2:123456789012:accesspoint/myaccesspoint/myprefix/

Order of Path Arguments¶

Every command takes one or two positional path arguments. The first pathargument represents the source, which is the local file/directory or S3object/prefix/bucket that is being referenced. If there is a second pathargument, it represents the destination, which is the local file/directoryor S3 object/prefix/bucket that is being operated on. Commands with onlyone path argument do not have a destination because the operation is beingperformed only on the source.

Single Local File and S3 Object Operations¶

Some commands perform operations only on single files and S3 objects. Thefollowing commands are single file/object operations if no--recursiveflag is provided.

• cp
• mv
• rm

For this type of operation, the first path argument, the source, must existand be a local file or S3 object. The second path argument, the destination,can be the name of a local file, local directory, S3 object, S3 prefix,or S3 bucket.

The destination is indicated as a local directory, S3 prefix, or S3 bucketif it ends with a forward slash or back slash. The use of slash dependson the path argument type. If the path argument is aLocalPath,the type of slash is the separator used by the operating system. If thepath is aS3Uri, the forward slash must always be used. If a slashis at the end of the destination, the destination file or object willadopt the name of the source file or object. Otherwise, if there is noslash at the end, the file or object will be saved under the name provided.See examples incp andmv to illustrate this description.

Directory and S3 Prefix Operations¶

Some commands only perform operations on the contents of a local directoryor S3 prefix/bucket. Adding or omitting a forward slash or back slash tothe end of any path argument, depending on its type, does not affect theresults of the operation. The following commands will always result ina directory or S3 prefix/bucket operation:

• sync
• mb
• rb
• ls

Use of Exclude and Include Filters¶

Currently, there is no support for the use of UNIX style wildcards ina command’s path arguments. However, most commands have--exclude"<value>"and--include"<value>" parameters that can achieve the desired result.These parameters perform pattern matching to either exclude or includea particular file or object. The following pattern symbols are supported.

• *: Matches everything
• ?: Matches any single character
• [sequence]: Matches any character insequence
• [!sequence]: Matches any character not insequence

Any number of these parameters can be passed to a command. You can do this byproviding an--exclude or--include argument multiple times, e.g.--include"*.txt"--include"*.png".When there are multiple filters, the rule is the filters that appear later inthe command take precedence over filters that appear earlier in the command.For example, if the filter parameters passed to the command were

--exclude"*"--include"*.txt"

All files will be excluded from the command except for files ending with.txt However, if the order of the filter parameters was changed to

--include"*.txt"--exclude"*"

All files will be excluded from the command.

Each filter is evaluated against thesource directory. If the sourcelocation is a file instead of a directory, the directory containing the file isused as the source directory. For example, suppose you had the followingdirectory structure:

/tmp/foo/.git/|---config|---descriptionfoo.txtbar.txtbaz.jpg

In the commandawss3sync/tmp/foos3://bucket/ the source directory is/tmp/foo. Any include/exclude filters will be evaluated with the sourcedirectory prepended. Below are several examples to demonstrate this.

Given the directory structure above and the commandawss3cp/tmp/foos3://bucket/--recursive--exclude".git/*", thefiles.git/config and.git/description will be excluded from thefiles to upload because the exclude filter.git/* will have the sourceprepended to the filter. This means that:

/tmp/foo/.git/*->/tmp/foo/.git/config(matches,shouldexclude)/tmp/foo/.git/*->/tmp/foo/.git/description(matches,shouldexclude)/tmp/foo/.git/*->/tmp/foo/foo.txt(doesnotmatch,shouldinclude)/tmp/foo/.git/*->/tmp/foo/bar.txt(doesnotmatch,shouldinclude)/tmp/foo/.git/*->/tmp/foo/baz.jpg(doesnotmatch,shouldinclude)

The commandawss3cp/tmp/foo/s3://bucket/--recursive--exclude"ba*"will exclude/tmp/foo/bar.txt and/tmp/foo/baz.jpg:

/tmp/foo/ba*->/tmp/foo/.git/config(doesnotmatch,shouldinclude)/tmp/foo/ba*->/tmp/foo/.git/description(doesnotmatch,shouldinclude)/tmp/foo/ba*->/tmp/foo/foo.txt(doesnotmatch,shouldinclude)/tmp/foo/ba*->/tmp/foo/bar.txt(matches,shouldexclude)/tmp/foo/ba*->/tmp/foo/baz.jpg(matches,shouldexclude)

Note that, by default,all files are included. This means thatprovidingonly an--include filter will not change whatfiles are transferred.--include will only re-include files thathave been excluded from an--exclude filter. If you only wantto upload files with a particular extension, you need to first excludeall files, then re-include the files with the particular extension.This command will uploadonly files ending with.jpg:

awss3cp/tmp/foo/s3://bucket/--recursive--exclude"*"--include"*.jpg"

If you wanted to include both.jpg files as well as.txt files youcan run:

awss3cp/tmp/foo/s3://bucket/--recursive \--exclude"*"--include"*.jpg"--include"*.txt"

• cp
• ls
• mb
• mv
• presign
• rb
• rm
• sync
• website