Mercurial > hgbook
comparison en/ch06-filenames.xml @ 683:c838b3975bc6
Add IDs to paragraphs.
author | Bryan O'Sullivan <bos@serpentine.com> |
---|---|
date | Thu, 19 Mar 2009 21:18:52 -0700 |
parents | 28b5a5befb08 |
children | 1c13ed2130a7 |
comparison
equal
deleted
inserted
replaced
682:28b5a5befb08 | 683:c838b3975bc6 |
---|---|
2 | 2 |
3 <chapter id="chap:names"> | 3 <chapter id="chap:names"> |
4 <?dbhtml filename="file-names-and-pattern-matching.html"?> | 4 <?dbhtml filename="file-names-and-pattern-matching.html"?> |
5 <title>File names and pattern matching</title> | 5 <title>File names and pattern matching</title> |
6 | 6 |
7 <para>Mercurial provides mechanisms that let you work with file | 7 <para id="x_543">Mercurial provides mechanisms that let you work with file |
8 names in a consistent and expressive way.</para> | 8 names in a consistent and expressive way.</para> |
9 | 9 |
10 <sect1> | 10 <sect1> |
11 <title>Simple file naming</title> | 11 <title>Simple file naming</title> |
12 | 12 |
13 <para>Mercurial uses a unified piece of machinery <quote>under the | 13 <para id="x_544">Mercurial uses a unified piece of machinery <quote>under the |
14 hood</quote> to handle file names. Every command behaves | 14 hood</quote> to handle file names. Every command behaves |
15 uniformly with respect to file names. The way in which commands | 15 uniformly with respect to file names. The way in which commands |
16 work with file names is as follows.</para> | 16 work with file names is as follows.</para> |
17 | 17 |
18 <para>If you explicitly name real files on the command line, | 18 <para id="x_545">If you explicitly name real files on the command line, |
19 Mercurial works with exactly those files, as you would expect. | 19 Mercurial works with exactly those files, as you would expect. |
20 &interaction.filenames.files;</para> | 20 &interaction.filenames.files;</para> |
21 | 21 |
22 <para>When you provide a directory name, Mercurial will interpret | 22 <para id="x_546">When you provide a directory name, Mercurial will interpret |
23 this as <quote>operate on every file in this directory and its | 23 this as <quote>operate on every file in this directory and its |
24 subdirectories</quote>. Mercurial traverses the files and | 24 subdirectories</quote>. Mercurial traverses the files and |
25 subdirectories in a directory in alphabetical order. When it | 25 subdirectories in a directory in alphabetical order. When it |
26 encounters a subdirectory, it will traverse that subdirectory | 26 encounters a subdirectory, it will traverse that subdirectory |
27 before continuing with the current directory.</para> | 27 before continuing with the current directory.</para> |
30 | 30 |
31 </sect1> | 31 </sect1> |
32 <sect1> | 32 <sect1> |
33 <title>Running commands without any file names</title> | 33 <title>Running commands without any file names</title> |
34 | 34 |
35 <para>Mercurial's commands that work with file names have useful | 35 <para id="x_547">Mercurial's commands that work with file names have useful |
36 default behaviours when you invoke them without providing any | 36 default behaviours when you invoke them without providing any |
37 file names or patterns. What kind of behaviour you should | 37 file names or patterns. What kind of behaviour you should |
38 expect depends on what the command does. Here are a few rules | 38 expect depends on what the command does. Here are a few rules |
39 of thumb you can use to predict what a command is likely to do | 39 of thumb you can use to predict what a command is likely to do |
40 if you don't give it any names to work with.</para> | 40 if you don't give it any names to work with.</para> |
41 <itemizedlist> | 41 <itemizedlist> |
42 <listitem><para>Most commands will operate on the entire working | 42 <listitem><para id="x_548">Most commands will operate on the entire working |
43 directory. This is what the <command role="hg-cmd">hg | 43 directory. This is what the <command role="hg-cmd">hg |
44 add</command> command does, for example.</para> | 44 add</command> command does, for example.</para> |
45 </listitem> | 45 </listitem> |
46 <listitem><para>If the command has effects that are difficult or | 46 <listitem><para id="x_549">If the command has effects that are difficult or |
47 impossible to reverse, it will force you to explicitly | 47 impossible to reverse, it will force you to explicitly |
48 provide at least one name or pattern (see below). This | 48 provide at least one name or pattern (see below). This |
49 protects you from accidentally deleting files by running | 49 protects you from accidentally deleting files by running |
50 <command role="hg-cmd">hg remove</command> with no | 50 <command role="hg-cmd">hg remove</command> with no |
51 arguments, for example.</para> | 51 arguments, for example.</para> |
52 </listitem></itemizedlist> | 52 </listitem></itemizedlist> |
53 | 53 |
54 <para>It's easy to work around these default behaviours if they | 54 <para id="x_54a">It's easy to work around these default behaviours if they |
55 don't suit you. If a command normally operates on the whole | 55 don't suit you. If a command normally operates on the whole |
56 working directory, you can invoke it on just the current | 56 working directory, you can invoke it on just the current |
57 directory and its subdirectories by giving it the name | 57 directory and its subdirectories by giving it the name |
58 <quote><filename class="directory">.</filename></quote>.</para> | 58 <quote><filename class="directory">.</filename></quote>.</para> |
59 | 59 |
60 &interaction.filenames.wdir-subdir; | 60 &interaction.filenames.wdir-subdir; |
61 | 61 |
62 <para>Along the same lines, some commands normally print file | 62 <para id="x_54b">Along the same lines, some commands normally print file |
63 names relative to the root of the repository, even if you're | 63 names relative to the root of the repository, even if you're |
64 invoking them from a subdirectory. Such a command will print | 64 invoking them from a subdirectory. Such a command will print |
65 file names relative to your subdirectory if you give it explicit | 65 file names relative to your subdirectory if you give it explicit |
66 names. Here, we're going to run <command role="hg-cmd">hg | 66 names. Here, we're going to run <command role="hg-cmd">hg |
67 status</command> from a subdirectory, and get it to operate on | 67 status</command> from a subdirectory, and get it to operate on |
73 | 73 |
74 </sect1> | 74 </sect1> |
75 <sect1> | 75 <sect1> |
76 <title>Telling you what's going on</title> | 76 <title>Telling you what's going on</title> |
77 | 77 |
78 <para>The <command role="hg-cmd">hg add</command> example in the | 78 <para id="x_54c">The <command role="hg-cmd">hg add</command> example in the |
79 preceding section illustrates something else that's helpful | 79 preceding section illustrates something else that's helpful |
80 about Mercurial commands. If a command operates on a file that | 80 about Mercurial commands. If a command operates on a file that |
81 you didn't name explicitly on the command line, it will usually | 81 you didn't name explicitly on the command line, it will usually |
82 print the name of the file, so that you will not be surprised | 82 print the name of the file, so that you will not be surprised |
83 what's going on.</para> | 83 what's going on.</para> |
84 | 84 |
85 <para>The principle here is of <emphasis>least | 85 <para id="x_54d">The principle here is of <emphasis>least |
86 surprise</emphasis>. If you've exactly named a file on the | 86 surprise</emphasis>. If you've exactly named a file on the |
87 command line, there's no point in repeating it back at you. If | 87 command line, there's no point in repeating it back at you. If |
88 Mercurial is acting on a file <emphasis>implicitly</emphasis>, | 88 Mercurial is acting on a file <emphasis>implicitly</emphasis>, |
89 because you provided no names, or a directory, or a pattern (see | 89 because you provided no names, or a directory, or a pattern (see |
90 below), it's safest to tell you what it's doing.</para> | 90 below), it's safest to tell you what it's doing.</para> |
91 | 91 |
92 <para>For commands that behave this way, you can silence them | 92 <para id="x_54e">For commands that behave this way, you can silence them |
93 using the <option role="hg-opt-global">-q</option> option. You | 93 using the <option role="hg-opt-global">-q</option> option. You |
94 can also get them to print the name of every file, even those | 94 can also get them to print the name of every file, even those |
95 you've named explicitly, using the <option | 95 you've named explicitly, using the <option |
96 role="hg-opt-global">-v</option> option.</para> | 96 role="hg-opt-global">-v</option> option.</para> |
97 | 97 |
98 </sect1> | 98 </sect1> |
99 <sect1> | 99 <sect1> |
100 <title>Using patterns to identify files</title> | 100 <title>Using patterns to identify files</title> |
101 | 101 |
102 <para>In addition to working with file and directory names, | 102 <para id="x_54f">In addition to working with file and directory names, |
103 Mercurial lets you use <emphasis>patterns</emphasis> to identify | 103 Mercurial lets you use <emphasis>patterns</emphasis> to identify |
104 files. Mercurial's pattern handling is expressive.</para> | 104 files. Mercurial's pattern handling is expressive.</para> |
105 | 105 |
106 <para>On Unix-like systems (Linux, MacOS, etc.), the job of | 106 <para id="x_550">On Unix-like systems (Linux, MacOS, etc.), the job of |
107 matching file names to patterns normally falls to the shell. On | 107 matching file names to patterns normally falls to the shell. On |
108 these systems, you must explicitly tell Mercurial that a name is | 108 these systems, you must explicitly tell Mercurial that a name is |
109 a pattern. On Windows, the shell does not expand patterns, so | 109 a pattern. On Windows, the shell does not expand patterns, so |
110 Mercurial will automatically identify names that are patterns, | 110 Mercurial will automatically identify names that are patterns, |
111 and expand them for you.</para> | 111 and expand them for you.</para> |
112 | 112 |
113 <para>To provide a pattern in place of a regular name on the | 113 <para id="x_551">To provide a pattern in place of a regular name on the |
114 command line, the mechanism is simple:</para> | 114 command line, the mechanism is simple:</para> |
115 <programlisting>syntax:patternbody</programlisting> | 115 <programlisting>syntax:patternbody</programlisting> |
116 <para>That is, a pattern is identified by a short text string that | 116 <para id="x_552">That is, a pattern is identified by a short text string that |
117 says what kind of pattern this is, followed by a colon, followed | 117 says what kind of pattern this is, followed by a colon, followed |
118 by the actual pattern.</para> | 118 by the actual pattern.</para> |
119 | 119 |
120 <para>Mercurial supports two kinds of pattern syntax. The most | 120 <para id="x_553">Mercurial supports two kinds of pattern syntax. The most |
121 frequently used is called <literal>glob</literal>; this is the | 121 frequently used is called <literal>glob</literal>; this is the |
122 same kind of pattern matching used by the Unix shell, and should | 122 same kind of pattern matching used by the Unix shell, and should |
123 be familiar to Windows command prompt users, too.</para> | 123 be familiar to Windows command prompt users, too.</para> |
124 | 124 |
125 <para>When Mercurial does automatic pattern matching on Windows, | 125 <para id="x_554">When Mercurial does automatic pattern matching on Windows, |
126 it uses <literal>glob</literal> syntax. You can thus omit the | 126 it uses <literal>glob</literal> syntax. You can thus omit the |
127 <quote><literal>glob:</literal></quote> prefix on Windows, but | 127 <quote><literal>glob:</literal></quote> prefix on Windows, but |
128 it's safe to use it, too.</para> | 128 it's safe to use it, too.</para> |
129 | 129 |
130 <para>The <literal>re</literal> syntax is more powerful; it lets | 130 <para id="x_555">The <literal>re</literal> syntax is more powerful; it lets |
131 you specify patterns using regular expressions, also known as | 131 you specify patterns using regular expressions, also known as |
132 regexps.</para> | 132 regexps.</para> |
133 | 133 |
134 <para>By the way, in the examples that follow, notice that I'm | 134 <para id="x_556">By the way, in the examples that follow, notice that I'm |
135 careful to wrap all of my patterns in quote characters, so that | 135 careful to wrap all of my patterns in quote characters, so that |
136 they won't get expanded by the shell before Mercurial sees | 136 they won't get expanded by the shell before Mercurial sees |
137 them.</para> | 137 them.</para> |
138 | 138 |
139 <sect2> | 139 <sect2> |
140 <title>Shell-style <literal>glob</literal> patterns</title> | 140 <title>Shell-style <literal>glob</literal> patterns</title> |
141 | 141 |
142 <para>This is an overview of the kinds of patterns you can use | 142 <para id="x_557">This is an overview of the kinds of patterns you can use |
143 when you're matching on glob patterns.</para> | 143 when you're matching on glob patterns.</para> |
144 | 144 |
145 <para>The <quote><literal>*</literal></quote> character matches | 145 <para id="x_558">The <quote><literal>*</literal></quote> character matches |
146 any string, within a single directory.</para> | 146 any string, within a single directory.</para> |
147 | 147 |
148 &interaction.filenames.glob.star; | 148 &interaction.filenames.glob.star; |
149 | 149 |
150 <para>The <quote><literal>**</literal></quote> pattern matches | 150 <para id="x_559">The <quote><literal>**</literal></quote> pattern matches |
151 any string, and crosses directory boundaries. It's not a | 151 any string, and crosses directory boundaries. It's not a |
152 standard Unix glob token, but it's accepted by several popular | 152 standard Unix glob token, but it's accepted by several popular |
153 Unix shells, and is very useful.</para> | 153 Unix shells, and is very useful.</para> |
154 | 154 |
155 &interaction.filenames.glob.starstar; | 155 &interaction.filenames.glob.starstar; |
156 | 156 |
157 <para>The <quote><literal>?</literal></quote> pattern matches | 157 <para id="x_55a">The <quote><literal>?</literal></quote> pattern matches |
158 any single character.</para> | 158 any single character.</para> |
159 | 159 |
160 &interaction.filenames.glob.question; | 160 &interaction.filenames.glob.question; |
161 | 161 |
162 <para>The <quote><literal>[</literal></quote> character begins a | 162 <para id="x_55b">The <quote><literal>[</literal></quote> character begins a |
163 <emphasis>character class</emphasis>. This matches any single | 163 <emphasis>character class</emphasis>. This matches any single |
164 character within the class. The class ends with a | 164 character within the class. The class ends with a |
165 <quote><literal>]</literal></quote> character. A class may | 165 <quote><literal>]</literal></quote> character. A class may |
166 contain multiple <emphasis>range</emphasis>s of the form | 166 contain multiple <emphasis>range</emphasis>s of the form |
167 <quote><literal>a-f</literal></quote>, which is shorthand for | 167 <quote><literal>a-f</literal></quote>, which is shorthand for |
168 <quote><literal>abcdef</literal></quote>.</para> | 168 <quote><literal>abcdef</literal></quote>.</para> |
169 | 169 |
170 &interaction.filenames.glob.range; | 170 &interaction.filenames.glob.range; |
171 | 171 |
172 <para>If the first character after the | 172 <para id="x_55c">If the first character after the |
173 <quote><literal>[</literal></quote> in a character class is a | 173 <quote><literal>[</literal></quote> in a character class is a |
174 <quote><literal>!</literal></quote>, it | 174 <quote><literal>!</literal></quote>, it |
175 <emphasis>negates</emphasis> the class, making it match any | 175 <emphasis>negates</emphasis> the class, making it match any |
176 single character not in the class.</para> | 176 single character not in the class.</para> |
177 | 177 |
178 <para>A <quote><literal>{</literal></quote> begins a group of | 178 <para id="x_55d">A <quote><literal>{</literal></quote> begins a group of |
179 subpatterns, where the whole group matches if any subpattern | 179 subpatterns, where the whole group matches if any subpattern |
180 in the group matches. The <quote><literal>,</literal></quote> | 180 in the group matches. The <quote><literal>,</literal></quote> |
181 character separates subpatterns, and | 181 character separates subpatterns, and |
182 <quote><literal>}</literal></quote> ends the group.</para> | 182 <quote><literal>}</literal></quote> ends the group.</para> |
183 | 183 |
184 &interaction.filenames.glob.group; | 184 &interaction.filenames.glob.group; |
185 | 185 |
186 <sect3> | 186 <sect3> |
187 <title>Watch out!</title> | 187 <title>Watch out!</title> |
188 | 188 |
189 <para>Don't forget that if you want to match a pattern in any | 189 <para id="x_55e">Don't forget that if you want to match a pattern in any |
190 directory, you should not be using the | 190 directory, you should not be using the |
191 <quote><literal>*</literal></quote> match-any token, as this | 191 <quote><literal>*</literal></quote> match-any token, as this |
192 will only match within one directory. Instead, use the | 192 will only match within one directory. Instead, use the |
193 <quote><literal>**</literal></quote> token. This small | 193 <quote><literal>**</literal></quote> token. This small |
194 example illustrates the difference between the two.</para> | 194 example illustrates the difference between the two.</para> |
199 </sect2> | 199 </sect2> |
200 <sect2> | 200 <sect2> |
201 <title>Regular expression matching with <literal>re</literal> | 201 <title>Regular expression matching with <literal>re</literal> |
202 patterns</title> | 202 patterns</title> |
203 | 203 |
204 <para>Mercurial accepts the same regular expression syntax as | 204 <para id="x_55f">Mercurial accepts the same regular expression syntax as |
205 the Python programming language (it uses Python's regexp | 205 the Python programming language (it uses Python's regexp |
206 engine internally). This is based on the Perl language's | 206 engine internally). This is based on the Perl language's |
207 regexp syntax, which is the most popular dialect in use (it's | 207 regexp syntax, which is the most popular dialect in use (it's |
208 also used in Java, for example).</para> | 208 also used in Java, for example).</para> |
209 | 209 |
210 <para>I won't discuss Mercurial's regexp dialect in any detail | 210 <para id="x_560">I won't discuss Mercurial's regexp dialect in any detail |
211 here, as regexps are not often used. Perl-style regexps are | 211 here, as regexps are not often used. Perl-style regexps are |
212 in any case already exhaustively documented on a multitude of | 212 in any case already exhaustively documented on a multitude of |
213 web sites, and in many books. Instead, I will focus here on a | 213 web sites, and in many books. Instead, I will focus here on a |
214 few things you should know if you find yourself needing to use | 214 few things you should know if you find yourself needing to use |
215 regexps with Mercurial.</para> | 215 regexps with Mercurial.</para> |
216 | 216 |
217 <para>A regexp is matched against an entire file name, relative | 217 <para id="x_561">A regexp is matched against an entire file name, relative |
218 to the root of the repository. In other words, even if you're | 218 to the root of the repository. In other words, even if you're |
219 already in subbdirectory <filename | 219 already in subbdirectory <filename |
220 class="directory">foo</filename>, if you want to match files | 220 class="directory">foo</filename>, if you want to match files |
221 under this directory, your pattern must start with | 221 under this directory, your pattern must start with |
222 <quote><literal>foo/</literal></quote>.</para> | 222 <quote><literal>foo/</literal></quote>.</para> |
223 | 223 |
224 <para>One thing to note, if you're familiar with Perl-style | 224 <para id="x_562">One thing to note, if you're familiar with Perl-style |
225 regexps, is that Mercurial's are <emphasis>rooted</emphasis>. | 225 regexps, is that Mercurial's are <emphasis>rooted</emphasis>. |
226 That is, a regexp starts matching against the beginning of a | 226 That is, a regexp starts matching against the beginning of a |
227 string; it doesn't look for a match anywhere within the | 227 string; it doesn't look for a match anywhere within the |
228 string. To match anywhere in a string, start your pattern | 228 string. To match anywhere in a string, start your pattern |
229 with <quote><literal>.*</literal></quote>.</para> | 229 with <quote><literal>.*</literal></quote>.</para> |
231 </sect2> | 231 </sect2> |
232 </sect1> | 232 </sect1> |
233 <sect1> | 233 <sect1> |
234 <title>Filtering files</title> | 234 <title>Filtering files</title> |
235 | 235 |
236 <para>Not only does Mercurial give you a variety of ways to | 236 <para id="x_563">Not only does Mercurial give you a variety of ways to |
237 specify files; it lets you further winnow those files using | 237 specify files; it lets you further winnow those files using |
238 <emphasis>filters</emphasis>. Commands that work with file | 238 <emphasis>filters</emphasis>. Commands that work with file |
239 names accept two filtering options.</para> | 239 names accept two filtering options.</para> |
240 <itemizedlist> | 240 <itemizedlist> |
241 <listitem><para><option role="hg-opt-global">-I</option>, or | 241 <listitem><para id="x_564"><option role="hg-opt-global">-I</option>, or |
242 <option role="hg-opt-global">--include</option>, lets you | 242 <option role="hg-opt-global">--include</option>, lets you |
243 specify a pattern that file names must match in order to be | 243 specify a pattern that file names must match in order to be |
244 processed.</para> | 244 processed.</para> |
245 </listitem> | 245 </listitem> |
246 <listitem><para><option role="hg-opt-global">-X</option>, or | 246 <listitem><para id="x_565"><option role="hg-opt-global">-X</option>, or |
247 <option role="hg-opt-global">--exclude</option>, gives you a | 247 <option role="hg-opt-global">--exclude</option>, gives you a |
248 way to <emphasis>avoid</emphasis> processing files, if they | 248 way to <emphasis>avoid</emphasis> processing files, if they |
249 match this pattern.</para> | 249 match this pattern.</para> |
250 </listitem></itemizedlist> | 250 </listitem></itemizedlist> |
251 <para>You can provide multiple <option | 251 <para id="x_566">You can provide multiple <option |
252 role="hg-opt-global">-I</option> and <option | 252 role="hg-opt-global">-I</option> and <option |
253 role="hg-opt-global">-X</option> options on the command line, | 253 role="hg-opt-global">-X</option> options on the command line, |
254 and intermix them as you please. Mercurial interprets the | 254 and intermix them as you please. Mercurial interprets the |
255 patterns you provide using glob syntax by default (but you can | 255 patterns you provide using glob syntax by default (but you can |
256 use regexps if you need to).</para> | 256 use regexps if you need to).</para> |
257 | 257 |
258 <para>You can read a <option role="hg-opt-global">-I</option> | 258 <para id="x_567">You can read a <option role="hg-opt-global">-I</option> |
259 filter as <quote>process only the files that match this | 259 filter as <quote>process only the files that match this |
260 filter</quote>.</para> | 260 filter</quote>.</para> |
261 | 261 |
262 &interaction.filenames.filter.include; | 262 &interaction.filenames.filter.include; |
263 | 263 |
264 <para>The <option role="hg-opt-global">-X</option> filter is best | 264 <para id="x_568">The <option role="hg-opt-global">-X</option> filter is best |
265 read as <quote>process only the files that don't match this | 265 read as <quote>process only the files that don't match this |
266 pattern</quote>.</para> | 266 pattern</quote>.</para> |
267 | 267 |
268 &interaction.filenames.filter.exclude; | 268 &interaction.filenames.filter.exclude; |
269 | 269 |
270 </sect1> | 270 </sect1> |
271 <sect1> | 271 <sect1> |
272 <title>Ignoring unwanted files and directories</title> | 272 <title>Ignoring unwanted files and directories</title> |
273 | 273 |
274 <para>XXX.</para> | 274 <para id="x_569">XXX.</para> |
275 | 275 |
276 </sect1> | 276 </sect1> |
277 <sect1 id="sec:names:case"> | 277 <sect1 id="sec:names:case"> |
278 <title>Case sensitivity</title> | 278 <title>Case sensitivity</title> |
279 | 279 |
280 <para>If you're working in a mixed development environment that | 280 <para id="x_56a">If you're working in a mixed development environment that |
281 contains both Linux (or other Unix) systems and Macs or Windows | 281 contains both Linux (or other Unix) systems and Macs or Windows |
282 systems, you should keep in the back of your mind the knowledge | 282 systems, you should keep in the back of your mind the knowledge |
283 that they treat the case (<quote>N</quote> versus | 283 that they treat the case (<quote>N</quote> versus |
284 <quote>n</quote>) of file names in incompatible ways. This is | 284 <quote>n</quote>) of file names in incompatible ways. This is |
285 not very likely to affect you, and it's easy to deal with if it | 285 not very likely to affect you, and it's easy to deal with if it |
286 does, but it could surprise you if you don't know about | 286 does, but it could surprise you if you don't know about |
287 it.</para> | 287 it.</para> |
288 | 288 |
289 <para>Operating systems and filesystems differ in the way they | 289 <para id="x_56b">Operating systems and filesystems differ in the way they |
290 handle the <emphasis>case</emphasis> of characters in file and | 290 handle the <emphasis>case</emphasis> of characters in file and |
291 directory names. There are three common ways to handle case in | 291 directory names. There are three common ways to handle case in |
292 names.</para> | 292 names.</para> |
293 <itemizedlist> | 293 <itemizedlist> |
294 <listitem><para>Completely case insensitive. Uppercase and | 294 <listitem><para id="x_56c">Completely case insensitive. Uppercase and |
295 lowercase versions of a letter are treated as identical, | 295 lowercase versions of a letter are treated as identical, |
296 both when creating a file and during subsequent accesses. | 296 both when creating a file and during subsequent accesses. |
297 This is common on older DOS-based systems.</para> | 297 This is common on older DOS-based systems.</para> |
298 </listitem> | 298 </listitem> |
299 <listitem><para>Case preserving, but insensitive. When a file | 299 <listitem><para id="x_56d">Case preserving, but insensitive. When a file |
300 or directory is created, the case of its name is stored, and | 300 or directory is created, the case of its name is stored, and |
301 can be retrieved and displayed by the operating system. | 301 can be retrieved and displayed by the operating system. |
302 When an existing file is being looked up, its case is | 302 When an existing file is being looked up, its case is |
303 ignored. This is the standard arrangement on Windows and | 303 ignored. This is the standard arrangement on Windows and |
304 MacOS. The names <filename>foo</filename> and | 304 MacOS. The names <filename>foo</filename> and |
305 <filename>FoO</filename> identify the same file. This | 305 <filename>FoO</filename> identify the same file. This |
306 treatment of uppercase and lowercase letters as | 306 treatment of uppercase and lowercase letters as |
307 interchangeable is also referred to as <emphasis>case | 307 interchangeable is also referred to as <emphasis>case |
308 folding</emphasis>.</para> | 308 folding</emphasis>.</para> |
309 </listitem> | 309 </listitem> |
310 <listitem><para>Case sensitive. The case of a name is | 310 <listitem><para id="x_56e">Case sensitive. The case of a name is |
311 significant at all times. The names <filename>foo</filename> | 311 significant at all times. The names <filename>foo</filename> |
312 and {FoO} identify different files. This is the way Linux | 312 and {FoO} identify different files. This is the way Linux |
313 and Unix systems normally work.</para> | 313 and Unix systems normally work.</para> |
314 </listitem></itemizedlist> | 314 </listitem></itemizedlist> |
315 | 315 |
316 <para>On Unix-like systems, it is possible to have any or all of | 316 <para id="x_56f">On Unix-like systems, it is possible to have any or all of |
317 the above ways of handling case in action at once. For example, | 317 the above ways of handling case in action at once. For example, |
318 if you use a USB thumb drive formatted with a FAT32 filesystem | 318 if you use a USB thumb drive formatted with a FAT32 filesystem |
319 on a Linux system, Linux will handle names on that filesystem in | 319 on a Linux system, Linux will handle names on that filesystem in |
320 a case preserving, but insensitive, way.</para> | 320 a case preserving, but insensitive, way.</para> |
321 | 321 |
322 <sect2> | 322 <sect2> |
323 <title>Safe, portable repository storage</title> | 323 <title>Safe, portable repository storage</title> |
324 | 324 |
325 <para>Mercurial's repository storage mechanism is <emphasis>case | 325 <para id="x_570">Mercurial's repository storage mechanism is <emphasis>case |
326 safe</emphasis>. It translates file names so that they can | 326 safe</emphasis>. It translates file names so that they can |
327 be safely stored on both case sensitive and case insensitive | 327 be safely stored on both case sensitive and case insensitive |
328 filesystems. This means that you can use normal file copying | 328 filesystems. This means that you can use normal file copying |
329 tools to transfer a Mercurial repository onto, for example, a | 329 tools to transfer a Mercurial repository onto, for example, a |
330 USB thumb drive, and safely move that drive and repository | 330 USB thumb drive, and safely move that drive and repository |
333 | 333 |
334 </sect2> | 334 </sect2> |
335 <sect2> | 335 <sect2> |
336 <title>Detecting case conflicts</title> | 336 <title>Detecting case conflicts</title> |
337 | 337 |
338 <para>When operating in the working directory, Mercurial honours | 338 <para id="x_571">When operating in the working directory, Mercurial honours |
339 the naming policy of the filesystem where the working | 339 the naming policy of the filesystem where the working |
340 directory is located. If the filesystem is case preserving, | 340 directory is located. If the filesystem is case preserving, |
341 but insensitive, Mercurial will treat names that differ only | 341 but insensitive, Mercurial will treat names that differ only |
342 in case as the same.</para> | 342 in case as the same.</para> |
343 | 343 |
344 <para>An important aspect of this approach is that it is | 344 <para id="x_572">An important aspect of this approach is that it is |
345 possible to commit a changeset on a case sensitive (typically | 345 possible to commit a changeset on a case sensitive (typically |
346 Linux or Unix) filesystem that will cause trouble for users on | 346 Linux or Unix) filesystem that will cause trouble for users on |
347 case insensitive (usually Windows and MacOS) users. If a | 347 case insensitive (usually Windows and MacOS) users. If a |
348 Linux user commits changes to two files, one named | 348 Linux user commits changes to two files, one named |
349 <filename>myfile.c</filename> and the other named | 349 <filename>myfile.c</filename> and the other named |
350 <filename>MyFile.C</filename>, they will be stored correctly | 350 <filename>MyFile.C</filename>, they will be stored correctly |
351 in the repository. And in the working directories of other | 351 in the repository. And in the working directories of other |
352 Linux users, they will be correctly represented as separate | 352 Linux users, they will be correctly represented as separate |
353 files.</para> | 353 files.</para> |
354 | 354 |
355 <para>If a Windows or Mac user pulls this change, they will not | 355 <para id="x_573">If a Windows or Mac user pulls this change, they will not |
356 initially have a problem, because Mercurial's repository | 356 initially have a problem, because Mercurial's repository |
357 storage mechanism is case safe. However, once they try to | 357 storage mechanism is case safe. However, once they try to |
358 <command role="hg-cmd">hg update</command> the working | 358 <command role="hg-cmd">hg update</command> the working |
359 directory to that changeset, or <command role="hg-cmd">hg | 359 directory to that changeset, or <command role="hg-cmd">hg |
360 merge</command> with that changeset, Mercurial will spot the | 360 merge</command> with that changeset, Mercurial will spot the |
364 | 364 |
365 </sect2> | 365 </sect2> |
366 <sect2> | 366 <sect2> |
367 <title>Fixing a case conflict</title> | 367 <title>Fixing a case conflict</title> |
368 | 368 |
369 <para>If you are using Windows or a Mac in a mixed environment | 369 <para id="x_574">If you are using Windows or a Mac in a mixed environment |
370 where some of your collaborators are using Linux or Unix, and | 370 where some of your collaborators are using Linux or Unix, and |
371 Mercurial reports a case folding conflict when you try to | 371 Mercurial reports a case folding conflict when you try to |
372 <command role="hg-cmd">hg update</command> or <command | 372 <command role="hg-cmd">hg update</command> or <command |
373 role="hg-cmd">hg merge</command>, the procedure to fix the | 373 role="hg-cmd">hg merge</command>, the procedure to fix the |
374 problem is simple.</para> | 374 problem is simple.</para> |
375 | 375 |
376 <para>Just find a nearby Linux or Unix box, clone the problem | 376 <para id="x_575">Just find a nearby Linux or Unix box, clone the problem |
377 repository onto it, and use Mercurial's <command | 377 repository onto it, and use Mercurial's <command |
378 role="hg-cmd">hg rename</command> command to change the | 378 role="hg-cmd">hg rename</command> command to change the |
379 names of any offending files or directories so that they will | 379 names of any offending files or directories so that they will |
380 no longer cause case folding conflicts. Commit this change, | 380 no longer cause case folding conflicts. Commit this change, |
381 <command role="hg-cmd">hg pull</command> or <command | 381 <command role="hg-cmd">hg pull</command> or <command |
382 role="hg-cmd">hg push</command> it across to your Windows or | 382 role="hg-cmd">hg push</command> it across to your Windows or |
383 MacOS system, and <command role="hg-cmd">hg update</command> | 383 MacOS system, and <command role="hg-cmd">hg update</command> |
384 to the revision with the non-conflicting names.</para> | 384 to the revision with the non-conflicting names.</para> |
385 | 385 |
386 <para>The changeset with case-conflicting names will remain in | 386 <para id="x_576">The changeset with case-conflicting names will remain in |
387 your project's history, and you still won't be able to | 387 your project's history, and you still won't be able to |
388 <command role="hg-cmd">hg update</command> your working | 388 <command role="hg-cmd">hg update</command> your working |
389 directory to that changeset on a Windows or MacOS system, but | 389 directory to that changeset on a Windows or MacOS system, but |
390 you can continue development unimpeded.</para> | 390 you can continue development unimpeded.</para> |
391 | 391 |
392 <note> | 392 <note> |
393 <para> Prior to version 0.9.3, Mercurial did not use a case | 393 <para id="x_577"> Prior to version 0.9.3, Mercurial did not use a case |
394 safe repository storage mechanism, and did not detect case | 394 safe repository storage mechanism, and did not detect case |
395 folding conflicts. If you are using an older version of | 395 folding conflicts. If you are using an older version of |
396 Mercurial on Windows or MacOS, I strongly recommend that you | 396 Mercurial on Windows or MacOS, I strongly recommend that you |
397 upgrade.</para> | 397 upgrade.</para> |
398 </note> | 398 </note> |