name : s3-case-insensitivity.rst :title: AWS CLI S3 Case-Insensitivity :description: Using 'aws s3' commands on case-insensitive filesystems :category: S3 :related command: s3 cp, s3 sync, s3 mv This page explains how to detect and handle potential case conflicts when downloading multiple objects from S3 to a local case-insensitive filesystem using a single AWS CLI command. Case conflicts ============== S3 object keys are case-sensitive meaning that a bucket can have a set of key names that differ only by case, for example, ``a.txt`` and ``A.txt``. The AWS CLI offers high-level S3 commands that manage transfers of multiple S3 objects using a single command: * ``aws s3 sync`` * ``aws s3 cp --recursive`` * ``aws s3 mv --recursive`` Case conflicts can occur on case-insensitive filesystems when an S3 bucket has multiple objects whose keys differ only by case and a single AWS CLI command is called to download multiple S3 objects **OR** a local file already exists whose name differs only by case. For example, consider an S3 bucket with the following stored objects: * ``a.txt`` * ``A.txt`` When the following AWS CLI command is called, the AWS CLI will submit requests to download ``a.txt`` and ``A.txt``. Since only one can exist on a case-insensitive filesystem, the last download to finish will be the file that's locally available. .. code-block:: aws s3 sync s3://examplebucket ./mylocaldir Detecting and handling case conflicts ===================================== To detect and handle case conflicts, you can specify the ``--case-conflict`` parameter. The following values are valid options: * ``error`` - When a case conflict is detected, the command will immediately fail and abort in-progress downloads. * ``warn`` - When a case conflict is detected, the AWS CLI will display a warning. * ``skip`` - When a case conflict is detected, the command will skip downloading the object and continue and display a warning. * ``ignore`` - (Default) Case conflicts will not be detected or handled. Continuing the prior example, the following describes what happens when appending the ``--case-conflict`` parameter with possible values: ``--case-conflict error`` 1. Submit a download request for ``A.txt``. 2. Detect that ``a.txt`` conflicts with an object that's been submitted for download. 3. Throw an error. If ``A.txt`` finished downloading, it will be locally available. Otherwise, the download request for ``A.txt`` will be aborted. ``--case-conflict warn`` 1. Submit a download request for ``A.txt``. 2. Detect that ``a.txt`` conflicts with an object that's been submitted for download. 3. Display a warning. 4. Submit a download request for ``a.txt``, downloading ``A.txt`` and ``a.txt`` in parallel. ``--case-conflict skip`` 1. Submit a download request for ``A.txt``. 2. Detect that ``a.txt`` conflicts with an object that's been submitted for download. 3. Skip downloading ``a.txt`` and continue. ``--case-conflict ignore`` 1. Submit a download request for ``A.txt``. 2. Submit a download request for ``a.txt``, downloading ``A.txt`` and ``a.txt`` in parallel. If your local filesystem is case-sensitive, there's no need to detect and handle case conflicts. We recommend setting ``--case-conflict ignore`` in this case. S3 Express directory buckets ============================ Detecting case conflicts is **NOT** supported when the source is an S3 Express directory bucket. When operating on directory buckets, valid values for the ``--case-conflict`` parameter are: * ``warn`` * ``ignore`` The following values are invalid when operating on directory buckets: * ``error`` * ``skip`` For example, calling the following command will fail: .. code-block:: aws s3 cp s3://mydirbucket--usw2-az1--x-s3 ./mylocaldir --recursive --case-conflict error