.. Taken from http://wiki.bazaar.canonical.com/CasePreservingWorkingTreeUseCases
.. FIXME: Probobly needs a bit of restructuring and Rework.
.. FIXME: Remove "we" "he" "she" "they" -> Write more like a scientific paper.

Case Preserving Working Tree Use Cases
======================================

This document attempts to describe the desired semantics for Breezy using the
bzr format on a Windows file system. Most Windows file systems are "case
preserving", in that the original case given for a filename is retained, even
though any case can be used to access the file. This is in contrast to some
file-systems, used on Windows and elsewhere, that are truly case-insensitve. 


This document is intended to be in a "psuedo-doctest" format. Lines beginning
with '``%``' are entered at a command-prompt, while lines beginning with '``>``'
are intended to show that command's output. Where the desired behaviour differs
from the current behaviour is marked with lines starting with '``***``'. 

Before we start you will need a repository to work with:

.. code-block:: none
  
  % [make and change into a temp working directory]
  % bzr init

Windows is a case-preserving file-system. Note that it doesn't matter what case
we use when asking for the file - we always get back the exact case the file was
created with.

.. code-block:: none
  
  % touch Foo
  % dir foo
  > ...
  > 09/10/2008  01:40 PM                 0 Foo
  % dir Foo
  > ...
  > 09/10/2008  01:40 PM                 0 Foo
  % if exist Foo echo Yes
  > Yes
  % if exist foo echo Yes
  > Yes

Bzr should attempt to use the name on the file-system rather than the name
supplied by the user.

.. code-block:: none
  
  % bzr add foo
  *** current behaviour ***
  > added foo
  *** expected behaviour ***
  > added Foo
  
  % bzr status
  *** current behaviour ***
  > unknown:
  >   Foo
  *** expected behaviour ***
  > added:
  >  Foo

Supplying the incorrect case to a file already in the inventory should work
correctly. Let's add a new file to bzr with the correct case:

.. code-block:: none
  
  % touch lower
  % bzr add lower
  > added lower

If Windows lets them see it with a given name:

.. code-block:: none
  
  % dir Lower
  > ...
  > 09/10/2008  01:48 PM                 0 lower

Bzr should too:

.. code-block:: none
  
  % bzr status Lower
  *** current behaviour ***
  > unknown:
  >   Lower
  *** expected behaviour ***
  > added:
  >   lower

All comments which accept a filename need to handle this situation. Eg, rm:

.. code-block:: none
  
  % [make and change into a temp working directory]
  % bzr init
  > ...
  % touch Foo lower
  % bzr add
  > added Foo
  > added lower
  % bzr ci -m "some changes"
  > ...
  
  % bzr rm foo Lower
  *** current behaviour ***
  > bzr: ERROR: Can't safely remove modified or unknown files:
  > unknown:
  >   foo
  >   Lower
  > Use --keep to not delete them, or --force to delete them regardless.
  *** expected behaviour ***
  > deleted lower
  > deleted Foo

If an external program changes the case of the file underneath us, it must not
phase us.

.. code-block:: none
  
  % bzr revert
  > +N  Foo
  > +N  lower
  
  % rm Foo
  % echo hello > foo
  % bzr status
  *** current behaviour ***
  > removed:
  >   Foo
  > unknown:
  >   foo
  *** expected behaviour ***
  > modified:
  >   Foo

And reverting a tree in that state should restore the case of the file:

.. code-block:: none
  
  % bzr revert
  *** current behaviour ***
  >  M  Foo
  > Conflict adding file Foo.  Moved existing file to foo.moved.
  *** expected behaviour ***
  > M Foo

But if the user really wants bzr to see the new name, she just does 'bzr mv' as
normal.