hgbook
view es/daily.tex @ 347:8d9bd626b4b5
defined a command to insert translator's notes. Added an explanation on the
README (Leame.1st) file
README (Leame.1st) file
| author | jerojasro@localhost |
|---|---|
| date | Sun Oct 19 22:39:43 2008 -0500 (2008-10-19) |
| parents | 04c08ad7e92e |
| children | d8596cd12b41 |
line source
1 \chapter{Mercurial día a día}
2 \label{chap:daily}
4 \section{Cómo indicarle a Mercurial qué archivos seguir}
6 Mercurial no trabaja con archivos en su repositorio a menos que usted
7 explícitamente se lo indique. La orden \hgcmd{status} le mostrará
8 cuáles archivos son desconocidos para Mercurial; emplea un
9 ``\texttt{?}'' para mostrar tales archivos.
11 Para indicarle a Mercurial que tenga en cuenta un archivo, emplee la
12 orden \hgcmd{add}. Una vez que haya adicionado el archivo, la línea
13 referente al archivo al aplicar la orden \hgcmd{status} para tal
14 archivo cambia de ``\texttt{?}'' a ``\texttt{A}''.
15 \interaction{daily.files.add}
17 Después de invocar \hgcmd{commit}, los archivos que haya adicionado
18 antes de consignar no se listarán en la salida de \hgcmd{status}. La
19 razón para esto es que \hgcmd{status} solamente le muestra aquellos
20 archivos ``interesantes''---los que usted haya modificado o a aquellos
21 sobre los que usted haya indicado a Mercurial hacerles algo---de forma
22 predeterminada. Si tiene un repositorio que contiene miles de
23 archivos, inusualmente deseará saber cuáles de ellos están siendo
24 seguidos por Mercurial, pero que no han cambiado. (De todas maneras,
25 puede obtener tal información; más adelante hablaremos de ello.)
28 Cuando usted añade un archivo, Mercurial no hace nada con el inmediatamente.
29 A cambio, tomará una instantánea del estado del archivo la próxima vez
30 que usted consigne. Continuará haciendo seguimiento a los cambios que
31 haga sobre el archivo cada vez que consigne, hasta que usted lo elimine.
33 \subsection{Nombramiento explicíto e implícito de archivos}
35 Mercurial tiene un comportamiento útil en el cual si a una orden,
36 le pasa el nombre de un directorio, todas las órdenes lo tratarán como
37 ``Deseo operar en cada archivo de este directorio y sus
38 subdirectorios''.
39 \interaction{daily.files.add-dir}
40 Tenga en cuenta que en este ejemplo Mercurial imprimió los nombres de
41 los archivos que se adicionaron, mientras que no lo hizo en el ejemplo
42 anterior cuando adicionamos el archivo con nombre \filename{a}.
44 En el último caso hicimos explícito el nombre del archivo que
45 deseábamos adicionar en la línea de órdenes, y Mercurial asume en
46 tales casos que usted sabe lo que está haciendo y no imprime
47 información alguna.
49 Cuando hacemos \emph{implícitos} los nombres de los archivos dando el
50 nombre de un directorio, Mercurial efectua un paso extra al imprimir
51 el nombre de cada archivo con el que va a hacer algo. Esto para
52 aclarar lo que está sucediendo, y reducir en lo posible una sorpresa
53 silenciosa pero fatal. Este comportamiento es común a la mayoría de
54 órdenes en Mercurial.
56 \subsection{Nota al margen:Mercurial trata archivos, no directorios}
58 Mercurial no da seguimiento a la información de los directorios. En
59 lugar de eso tiene en cuenta las rutas de los archivos. Antes de
60 crear un archivo, primero crea todos los directorios que hagan falta
61 para completar la ruta del archivo. Después de borrar un archivo,
62 borra todos los directorios vacíos que estuvieran en la ruta del
63 archivo borrado. Suena como una diferencia trivial, pero tiene una
64 consecuencia práctica menor: no es posible representar un directorio
65 completamente vacío en Mercurial.
67 Los directorios vacíos son inusualmente útiles, hay soluciones
68 alternativas no intrusivas que puede emplear para obtener el efecto
69 apropiado. Los desarrolladores de Mercurial pensaron que la
70 complejidad necesaria para administrar directorios vacíos no valía la
71 pena frente al beneficio limitado que esta característica podría traer.
73 Si necesita un directorio vacío en su repositorio, hay algunas formas
74 de lograrlo. Una es crear un directorio, después hacer \hgcmd{add} a
75 un archivo ``escondido'' dentro de ese directorio. En sistemas tipo
76 Unix, cualquier archivo cuyo nombre comience con un punto
77 (``\texttt{.}'') se trata como escondido por la mayoría de
78 herramientas GUI. Esta aproximación se ilustra en la figura~\ref{ex:daily:hidden}.
80 \begin{figure}[ht]
81 \interaction{daily.files.hidden}
82 \caption{Simular un directorio vacío con un archivo escondido}
83 \label{ex:daily:hidden}
84 \end{figure}
86 Otra forma de abordar la necesidad de un archivo vacío es crear
87 simplemente uno en sus guiones de construcción antes de ser necesarios.
89 \section{How to stop tracking a file}
91 Once you decide that a file no longer belongs in your repository, use
92 the \hgcmd{remove} command; this deletes the file, and tells Mercurial
93 to stop tracking it. A removed file is represented in the output of
94 \hgcmd{status} with a ``\texttt{R}''.
95 \interaction{daily.files.remove}
97 After you \hgcmd{remove} a file, Mercurial will no longer track
98 changes to that file, even if you recreate a file with the same name
99 in your working directory. If you do recreate a file with the same
100 name and want Mercurial to track the new file, simply \hgcmd{add} it.
101 Mercurial will know that the newly added file is not related to the
102 old file of the same name.
104 \subsection{Removing a file does not affect its history}
106 It is important to understand that removing a file has only two
107 effects.
108 \begin{itemize}
109 \item It removes the current version of the file from the working
110 directory.
111 \item It stops Mercurial from tracking changes to the file, from the
112 time of the next commit.
113 \end{itemize}
114 Removing a file \emph{does not} in any way alter the \emph{history} of
115 the file.
117 If you update the working directory to a changeset in which a file
118 that you have removed was still tracked, it will reappear in the
119 working directory, with the contents it had when you committed that
120 changeset. If you then update the working directory to a later
121 changeset, in which the file had been removed, Mercurial will once
122 again remove the file from the working directory.
124 \subsection{Missing files}
126 Mercurial considers a file that you have deleted, but not used
127 \hgcmd{remove} to delete, to be \emph{missing}. A missing file is
128 represented with ``\texttt{!}'' in the output of \hgcmd{status}.
129 Mercurial commands will not generally do anything with missing files.
130 \interaction{daily.files.missing}
132 If your repository contains a file that \hgcmd{status} reports as
133 missing, and you want the file to stay gone, you can run
134 \hgcmdargs{remove}{\hgopt{remove}{--after}} at any time later on, to
135 tell Mercurial that you really did mean to remove the file.
136 \interaction{daily.files.remove-after}
138 On the other hand, if you deleted the missing file by accident, use
139 \hgcmdargs{revert}{\emph{filename}} to recover the file. It will
140 reappear, in unmodified form.
141 \interaction{daily.files.recover-missing}
143 \subsection{Aside: why tell Mercurial explicitly to
144 remove a file?}
146 You might wonder why Mercurial requires you to explicitly tell it that
147 you are deleting a file. Early during the development of Mercurial,
148 it let you delete a file however you pleased; Mercurial would notice
149 the absence of the file automatically when you next ran a
150 \hgcmd{commit}, and stop tracking the file. In practice, this made it
151 too easy to accidentally remove a file without noticing.
153 \subsection{Useful shorthand---adding and removing files
154 in one step}
156 Mercurial offers a combination command, \hgcmd{addremove}, that adds
157 untracked files and marks missing files as removed.
158 \interaction{daily.files.addremove}
159 The \hgcmd{commit} command also provides a \hgopt{commit}{-A} option
160 that performs this same add-and-remove, immediately followed by a
161 commit.
162 \interaction{daily.files.commit-addremove}
164 \section{Copying files}
166 Mercurial provides a \hgcmd{copy} command that lets you make a new
167 copy of a file. When you copy a file using this command, Mercurial
168 makes a record of the fact that the new file is a copy of the original
169 file. It treats these copied files specially when you merge your work
170 with someone else's.
172 \subsection{The results of copying during a merge}
174 What happens during a merge is that changes ``follow'' a copy. To
175 best illustrate what this means, let's create an example. We'll start
176 with the usual tiny repository that contains a single file.
177 \interaction{daily.copy.init}
178 We need to do some work in parallel, so that we'll have something to
179 merge. So let's clone our repository.
180 \interaction{daily.copy.clone}
181 Back in our initial repository, let's use the \hgcmd{copy} command to
182 make a copy of the first file we created.
183 \interaction{daily.copy.copy}
185 If we look at the output of the \hgcmd{status} command afterwards, the
186 copied file looks just like a normal added file.
187 \interaction{daily.copy.status}
188 But if we pass the \hgopt{status}{-C} option to \hgcmd{status}, it
189 prints another line of output: this is the file that our newly-added
190 file was copied \emph{from}.
191 \interaction{daily.copy.status-copy}
193 Now, back in the repository we cloned, let's make a change in
194 parallel. We'll add a line of content to the original file that we
195 created.
196 \interaction{daily.copy.other}
197 Now we have a modified \filename{file} in this repository. When we
198 pull the changes from the first repository, and merge the two heads,
199 Mercurial will propagate the changes that we made locally to
200 \filename{file} into its copy, \filename{new-file}.
201 \interaction{daily.copy.merge}
203 \subsection{Why should changes follow copies?}
204 \label{sec:daily:why-copy}
206 This behaviour, of changes to a file propagating out to copies of the
207 file, might seem esoteric, but in most cases it's highly desirable.
209 First of all, remember that this propagation \emph{only} happens when
210 you merge. So if you \hgcmd{copy} a file, and subsequently modify the
211 original file during the normal course of your work, nothing will
212 happen.
214 The second thing to know is that modifications will only propagate
215 across a copy as long as the repository that you're pulling changes
216 from \emph{doesn't know} about the copy.
218 The reason that Mercurial does this is as follows. Let's say I make
219 an important bug fix in a source file, and commit my changes.
220 Meanwhile, you've decided to \hgcmd{copy} the file in your repository,
221 without knowing about the bug or having seen the fix, and you have
222 started hacking on your copy of the file.
224 If you pulled and merged my changes, and Mercurial \emph{didn't}
225 propagate changes across copies, your source file would now contain
226 the bug, and unless you remembered to propagate the bug fix by hand,
227 the bug would \emph{remain} in your copy of the file.
229 By automatically propagating the change that fixed the bug from the
230 original file to the copy, Mercurial prevents this class of problem.
231 To my knowledge, Mercurial is the \emph{only} revision control system
232 that propagates changes across copies like this.
234 Once your change history has a record that the copy and subsequent
235 merge occurred, there's usually no further need to propagate changes
236 from the original file to the copied file, and that's why Mercurial
237 only propagates changes across copies until this point, and no
238 further.
240 \subsection{How to make changes \emph{not} follow a copy}
242 If, for some reason, you decide that this business of automatically
243 propagating changes across copies is not for you, simply use your
244 system's normal file copy command (on Unix-like systems, that's
245 \command{cp}) to make a copy of a file, then \hgcmd{add} the new copy
246 by hand. Before you do so, though, please do reread
247 section~\ref{sec:daily:why-copy}, and make an informed decision that
248 this behaviour is not appropriate to your specific case.
250 \subsection{Behaviour of the \hgcmd{copy} command}
252 When you use the \hgcmd{copy} command, Mercurial makes a copy of each
253 source file as it currently stands in the working directory. This
254 means that if you make some modifications to a file, then \hgcmd{copy}
255 it without first having committed those changes, the new copy will
256 also contain the modifications you have made up until that point. (I
257 find this behaviour a little counterintuitive, which is why I mention
258 it here.)
260 The \hgcmd{copy} command acts similarly to the Unix \command{cp}
261 command (you can use the \hgcmd{cp} alias if you prefer). The last
262 argument is the \emph{destination}, and all prior arguments are
263 \emph{sources}. If you pass it a single file as the source, and the
264 destination does not exist, it creates a new file with that name.
265 \interaction{daily.copy.simple}
266 If the destination is a directory, Mercurial copies its sources into
267 that directory.
268 \interaction{daily.copy.dir-dest}
269 Copying a directory is recursive, and preserves the directory
270 structure of the source.
271 \interaction{daily.copy.dir-src}
272 If the source and destination are both directories, the source tree is
273 recreated in the destination directory.
274 \interaction{daily.copy.dir-src-dest}
276 As with the \hgcmd{rename} command, if you copy a file manually and
277 then want Mercurial to know that you've copied the file, simply use
278 the \hgopt{copy}{--after} option to \hgcmd{copy}.
279 \interaction{daily.copy.after}
281 \section{Renaming files}
283 It's rather more common to need to rename a file than to make a copy
284 of it. The reason I discussed the \hgcmd{copy} command before talking
285 about renaming files is that Mercurial treats a rename in essentially
286 the same way as a copy. Therefore, knowing what Mercurial does when
287 you copy a file tells you what to expect when you rename a file.
289 When you use the \hgcmd{rename} command, Mercurial makes a copy of
290 each source file, then deletes it and marks the file as removed.
291 \interaction{daily.rename.rename}
292 The \hgcmd{status} command shows the newly copied file as added, and
293 the copied-from file as removed.
294 \interaction{daily.rename.status}
295 As with the results of a \hgcmd{copy}, we must use the
296 \hgopt{status}{-C} option to \hgcmd{status} to see that the added file
297 is really being tracked by Mercurial as a copy of the original, now
298 removed, file.
299 \interaction{daily.rename.status-copy}
301 As with \hgcmd{remove} and \hgcmd{copy}, you can tell Mercurial about
302 a rename after the fact using the \hgopt{rename}{--after} option. In
303 most other respects, the behaviour of the \hgcmd{rename} command, and
304 the options it accepts, are similar to the \hgcmd{copy} command.
306 \subsection{Renaming files and merging changes}
308 Since Mercurial's rename is implemented as copy-and-remove, the same
309 propagation of changes happens when you merge after a rename as after
310 a copy.
312 If I modify a file, and you rename it to a new name, and then we merge
313 our respective changes, my modifications to the file under its
314 original name will be propagated into the file under its new name.
315 (This is something you might expect to ``simply work,'' but not all
316 revision control systems actually do this.)
318 Whereas having changes follow a copy is a feature where you can
319 perhaps nod and say ``yes, that might be useful,'' it should be clear
320 that having them follow a rename is definitely important. Without
321 this facility, it would simply be too easy for changes to become
322 orphaned when files are renamed.
324 \subsection{Divergent renames and merging}
326 The case of diverging names occurs when two developers start with a
327 file---let's call it \filename{foo}---in their respective
328 repositories.
330 \interaction{rename.divergent.clone}
331 Anne renames the file to \filename{bar}.
332 \interaction{rename.divergent.rename.anne}
333 Meanwhile, Bob renames it to \filename{quux}.
334 \interaction{rename.divergent.rename.bob}
336 I like to think of this as a conflict because each developer has
337 expressed different intentions about what the file ought to be named.
339 What do you think should happen when they merge their work?
340 Mercurial's actual behaviour is that it always preserves \emph{both}
341 names when it merges changesets that contain divergent renames.
342 \interaction{rename.divergent.merge}
344 Notice that Mercurial does warn about the divergent renames, but it
345 leaves it up to you to do something about the divergence after the merge.
347 \subsection{Convergent renames and merging}
349 Another kind of rename conflict occurs when two people choose to
350 rename different \emph{source} files to the same \emph{destination}.
351 In this case, Mercurial runs its normal merge machinery, and lets you
352 guide it to a suitable resolution.
354 \subsection{Other name-related corner cases}
356 Mercurial has a longstanding bug in which it fails to handle a merge
357 where one side has a file with a given name, while another has a
358 directory with the same name. This is documented as~\bug{29}.
359 \interaction{issue29.go}
361 \section{Recovering from mistakes}
363 Mercurial has some useful commands that will help you to recover from
364 some common mistakes.
366 The \hgcmd{revert} command lets you undo changes that you have made to
367 your working directory. For example, if you \hgcmd{add} a file by
368 accident, just run \hgcmd{revert} with the name of the file you added,
369 and while the file won't be touched in any way, it won't be tracked
370 for adding by Mercurial any longer, either. You can also use
371 \hgcmd{revert} to get rid of erroneous changes to a file.
373 It's useful to remember that the \hgcmd{revert} command is useful for
374 changes that you have not yet committed. Once you've committed a
375 change, if you decide it was a mistake, you can still do something
376 about it, though your options may be more limited.
378 For more information about the \hgcmd{revert} command, and details
379 about how to deal with changes you have already committed, see
380 chapter~\ref{chap:undo}.
382 %%% Local Variables:
383 %%% mode: latex
384 %%% TeX-master: "00book"
385 %%% End: