hgbook
view es/daily.tex @ 354:11d7896cd2ac
Merging changes from jerojasro
| author | Igor TAmara <igor@tamarapatino.org> |
|---|---|
| date | Wed Oct 22 01:51:33 2008 -0500 (2008-10-22) |
| parents | d8596cd12b41 |
| children | 854a70fc05c6 |
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{Cómo dejar de hacer seguimiento a un archivo}
91 Si decide que un archivo no pertenece a su repositorio, use la orden
92 \hgcmd{remove}; se borrará el archivo y le indicará a Mercurial que
93 deje de hacerle seguimiento. Los archivos eliminados se representan
94 con ``\texttt{R}'' al usar \hgcmd{status}.
95 \interaction{daily.files.remove}
97 Después de hacer \hgcmd{remove} a un archivo, Mercurial dejará de
98 hacer seguimiento al mismo, incluso si recrea el archivo con el mismo
99 nombre en su directorio de trabajo. Si decide recrear un archivo con
100 el mismo nombre y desea que Mercurial le haga seguimiento, basta con
101 hacerle \hgcmd{add}. Mercurial sabrá que el archivo recientemente
102 adicionado no está relacionado con el archivo anterior que tenía el
103 mismo nombre.
105 \subsection{Al eliminar un archivo no se afecta su historia}
107 Es preciso tener en cuenta que al eliminar un archivo se tiene
108 dos efectos solamente.
109 \begin{itemize}
110 \item Se elimina la versión actual del fichero del directorio de
111 trabajo.
112 \item Mercurial deja de hacer seguimiento a los cambios del fichero
113 desde la próxima consignación.
114 \end{itemize}
115 Al eliminar un fichero \emph{no} se altera de ninguna manera la
116 \emph{historia} del mismo.
118 Si actualiza su directorio de trabajo a un conjunto de cambios en el
119 cual esl archivo que eliminó aún era tenido en cuenta, reaparecerá en
120 el directorio de trabajo, con los contenidos que este tenía cuando se
121 consignó tal conjunto de cambios. Si usted actualiza el directorio de
122 trabajo a un conjunto de cambios posterior en el cual el archivo había
123 sido eliminado, Mercurial lo eliminará de nuevo del directorio de
124 trabajo.
126 \subsection{Archivos perdidos}
128 Mercurial considera como \emph{perdido} un archivo que usted borró,
129 pero para el que no se usó \hgcmd{remove}. Los archivos perdidos se
130 representan con ``\texttt{!}'' al visualizar \hgcmd{status}.
131 Las órdenes de Mercurial generalmente no harán nada con los archivos
132 perdidos.
133 \interaction{daily.files.missing}
135 Si su repositorio contiene un archivo que \hgcmd{status} reporta como
136 perdido, y desea que el mismo se vaya, se puede usar
137 \hgcmdargs{remove}{\hgopt{remove}{--after}} posteriormente para
138 indicarle a Mercurial que usted deseaba borrar tal archivo.
139 \interaction{daily.files.remove-after}
141 Por otro lado, si borró un fichero perdido por accidente, puede usar
142 \hgcmdargs{revert}{\emph{nombre de fichero}} para recuperar el
143 fichero. Reaparecerá sin modificaciones.
144 \interaction{daily.files.recover-missing}
146 \subsection{Nota al margen: ¿Por qué decirle explícitamente a Mercurial
147 que elimine un archivo?}
149 Es posible que se haya preguntado por qué Mercurial exige que usted le
150 indique explícitamente que está borrando un archivo. Al principio del
151 desarrollo de Mercurial, este permitía que usted borrara el archivo
152 sin más; Mercurial se daría cuanta de la ausencia del archivo
153 automáticamente después de la ejecución de \hgcmd{commit}, y dejaba de
154 hacer seguimiento al archivo. En la práctica, resultaba muy sencillo
155 borrar un archivo accidentalmente sin darse cuenta.
157 \subsection{Atajo útil---agregar y eliminar archivos en un solo paso}
159 Mercurial ofrece una orden combinada, \hgcmd{addremove}, que agrega
160 los archivos que no tienen seguimiento y marca los archivos faltantes
161 como eliminados.
162 \interaction{daily.files.addremove}
163 La orden \hgcmd{commit} su puede usar con la opción \hgopt{commit}{-A}
164 que aplica el agregar-eliminar, seguido inmediatamente de una
165 consignación.
166 \interaction{daily.files.commit-addremove}
168 \section{Copying files}
170 Mercurial provides a \hgcmd{copy} command that lets you make a new
171 copy of a file. When you copy a file using this command, Mercurial
172 makes a record of the fact that the new file is a copy of the original
173 file. It treats these copied files specially when you merge your work
174 with someone else's.
176 \subsection{The results of copying during a merge}
178 What happens during a merge is that changes ``follow'' a copy. To
179 best illustrate what this means, let's create an example. We'll start
180 with the usual tiny repository that contains a single file.
181 \interaction{daily.copy.init}
182 We need to do some work in parallel, so that we'll have something to
183 merge. So let's clone our repository.
184 \interaction{daily.copy.clone}
185 Back in our initial repository, let's use the \hgcmd{copy} command to
186 make a copy of the first file we created.
187 \interaction{daily.copy.copy}
189 If we look at the output of the \hgcmd{status} command afterwards, the
190 copied file looks just like a normal added file.
191 \interaction{daily.copy.status}
192 But if we pass the \hgopt{status}{-C} option to \hgcmd{status}, it
193 prints another line of output: this is the file that our newly-added
194 file was copied \emph{from}.
195 \interaction{daily.copy.status-copy}
197 Now, back in the repository we cloned, let's make a change in
198 parallel. We'll add a line of content to the original file that we
199 created.
200 \interaction{daily.copy.other}
201 Now we have a modified \filename{file} in this repository. When we
202 pull the changes from the first repository, and merge the two heads,
203 Mercurial will propagate the changes that we made locally to
204 \filename{file} into its copy, \filename{new-file}.
205 \interaction{daily.copy.merge}
207 \subsection{Why should changes follow copies?}
208 \label{sec:daily:why-copy}
210 This behaviour, of changes to a file propagating out to copies of the
211 file, might seem esoteric, but in most cases it's highly desirable.
213 First of all, remember that this propagation \emph{only} happens when
214 you merge. So if you \hgcmd{copy} a file, and subsequently modify the
215 original file during the normal course of your work, nothing will
216 happen.
218 The second thing to know is that modifications will only propagate
219 across a copy as long as the repository that you're pulling changes
220 from \emph{doesn't know} about the copy.
222 The reason that Mercurial does this is as follows. Let's say I make
223 an important bug fix in a source file, and commit my changes.
224 Meanwhile, you've decided to \hgcmd{copy} the file in your repository,
225 without knowing about the bug or having seen the fix, and you have
226 started hacking on your copy of the file.
228 If you pulled and merged my changes, and Mercurial \emph{didn't}
229 propagate changes across copies, your source file would now contain
230 the bug, and unless you remembered to propagate the bug fix by hand,
231 the bug would \emph{remain} in your copy of the file.
233 By automatically propagating the change that fixed the bug from the
234 original file to the copy, Mercurial prevents this class of problem.
235 To my knowledge, Mercurial is the \emph{only} revision control system
236 that propagates changes across copies like this.
238 Once your change history has a record that the copy and subsequent
239 merge occurred, there's usually no further need to propagate changes
240 from the original file to the copied file, and that's why Mercurial
241 only propagates changes across copies until this point, and no
242 further.
244 \subsection{How to make changes \emph{not} follow a copy}
246 If, for some reason, you decide that this business of automatically
247 propagating changes across copies is not for you, simply use your
248 system's normal file copy command (on Unix-like systems, that's
249 \command{cp}) to make a copy of a file, then \hgcmd{add} the new copy
250 by hand. Before you do so, though, please do reread
251 section~\ref{sec:daily:why-copy}, and make an informed decision that
252 this behaviour is not appropriate to your specific case.
254 \subsection{Behaviour of the \hgcmd{copy} command}
256 When you use the \hgcmd{copy} command, Mercurial makes a copy of each
257 source file as it currently stands in the working directory. This
258 means that if you make some modifications to a file, then \hgcmd{copy}
259 it without first having committed those changes, the new copy will
260 also contain the modifications you have made up until that point. (I
261 find this behaviour a little counterintuitive, which is why I mention
262 it here.)
264 The \hgcmd{copy} command acts similarly to the Unix \command{cp}
265 command (you can use the \hgcmd{cp} alias if you prefer). The last
266 argument is the \emph{destination}, and all prior arguments are
267 \emph{sources}. If you pass it a single file as the source, and the
268 destination does not exist, it creates a new file with that name.
269 \interaction{daily.copy.simple}
270 If the destination is a directory, Mercurial copies its sources into
271 that directory.
272 \interaction{daily.copy.dir-dest}
273 Copying a directory is recursive, and preserves the directory
274 structure of the source.
275 \interaction{daily.copy.dir-src}
276 If the source and destination are both directories, the source tree is
277 recreated in the destination directory.
278 \interaction{daily.copy.dir-src-dest}
280 As with the \hgcmd{rename} command, if you copy a file manually and
281 then want Mercurial to know that you've copied the file, simply use
282 the \hgopt{copy}{--after} option to \hgcmd{copy}.
283 \interaction{daily.copy.after}
285 \section{Renaming files}
287 It's rather more common to need to rename a file than to make a copy
288 of it. The reason I discussed the \hgcmd{copy} command before talking
289 about renaming files is that Mercurial treats a rename in essentially
290 the same way as a copy. Therefore, knowing what Mercurial does when
291 you copy a file tells you what to expect when you rename a file.
293 When you use the \hgcmd{rename} command, Mercurial makes a copy of
294 each source file, then deletes it and marks the file as removed.
295 \interaction{daily.rename.rename}
296 The \hgcmd{status} command shows the newly copied file as added, and
297 the copied-from file as removed.
298 \interaction{daily.rename.status}
299 As with the results of a \hgcmd{copy}, we must use the
300 \hgopt{status}{-C} option to \hgcmd{status} to see that the added file
301 is really being tracked by Mercurial as a copy of the original, now
302 removed, file.
303 \interaction{daily.rename.status-copy}
305 As with \hgcmd{remove} and \hgcmd{copy}, you can tell Mercurial about
306 a rename after the fact using the \hgopt{rename}{--after} option. In
307 most other respects, the behaviour of the \hgcmd{rename} command, and
308 the options it accepts, are similar to the \hgcmd{copy} command.
310 \subsection{Renaming files and merging changes}
312 Since Mercurial's rename is implemented as copy-and-remove, the same
313 propagation of changes happens when you merge after a rename as after
314 a copy.
316 If I modify a file, and you rename it to a new name, and then we merge
317 our respective changes, my modifications to the file under its
318 original name will be propagated into the file under its new name.
319 (This is something you might expect to ``simply work,'' but not all
320 revision control systems actually do this.)
322 Whereas having changes follow a copy is a feature where you can
323 perhaps nod and say ``yes, that might be useful,'' it should be clear
324 that having them follow a rename is definitely important. Without
325 this facility, it would simply be too easy for changes to become
326 orphaned when files are renamed.
328 \subsection{Divergent renames and merging}
330 The case of diverging names occurs when two developers start with a
331 file---let's call it \filename{foo}---in their respective
332 repositories.
334 \interaction{rename.divergent.clone}
335 Anne renames the file to \filename{bar}.
336 \interaction{rename.divergent.rename.anne}
337 Meanwhile, Bob renames it to \filename{quux}.
338 \interaction{rename.divergent.rename.bob}
340 I like to think of this as a conflict because each developer has
341 expressed different intentions about what the file ought to be named.
343 What do you think should happen when they merge their work?
344 Mercurial's actual behaviour is that it always preserves \emph{both}
345 names when it merges changesets that contain divergent renames.
346 \interaction{rename.divergent.merge}
348 Notice that Mercurial does warn about the divergent renames, but it
349 leaves it up to you to do something about the divergence after the merge.
351 \subsection{Convergent renames and merging}
353 Another kind of rename conflict occurs when two people choose to
354 rename different \emph{source} files to the same \emph{destination}.
355 In this case, Mercurial runs its normal merge machinery, and lets you
356 guide it to a suitable resolution.
358 \subsection{Other name-related corner cases}
360 Mercurial has a longstanding bug in which it fails to handle a merge
361 where one side has a file with a given name, while another has a
362 directory with the same name. This is documented as~\bug{29}.
363 \interaction{issue29.go}
365 \section{Recovering from mistakes}
367 Mercurial has some useful commands that will help you to recover from
368 some common mistakes.
370 The \hgcmd{revert} command lets you undo changes that you have made to
371 your working directory. For example, if you \hgcmd{add} a file by
372 accident, just run \hgcmd{revert} with the name of the file you added,
373 and while the file won't be touched in any way, it won't be tracked
374 for adding by Mercurial any longer, either. You can also use
375 \hgcmd{revert} to get rid of erroneous changes to a file.
377 It's useful to remember that the \hgcmd{revert} command is useful for
378 changes that you have not yet committed. Once you've committed a
379 change, if you decide it was a mistake, you can still do something
380 about it, though your options may be more limited.
382 For more information about the \hgcmd{revert} command, and details
383 about how to deal with changes you have already committed, see
384 chapter~\ref{chap:undo}.
386 %%% Local Variables:
387 %%% mode: latex
388 %%% TeX-master: "00book"
389 %%% End: