hgbook

annotate es/daily.tex @ 347:8d9bd626b4b5

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