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