: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
