/brz/remove-bazaar : contents of doc/developers/case-preserving-working-tree-use-cases.txt at revision 7532

: (revision 7532)

To get this branch, use:

bzr branch
http://gegoxaren.bato24.eu/bzr/brz/remove-bazaar

.. 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. 

7531 by Gustav Hartvigsson Added 'Case Preserving Working Tree Use Cases' from Canonical Wiki	1	.. Taken from http://wiki.bazaar.canonical.com/CasePreservingWorkingTreeUseCases
	2	.. FIXME: Probobly needs a bit of restructuring and Rework.
	3	.. FIXME: Remove "we" "he" "she" "they" -> Write more like a scientific paper.
	4
	5	Case Preserving Working Tree Use Cases
	6	======================================
	7
	8	This document attempts to describe the desired semantics for Breezy using the
	9	bzr format on a Windows file system. Most Windows file systems are "case
	10	preserving", in that the original case given for a filename is retained, even
	11	though any case can be used to access the file. This is in contrast to some
	12	file-systems, used on Windows and elsewhere, that are truly case-insensitve.
	13
	14
	15	This document is intended to be in a "psuedo-doctest" format. Lines beginning
	16	with '``%``' are entered at a command-prompt, while lines beginning with '``>``'
	17	are intended to show that command's output. Where the desired behaviour differs
	18	from the current behaviour is marked with lines starting with '``***``'.
	19
	20	Before we start you will need a repository to work with:
	21
	22	.. code-block:: none
	23
	24	% [make and change into a temp working directory]
	25	% bzr init
	26
	27	Windows is a case-preserving file-system. Note that it doesn't matter what case
	28	we use when asking for the file - we always get back the exact case the file was
	29	created with.
	30
	31	.. code-block:: none
	32
	33	% touch Foo
	34	% dir foo
	35	> ...
	36	> 09/10/2008 01:40 PM 0 Foo
	37	% dir Foo
	38	> ...
	39	> 09/10/2008 01:40 PM 0 Foo
	40	% if exist Foo echo Yes
	41	> Yes
	42	% if exist foo echo Yes
	43	> Yes
	44
	45	Bzr should attempt to use the name on the file-system rather than the name
	46	supplied by the user.
	47
	48	.. code-block:: none
	49
	50	% bzr add foo
	51	* current behaviour *
	52	> added foo
	53	* expected behaviour *
	54	> added Foo
	55
	56	% bzr status
	57	* current behaviour *
	58	> unknown:
	59	> Foo
	60	* expected behaviour *
	61	> added:
	62	> Foo
	63
	64	Supplying the incorrect case to a file already in the inventory should work
65	correctly. Let's add a new file to bzr with the correct case:
66
67	.. code-block:: none
68
69	% touch lower
70	% bzr add lower
71	> added lower
72
73	If Windows lets them see it with a given name:
74
75	.. code-block:: none
76
77	% dir Lower
78	> ...
79	> 09/10/2008 01:48 PM 0 lower
80
81	Bzr should too:
82
83	.. code-block:: none
84
85	% bzr status Lower
86	* current behaviour *
87	> unknown:
88	> Lower
89	* expected behaviour *
90	> added:
91	> lower
92
93	All comments which accept a filename need to handle this situation. Eg, rm:
94
95	.. code-block:: none
96
97	% [make and change into a temp working directory]
98	% bzr init
99	> ...
100	% touch Foo lower
101	% bzr add
102	> added Foo
103	> added lower
104	% bzr ci -m "some changes"
105	> ...
106
107	% bzr rm foo Lower
108	* current behaviour *
109	> bzr: ERROR: Can't safely remove modified or unknown files:
110	> unknown:
111	> foo
112	> Lower
113	> Use --keep to not delete them, or --force to delete them regardless.
114	* expected behaviour *
115	> deleted lower
116	> deleted Foo
117
118	If an external program changes the case of the file underneath us, it must not
119	phase us.
120
121	.. code-block:: none
122
123	% bzr revert
124	> +N Foo
125	> +N lower
126
127	% rm Foo
128	% echo hello > foo
129	% bzr status
130	* current behaviour *
131	> removed:
132	> Foo
133	> unknown:
134	> foo
135	* expected behaviour *
136	> modified:
137	> Foo
138
139	And reverting a tree in that state should restore the case of the file:
140
141	.. code-block:: none
142
143	% bzr revert
144	* current behaviour *
145	> M Foo
146	> Conflict adding file Foo. Moved existing file to foo.moved.
147	* expected behaviour *
148	> M Foo
149
150	But if the user really wants bzr to see the new name, she just does 'bzr mv' as
151	normal.