hgbook

annotate es/undo.tex @ 384:7f1572c365d2

find changesets by author, revision, files, or words in the commit message
translated up to section 2.1.1, included
author Javier Rojas <jerojasro@devnull.li>
date Fri Oct 31 00:19:04 2008 -0500 (2008-10-31)
parents d5f1049a79dd
children d2467817c934
rev   line source
igor@374 1 \chapter{Encontrar y arreglar sus equivocaciones}
jerojasro@343 2 \label{chap:undo}
jerojasro@343 3
igor@374 4 Errar es humano, pero tratar adecuadamente las consecuencias requiere
igor@374 5 un sistema de control de revisiones de primera categoría. En este
igor@374 6 capítulo, discutiremos algunas técnicas que puede usar cuando
igor@374 7 encuentra que hay un problema enraizado en su proyecto. Mercurial
igor@374 8 tiene unas características poderosas que le ayudarán a isolar las
igor@374 9 fuentes de los problemas, y a dar cuenta de ellas apropiadamente.
igor@374 10
igor@374 11 \section{Borrar la historia local}
igor@374 12
igor@374 13 \subsection{La consignación accidental}
igor@374 14
igor@374 15 Tengo el problema ocasional, pero persistente de teclear más rápido de
igor@374 16 lo que pienso, que aveces resulta en consignar un conjunto de cambios
igor@374 17 incompleto o simplemente malo. En mi caso, el conjunto de cambios
igor@378 18 incompleto consiste en que creé un nuevo fichero fuente, pero olvidé
igor@374 19 hacerle \hgcmd{add}. Un conjunto de cambios``simplemente malo'' no es
igor@374 20 tan común, pero sí resulta muy molesto.
igor@374 21
igor@378 22 \subsection{Hacer rollback una transacción}
jerojasro@343 23 \label{sec:undo:rollback}
jerojasro@343 24
igor@374 25 En la sección~\ref{sec:concepts:txn}, mencioné que Mercurial trata
igor@374 26 modificación a un repositorio como una \emph{transacción}. Cada vez
igor@374 27 que consigna un conjunto de cambios o lo jala de otro repositorio,
igor@378 28 Mercurial recuerda lo que hizo. Puede deshacer, o hacer \emph{roll back}\ndt{El significado igual que en los
igor@378 29 ambientes de sistemas manejadores de bases de datos se refiere a
igor@378 30 la atomicidad e integridad al devolver un conjunto de acciones que
igor@378 31 permitan dejar el repositorio en un estado consistente previo},
igor@374 32 exactamente una de tales acciones usando la orden \hgcmd{rollback}.
igor@374 33 (Ver en la sección~\ref{sec:undo:rollback-after-push} una anotación
igor@374 34 importante acerca del uso de esta orden.)
igor@374 35
igor@374 36 A continuación una equivocación que me sucede frecuentemente:
igor@374 37 consignar un cambio en el cual he creado un nuevo fichero, pero he
igor@374 38 olvidado hacerle \hgcmd{add}.
jerojasro@343 39 \interaction{rollback.commit}
igor@374 40 La salida de \hgcmd{status} después de la consignación confirma
igor@374 41 inmediatamente este error.
jerojasro@343 42 \interaction{rollback.status}
igor@378 43 La consignación capturó los cambios en el fichero \filename{a}, pero
igor@374 44 no el nuevo fichero \filename{b}. Si yo publicara este conjunto de
igor@374 45 cambios a un repositorio compartido con un colega, es bastante
igor@374 46 probable que algo en \filename{a} se refiriera a \filename{b}, el cual
igor@374 47 podría no estar presente cuando jalen mis cambios del repositorio. Me
igor@374 48 convertiría el sujeto de cierta indignación.
igor@374 49
igor@374 50 Como sea, la suerte me acompaña---Encontré mi error antes de publicar
igor@374 51 el conjunto de cambios. Uso la orden \hgcmd{rollback}, y Mercurial
igor@374 52 hace desaparecer el último conjunto de cambios.
jerojasro@343 53 \interaction{rollback.rollback}
igor@374 54 El conjunto de cambios ya no está en la historia del repositorio, y el
igor@374 55 directorio de trabajo cree que el fichero \filename{a} ha sido
igor@377 56 modificado. La consignación y el roll back dejaron el directorio de
igor@377 57 trabajo exactamente como estaba antes de la consignación; el conjunto
igor@374 58 de cambios ha sido eliminado totlamente. Ahora puedo hacer \hgcmd{add}
igor@374 59 al fichero \filename{b}, y hacer de nuevo la consignación.
jerojasro@343 60 \interaction{rollback.add}
jerojasro@343 61
igor@374 62 \subsection{Erroneamente jalado}
igor@374 63
igor@374 64 Mantener ramas de desarrollo separadas de un proyecto en distintos
igor@374 65 repositorios es una práctica común con Mercurial. Su equipo de
igor@374 66 desarrollo puede tener un repositorio compartido para la versión ``0.9''
igor@374 67 y otra con cambios distintos para la versión ``1.0''.
igor@374 68
igor@374 69 Con este escenario, puede imaginar las consecuencias si tuviera un
igor@374 70 repositorio local ``0.9'', y jalara accidentalmente los cambios del
igor@374 71 repositorio compartido de la versión ``1.0'' en este. En el peor de
igor@374 72 los casos, por falta de atención, es posible que publique tales
igor@374 73 cambios en el árbol compartido ``0.9'', confundiendo a todo su equipo
igor@374 74 de trabajo(pero no se preocupe, volveremos a este terrorífico
igor@374 75 escenario posteriormente). En todo caso, es muy probable que usted se
igor@374 76 de cuenta inmediatamente, dado que Mercurial mostrará el URL de donde
igor@374 77 está jalando, o que vea jalando una sospechosa gran cantidad de
igor@374 78 cambios en el repositorio.
igor@374 79
igor@377 80 La orden \hgcmd{rollback} excluirá eficientemente los conjuntos de
igor@377 81 cambios que haya acabado de jalar. Mercurial agrupa todos los cambios
igor@377 82 de un \hgcmd{pull} a una única transacción y bastará con un
igor@377 83 \hgcmd{rollback} para deshacer esta equivocación.
igor@377 84
igor@377 85 \subsection{Después de publicar, un roll back es futil}
jerojasro@343 86 \label{sec:undo:rollback-after-push}
jerojasro@343 87
igor@377 88 El valor de \hgcmd{rollback} se anula cuando ha publicado sus cambios
igor@377 89 a otro repositorio. Un cambio desaparece totalmente al hacer roll back,
igor@377 90 pero \emph{solamente} en el repositorio en el cual aplica
igor@377 91 \hgcmd{rollback}. Debido a que un roll back elimina la historia,
igor@377 92 no hay forma de que la desaparición de un cambio se propague entre
igor@377 93 repositorios.
igor@377 94
igor@377 95 Si ha publicado un cambio en otro repositorio---particularmente si es
igor@377 96 un repositorio público---esencialmente está ``en terreno agreste,''
igor@377 97 y tendrá que reparar la equivocación de un modo distinto. Lo que
igor@377 98 pasará si publica un conjunto de cambios en algún sitio, hacer
igor@377 99 rollback y después volver a jalar del repositorio del cual había
igor@377 100 publicado, es que el conjunto de cambios reaparecerá en su repositorio.
igor@377 101
igor@377 102 (Si está absolutamente segruro de que el conjunto de cambios al que
igor@377 103 desea hacer rollback es el cambio más reciente del repositorio en el
igor@377 104 cual publicó, \emph{y} sabe que nadie más pudo haber jalado de tal
igor@377 105 repositorio, puede hacer rollback del conjunto de cambios allí, pero
igor@377 106 es mejor no confiar en una solución de este estilo. Si lo hace, tarde
igor@377 107 o temprano un conjunto de cambios logrará colarse en un repositorio
igor@377 108 que usted no controle directamente(o del cual se ha olvidado), y
igor@377 109 volverá a hostigarle.)
igor@377 110
igor@377 111 \subsection{Solamente hay un roll back}
igor@377 112
igor@377 113 Mercurial almacena exactamente una transacción en su bitácora de
igor@377 114 transacciones; tal transacción es la más reciente de las que haya
igor@377 115 ocurrido en el repositorio. Esto significa que solamente puede hacer
igor@377 116 roll back a una transacción. Si espera poder hacer roll back a una
igor@377 117 transacción después al antecesor, observará que no es el
igor@377 118 comportamiento que obtendrá.
jerojasro@343 119 \interaction{rollback.twice}
igor@377 120 Una vez que haya aplicado un rollback en una transacción a un
igor@377 121 repositorio, no podrá volver a hacer rollback hasta que haga una
igor@377 122 consignación o haya jalado.
jerojasro@343 123
jerojasro@343 124 \section{Reverting the mistaken change}
jerojasro@343 125
jerojasro@343 126 If you make a modification to a file, and decide that you really
jerojasro@343 127 didn't want to change the file at all, and you haven't yet committed
jerojasro@343 128 your changes, the \hgcmd{revert} command is the one you'll need. It
jerojasro@343 129 looks at the changeset that's the parent of the working directory, and
jerojasro@343 130 restores the contents of the file to their state as of that changeset.
jerojasro@343 131 (That's a long-winded way of saying that, in the normal case, it
jerojasro@343 132 undoes your modifications.)
jerojasro@343 133
jerojasro@343 134 Let's illustrate how the \hgcmd{revert} command works with yet another
jerojasro@343 135 small example. We'll begin by modifying a file that Mercurial is
jerojasro@343 136 already tracking.
jerojasro@343 137 \interaction{daily.revert.modify}
jerojasro@343 138 If we don't want that change, we can simply \hgcmd{revert} the file.
jerojasro@343 139 \interaction{daily.revert.unmodify}
jerojasro@343 140 The \hgcmd{revert} command provides us with an extra degree of safety
jerojasro@343 141 by saving our modified file with a \filename{.orig} extension.
jerojasro@343 142 \interaction{daily.revert.status}
jerojasro@343 143
jerojasro@343 144 Here is a summary of the cases that the \hgcmd{revert} command can
jerojasro@343 145 deal with. We will describe each of these in more detail in the
jerojasro@343 146 section that follows.
jerojasro@343 147 \begin{itemize}
jerojasro@343 148 \item If you modify a file, it will restore the file to its unmodified
jerojasro@343 149 state.
jerojasro@343 150 \item If you \hgcmd{add} a file, it will undo the ``added'' state of
jerojasro@343 151 the file, but leave the file itself untouched.
jerojasro@343 152 \item If you delete a file without telling Mercurial, it will restore
jerojasro@343 153 the file to its unmodified contents.
jerojasro@343 154 \item If you use the \hgcmd{remove} command to remove a file, it will
jerojasro@343 155 undo the ``removed'' state of the file, and restore the file to its
jerojasro@343 156 unmodified contents.
jerojasro@343 157 \end{itemize}
jerojasro@343 158
jerojasro@343 159 \subsection{File management errors}
jerojasro@343 160 \label{sec:undo:mgmt}
jerojasro@343 161
jerojasro@343 162 The \hgcmd{revert} command is useful for more than just modified
jerojasro@343 163 files. It lets you reverse the results of all of Mercurial's file
jerojasro@343 164 management commands---\hgcmd{add}, \hgcmd{remove}, and so on.
jerojasro@343 165
jerojasro@343 166 If you \hgcmd{add} a file, then decide that in fact you don't want
jerojasro@343 167 Mercurial to track it, use \hgcmd{revert} to undo the add. Don't
jerojasro@343 168 worry; Mercurial will not modify the file in any way. It will just
jerojasro@343 169 ``unmark'' the file.
jerojasro@343 170 \interaction{daily.revert.add}
jerojasro@343 171
jerojasro@343 172 Similarly, if you ask Mercurial to \hgcmd{remove} a file, you can use
jerojasro@343 173 \hgcmd{revert} to restore it to the contents it had as of the parent
jerojasro@343 174 of the working directory.
jerojasro@343 175 \interaction{daily.revert.remove}
jerojasro@343 176 This works just as well for a file that you deleted by hand, without
jerojasro@343 177 telling Mercurial (recall that in Mercurial terminology, this kind of
jerojasro@343 178 file is called ``missing'').
jerojasro@343 179 \interaction{daily.revert.missing}
jerojasro@343 180
jerojasro@343 181 If you revert a \hgcmd{copy}, the copied-to file remains in your
jerojasro@343 182 working directory afterwards, untracked. Since a copy doesn't affect
jerojasro@343 183 the copied-from file in any way, Mercurial doesn't do anything with
jerojasro@343 184 the copied-from file.
jerojasro@343 185 \interaction{daily.revert.copy}
jerojasro@343 186
jerojasro@343 187 \subsubsection{A slightly special case: reverting a rename}
jerojasro@343 188
jerojasro@343 189 If you \hgcmd{rename} a file, there is one small detail that
jerojasro@343 190 you should remember. When you \hgcmd{revert} a rename, it's not
jerojasro@343 191 enough to provide the name of the renamed-to file, as you can see
jerojasro@343 192 here.
jerojasro@343 193 \interaction{daily.revert.rename}
jerojasro@343 194 As you can see from the output of \hgcmd{status}, the renamed-to file
jerojasro@343 195 is no longer identified as added, but the renamed-\emph{from} file is
jerojasro@343 196 still removed! This is counter-intuitive (at least to me), but at
jerojasro@343 197 least it's easy to deal with.
jerojasro@343 198 \interaction{daily.revert.rename-orig}
jerojasro@343 199 So remember, to revert a \hgcmd{rename}, you must provide \emph{both}
jerojasro@343 200 the source and destination names.
jerojasro@343 201
jerojasro@343 202 % TODO: the output doesn't look like it will be removed!
jerojasro@343 203
jerojasro@343 204 (By the way, if you rename a file, then modify the renamed-to file,
jerojasro@343 205 then revert both components of the rename, when Mercurial restores the
jerojasro@343 206 file that was removed as part of the rename, it will be unmodified.
jerojasro@343 207 If you need the modifications in the renamed-to file to show up in the
jerojasro@343 208 renamed-from file, don't forget to copy them over.)
jerojasro@343 209
jerojasro@343 210 These fiddly aspects of reverting a rename arguably constitute a small
jerojasro@343 211 bug in Mercurial.
jerojasro@343 212
jerojasro@343 213 \section{Dealing with committed changes}
jerojasro@343 214
jerojasro@343 215 Consider a case where you have committed a change $a$, and another
jerojasro@343 216 change $b$ on top of it; you then realise that change $a$ was
jerojasro@343 217 incorrect. Mercurial lets you ``back out'' an entire changeset
jerojasro@343 218 automatically, and building blocks that let you reverse part of a
jerojasro@343 219 changeset by hand.
jerojasro@343 220
jerojasro@343 221 Before you read this section, here's something to keep in mind: the
jerojasro@343 222 \hgcmd{backout} command undoes changes by \emph{adding} history, not
jerojasro@343 223 by modifying or erasing it. It's the right tool to use if you're
jerojasro@343 224 fixing bugs, but not if you're trying to undo some change that has
jerojasro@343 225 catastrophic consequences. To deal with those, see
jerojasro@343 226 section~\ref{sec:undo:aaaiiieee}.
jerojasro@343 227
jerojasro@343 228 \subsection{Backing out a changeset}
jerojasro@343 229
jerojasro@343 230 The \hgcmd{backout} command lets you ``undo'' the effects of an entire
jerojasro@343 231 changeset in an automated fashion. Because Mercurial's history is
jerojasro@343 232 immutable, this command \emph{does not} get rid of the changeset you
jerojasro@343 233 want to undo. Instead, it creates a new changeset that
jerojasro@343 234 \emph{reverses} the effect of the to-be-undone changeset.
jerojasro@343 235
jerojasro@343 236 The operation of the \hgcmd{backout} command is a little intricate, so
jerojasro@343 237 let's illustrate it with some examples. First, we'll create a
jerojasro@343 238 repository with some simple changes.
jerojasro@343 239 \interaction{backout.init}
jerojasro@343 240
jerojasro@343 241 The \hgcmd{backout} command takes a single changeset ID as its
jerojasro@343 242 argument; this is the changeset to back out. Normally,
jerojasro@343 243 \hgcmd{backout} will drop you into a text editor to write a commit
jerojasro@343 244 message, so you can record why you're backing the change out. In this
jerojasro@343 245 example, we provide a commit message on the command line using the
jerojasro@343 246 \hgopt{backout}{-m} option.
jerojasro@343 247
jerojasro@343 248 \subsection{Backing out the tip changeset}
jerojasro@343 249
jerojasro@343 250 We're going to start by backing out the last changeset we committed.
jerojasro@343 251 \interaction{backout.simple}
jerojasro@343 252 You can see that the second line from \filename{myfile} is no longer
jerojasro@343 253 present. Taking a look at the output of \hgcmd{log} gives us an idea
jerojasro@343 254 of what the \hgcmd{backout} command has done.
jerojasro@343 255 \interaction{backout.simple.log}
jerojasro@343 256 Notice that the new changeset that \hgcmd{backout} has created is a
jerojasro@343 257 child of the changeset we backed out. It's easier to see this in
jerojasro@343 258 figure~\ref{fig:undo:backout}, which presents a graphical view of the
jerojasro@343 259 change history. As you can see, the history is nice and linear.
jerojasro@343 260
jerojasro@343 261 \begin{figure}[htb]
jerojasro@343 262 \centering
jerojasro@343 263 \grafix{undo-simple}
jerojasro@343 264 \caption{Backing out a change using the \hgcmd{backout} command}
jerojasro@343 265 \label{fig:undo:backout}
jerojasro@343 266 \end{figure}
jerojasro@343 267
jerojasro@343 268 \subsection{Backing out a non-tip change}
jerojasro@343 269
jerojasro@343 270 If you want to back out a change other than the last one you
jerojasro@343 271 committed, pass the \hgopt{backout}{--merge} option to the
jerojasro@343 272 \hgcmd{backout} command.
jerojasro@343 273 \interaction{backout.non-tip.clone}
jerojasro@343 274 This makes backing out any changeset a ``one-shot'' operation that's
jerojasro@343 275 usually simple and fast.
jerojasro@343 276 \interaction{backout.non-tip.backout}
jerojasro@343 277
jerojasro@343 278 If you take a look at the contents of \filename{myfile} after the
jerojasro@343 279 backout finishes, you'll see that the first and third changes are
jerojasro@343 280 present, but not the second.
jerojasro@343 281 \interaction{backout.non-tip.cat}
jerojasro@343 282
jerojasro@343 283 As the graphical history in figure~\ref{fig:undo:backout-non-tip}
jerojasro@343 284 illustrates, Mercurial actually commits \emph{two} changes in this
jerojasro@343 285 kind of situation (the box-shaped nodes are the ones that Mercurial
jerojasro@343 286 commits automatically). Before Mercurial begins the backout process,
jerojasro@343 287 it first remembers what the current parent of the working directory
jerojasro@343 288 is. It then backs out the target changeset, and commits that as a
jerojasro@343 289 changeset. Finally, it merges back to the previous parent of the
jerojasro@343 290 working directory, and commits the result of the merge.
jerojasro@343 291
jerojasro@343 292 % TODO: to me it looks like mercurial doesn't commit the second merge automatically!
jerojasro@343 293
jerojasro@343 294 \begin{figure}[htb]
jerojasro@343 295 \centering
jerojasro@343 296 \grafix{undo-non-tip}
jerojasro@343 297 \caption{Automated backout of a non-tip change using the \hgcmd{backout} command}
jerojasro@343 298 \label{fig:undo:backout-non-tip}
jerojasro@343 299 \end{figure}
jerojasro@343 300
jerojasro@343 301 The result is that you end up ``back where you were'', only with some
jerojasro@343 302 extra history that undoes the effect of the changeset you wanted to
jerojasro@343 303 back out.
jerojasro@343 304
jerojasro@343 305 \subsubsection{Always use the \hgopt{backout}{--merge} option}
jerojasro@343 306
jerojasro@343 307 In fact, since the \hgopt{backout}{--merge} option will do the ``right
jerojasro@343 308 thing'' whether or not the changeset you're backing out is the tip
jerojasro@343 309 (i.e.~it won't try to merge if it's backing out the tip, since there's
jerojasro@343 310 no need), you should \emph{always} use this option when you run the
jerojasro@343 311 \hgcmd{backout} command.
jerojasro@343 312
jerojasro@343 313 \subsection{Gaining more control of the backout process}
jerojasro@343 314
jerojasro@343 315 While I've recommended that you always use the
jerojasro@343 316 \hgopt{backout}{--merge} option when backing out a change, the
jerojasro@343 317 \hgcmd{backout} command lets you decide how to merge a backout
jerojasro@343 318 changeset. Taking control of the backout process by hand is something
jerojasro@343 319 you will rarely need to do, but it can be useful to understand what
jerojasro@343 320 the \hgcmd{backout} command is doing for you automatically. To
jerojasro@343 321 illustrate this, let's clone our first repository, but omit the
jerojasro@343 322 backout change that it contains.
jerojasro@343 323
jerojasro@343 324 \interaction{backout.manual.clone}
jerojasro@343 325 As with our earlier example, We'll commit a third changeset, then back
jerojasro@343 326 out its parent, and see what happens.
jerojasro@343 327 \interaction{backout.manual.backout}
jerojasro@343 328 Our new changeset is again a descendant of the changeset we backout
jerojasro@343 329 out; it's thus a new head, \emph{not} a descendant of the changeset
jerojasro@343 330 that was the tip. The \hgcmd{backout} command was quite explicit in
jerojasro@343 331 telling us this.
jerojasro@343 332 \interaction{backout.manual.log}
jerojasro@343 333
jerojasro@343 334 Again, it's easier to see what has happened by looking at a graph of
jerojasro@343 335 the revision history, in figure~\ref{fig:undo:backout-manual}. This
jerojasro@343 336 makes it clear that when we use \hgcmd{backout} to back out a change
jerojasro@343 337 other than the tip, Mercurial adds a new head to the repository (the
jerojasro@343 338 change it committed is box-shaped).
jerojasro@343 339
jerojasro@343 340 \begin{figure}[htb]
jerojasro@343 341 \centering
jerojasro@343 342 \grafix{undo-manual}
jerojasro@343 343 \caption{Backing out a change using the \hgcmd{backout} command}
jerojasro@343 344 \label{fig:undo:backout-manual}
jerojasro@343 345 \end{figure}
jerojasro@343 346
jerojasro@343 347 After the \hgcmd{backout} command has completed, it leaves the new
jerojasro@343 348 ``backout'' changeset as the parent of the working directory.
jerojasro@343 349 \interaction{backout.manual.parents}
jerojasro@343 350 Now we have two isolated sets of changes.
jerojasro@343 351 \interaction{backout.manual.heads}
jerojasro@343 352
jerojasro@343 353 Let's think about what we expect to see as the contents of
jerojasro@343 354 \filename{myfile} now. The first change should be present, because
jerojasro@343 355 we've never backed it out. The second change should be missing, as
jerojasro@343 356 that's the change we backed out. Since the history graph shows the
jerojasro@343 357 third change as a separate head, we \emph{don't} expect to see the
jerojasro@343 358 third change present in \filename{myfile}.
jerojasro@343 359 \interaction{backout.manual.cat}
jerojasro@343 360 To get the third change back into the file, we just do a normal merge
jerojasro@343 361 of our two heads.
jerojasro@343 362 \interaction{backout.manual.merge}
jerojasro@343 363 Afterwards, the graphical history of our repository looks like
jerojasro@343 364 figure~\ref{fig:undo:backout-manual-merge}.
jerojasro@343 365
jerojasro@343 366 \begin{figure}[htb]
jerojasro@343 367 \centering
jerojasro@343 368 \grafix{undo-manual-merge}
jerojasro@343 369 \caption{Manually merging a backout change}
jerojasro@343 370 \label{fig:undo:backout-manual-merge}
jerojasro@343 371 \end{figure}
jerojasro@343 372
jerojasro@343 373 \subsection{Why \hgcmd{backout} works as it does}
jerojasro@343 374
jerojasro@343 375 Here's a brief description of how the \hgcmd{backout} command works.
jerojasro@343 376 \begin{enumerate}
jerojasro@343 377 \item It ensures that the working directory is ``clean'', i.e.~that
jerojasro@343 378 the output of \hgcmd{status} would be empty.
jerojasro@343 379 \item It remembers the current parent of the working directory. Let's
jerojasro@343 380 call this changeset \texttt{orig}
jerojasro@343 381 \item It does the equivalent of a \hgcmd{update} to sync the working
jerojasro@343 382 directory to the changeset you want to back out. Let's call this
jerojasro@343 383 changeset \texttt{backout}
jerojasro@343 384 \item It finds the parent of that changeset. Let's call that
jerojasro@343 385 changeset \texttt{parent}.
jerojasro@343 386 \item For each file that the \texttt{backout} changeset affected, it
jerojasro@343 387 does the equivalent of a \hgcmdargs{revert}{-r parent} on that file,
jerojasro@343 388 to restore it to the contents it had before that changeset was
jerojasro@343 389 committed.
jerojasro@343 390 \item It commits the result as a new changeset. This changeset has
jerojasro@343 391 \texttt{backout} as its parent.
jerojasro@343 392 \item If you specify \hgopt{backout}{--merge} on the command line, it
jerojasro@343 393 merges with \texttt{orig}, and commits the result of the merge.
jerojasro@343 394 \end{enumerate}
jerojasro@343 395
jerojasro@343 396 An alternative way to implement the \hgcmd{backout} command would be
jerojasro@343 397 to \hgcmd{export} the to-be-backed-out changeset as a diff, then use
jerojasro@343 398 the \cmdopt{patch}{--reverse} option to the \command{patch} command to
jerojasro@343 399 reverse the effect of the change without fiddling with the working
jerojasro@343 400 directory. This sounds much simpler, but it would not work nearly as
jerojasro@343 401 well.
jerojasro@343 402
jerojasro@343 403 The reason that \hgcmd{backout} does an update, a commit, a merge, and
jerojasro@343 404 another commit is to give the merge machinery the best chance to do a
jerojasro@343 405 good job when dealing with all the changes \emph{between} the change
jerojasro@343 406 you're backing out and the current tip.
jerojasro@343 407
jerojasro@343 408 If you're backing out a changeset that's~100 revisions back in your
jerojasro@343 409 project's history, the chances that the \command{patch} command will
jerojasro@343 410 be able to apply a reverse diff cleanly are not good, because
jerojasro@343 411 intervening changes are likely to have ``broken the context'' that
jerojasro@343 412 \command{patch} uses to determine whether it can apply a patch (if
jerojasro@343 413 this sounds like gibberish, see \ref{sec:mq:patch} for a
jerojasro@343 414 discussion of the \command{patch} command). Also, Mercurial's merge
jerojasro@343 415 machinery will handle files and directories being renamed, permission
jerojasro@343 416 changes, and modifications to binary files, none of which
jerojasro@343 417 \command{patch} can deal with.
jerojasro@343 418
jerojasro@343 419 \section{Changes that should never have been}
jerojasro@343 420 \label{sec:undo:aaaiiieee}
jerojasro@343 421
jerojasro@343 422 Most of the time, the \hgcmd{backout} command is exactly what you need
jerojasro@343 423 if you want to undo the effects of a change. It leaves a permanent
jerojasro@343 424 record of exactly what you did, both when committing the original
jerojasro@343 425 changeset and when you cleaned up after it.
jerojasro@343 426
jerojasro@343 427 On rare occasions, though, you may find that you've committed a change
jerojasro@343 428 that really should not be present in the repository at all. For
jerojasro@343 429 example, it would be very unusual, and usually considered a mistake,
jerojasro@343 430 to commit a software project's object files as well as its source
jerojasro@343 431 files. Object files have almost no intrinsic value, and they're
jerojasro@343 432 \emph{big}, so they increase the size of the repository and the amount
jerojasro@343 433 of time it takes to clone or pull changes.
jerojasro@343 434
jerojasro@343 435 Before I discuss the options that you have if you commit a ``brown
jerojasro@343 436 paper bag'' change (the kind that's so bad that you want to pull a
jerojasro@343 437 brown paper bag over your head), let me first discuss some approaches
jerojasro@343 438 that probably won't work.
jerojasro@343 439
jerojasro@343 440 Since Mercurial treats history as accumulative---every change builds
jerojasro@343 441 on top of all changes that preceded it---you generally can't just make
jerojasro@343 442 disastrous changes disappear. The one exception is when you've just
jerojasro@343 443 committed a change, and it hasn't been pushed or pulled into another
jerojasro@343 444 repository. That's when you can safely use the \hgcmd{rollback}
jerojasro@343 445 command, as I detailed in section~\ref{sec:undo:rollback}.
jerojasro@343 446
jerojasro@343 447 After you've pushed a bad change to another repository, you
jerojasro@343 448 \emph{could} still use \hgcmd{rollback} to make your local copy of the
jerojasro@343 449 change disappear, but it won't have the consequences you want. The
jerojasro@343 450 change will still be present in the remote repository, so it will
jerojasro@343 451 reappear in your local repository the next time you pull.
jerojasro@343 452
jerojasro@343 453 If a situation like this arises, and you know which repositories your
jerojasro@343 454 bad change has propagated into, you can \emph{try} to get rid of the
jerojasro@343 455 changeefrom \emph{every} one of those repositories. This is, of
jerojasro@343 456 course, not a satisfactory solution: if you miss even a single
jerojasro@343 457 repository while you're expunging, the change is still ``in the
jerojasro@343 458 wild'', and could propagate further.
jerojasro@343 459
jerojasro@343 460 If you've committed one or more changes \emph{after} the change that
jerojasro@343 461 you'd like to see disappear, your options are further reduced.
jerojasro@343 462 Mercurial doesn't provide a way to ``punch a hole'' in history,
jerojasro@343 463 leaving changesets intact.
jerojasro@343 464
jerojasro@343 465 XXX This needs filling out. The \texttt{hg-replay} script in the
jerojasro@343 466 \texttt{examples} directory works, but doesn't handle merge
jerojasro@343 467 changesets. Kind of an important omission.
jerojasro@343 468
jerojasro@343 469 \subsection{Protect yourself from ``escaped'' changes}
jerojasro@343 470
jerojasro@343 471 If you've committed some changes to your local repository and they've
jerojasro@343 472 been pushed or pulled somewhere else, this isn't necessarily a
jerojasro@343 473 disaster. You can protect yourself ahead of time against some classes
jerojasro@343 474 of bad changeset. This is particularly easy if your team usually
jerojasro@343 475 pulls changes from a central repository.
jerojasro@343 476
jerojasro@343 477 By configuring some hooks on that repository to validate incoming
jerojasro@343 478 changesets (see chapter~\ref{chap:hook}), you can automatically
jerojasro@343 479 prevent some kinds of bad changeset from being pushed to the central
jerojasro@343 480 repository at all. With such a configuration in place, some kinds of
jerojasro@343 481 bad changeset will naturally tend to ``die out'' because they can't
jerojasro@343 482 propagate into the central repository. Better yet, this happens
jerojasro@343 483 without any need for explicit intervention.
jerojasro@343 484
jerojasro@343 485 For instance, an incoming change hook that verifies that a changeset
jerojasro@343 486 will actually compile can prevent people from inadvertantly ``breaking
jerojasro@343 487 the build''.
jerojasro@343 488
jerojasro@343 489 \section{Finding the source of a bug}
jerojasro@343 490 \label{sec:undo:bisect}
jerojasro@343 491
jerojasro@343 492 While it's all very well to be able to back out a changeset that
jerojasro@343 493 introduced a bug, this requires that you know which changeset to back
jerojasro@343 494 out. Mercurial provides an invaluable command, called
jerojasro@343 495 \hgcmd{bisect}, that helps you to automate this process and accomplish
jerojasro@343 496 it very efficiently.
jerojasro@343 497
jerojasro@343 498 The idea behind the \hgcmd{bisect} command is that a changeset has
jerojasro@343 499 introduced some change of behaviour that you can identify with a
jerojasro@343 500 simple binary test. You don't know which piece of code introduced the
jerojasro@343 501 change, but you know how to test for the presence of the bug. The
jerojasro@343 502 \hgcmd{bisect} command uses your test to direct its search for the
jerojasro@343 503 changeset that introduced the code that caused the bug.
jerojasro@343 504
jerojasro@343 505 Here are a few scenarios to help you understand how you might apply
jerojasro@343 506 this command.
jerojasro@343 507 \begin{itemize}
jerojasro@343 508 \item The most recent version of your software has a bug that you
jerojasro@343 509 remember wasn't present a few weeks ago, but you don't know when it
jerojasro@343 510 was introduced. Here, your binary test checks for the presence of
jerojasro@343 511 that bug.
jerojasro@343 512 \item You fixed a bug in a rush, and now it's time to close the entry
jerojasro@343 513 in your team's bug database. The bug database requires a changeset
jerojasro@343 514 ID when you close an entry, but you don't remember which changeset
jerojasro@343 515 you fixed the bug in. Once again, your binary test checks for the
jerojasro@343 516 presence of the bug.
jerojasro@343 517 \item Your software works correctly, but runs~15\% slower than the
jerojasro@343 518 last time you measured it. You want to know which changeset
jerojasro@343 519 introduced the performance regression. In this case, your binary
jerojasro@343 520 test measures the performance of your software, to see whether it's
jerojasro@343 521 ``fast'' or ``slow''.
jerojasro@343 522 \item The sizes of the components of your project that you ship
jerojasro@343 523 exploded recently, and you suspect that something changed in the way
jerojasro@343 524 you build your project.
jerojasro@343 525 \end{itemize}
jerojasro@343 526
jerojasro@343 527 From these examples, it should be clear that the \hgcmd{bisect}
jerojasro@343 528 command is not useful only for finding the sources of bugs. You can
jerojasro@343 529 use it to find any ``emergent property'' of a repository (anything
jerojasro@343 530 that you can't find from a simple text search of the files in the
jerojasro@343 531 tree) for which you can write a binary test.
jerojasro@343 532
jerojasro@343 533 We'll introduce a little bit of terminology here, just to make it
jerojasro@343 534 clear which parts of the search process are your responsibility, and
jerojasro@343 535 which are Mercurial's. A \emph{test} is something that \emph{you} run
jerojasro@343 536 when \hgcmd{bisect} chooses a changeset. A \emph{probe} is what
jerojasro@343 537 \hgcmd{bisect} runs to tell whether a revision is good. Finally,
jerojasro@343 538 we'll use the word ``bisect'', as both a noun and a verb, to stand in
jerojasro@343 539 for the phrase ``search using the \hgcmd{bisect} command.
jerojasro@343 540
jerojasro@343 541 One simple way to automate the searching process would be simply to
jerojasro@343 542 probe every changeset. However, this scales poorly. If it took ten
jerojasro@343 543 minutes to test a single changeset, and you had 10,000 changesets in
jerojasro@343 544 your repository, the exhaustive approach would take on average~35
jerojasro@343 545 \emph{days} to find the changeset that introduced a bug. Even if you
jerojasro@343 546 knew that the bug was introduced by one of the last 500 changesets,
jerojasro@343 547 and limited your search to those, you'd still be looking at over 40
jerojasro@343 548 hours to find the changeset that introduced your bug.
jerojasro@343 549
jerojasro@343 550 What the \hgcmd{bisect} command does is use its knowledge of the
jerojasro@343 551 ``shape'' of your project's revision history to perform a search in
jerojasro@343 552 time proportional to the \emph{logarithm} of the number of changesets
jerojasro@343 553 to check (the kind of search it performs is called a dichotomic
jerojasro@343 554 search). With this approach, searching through 10,000 changesets will
jerojasro@343 555 take less than three hours, even at ten minutes per test (the search
jerojasro@343 556 will require about 14 tests). Limit your search to the last hundred
jerojasro@343 557 changesets, and it will take only about an hour (roughly seven tests).
jerojasro@343 558
jerojasro@343 559 The \hgcmd{bisect} command is aware of the ``branchy'' nature of a
jerojasro@343 560 Mercurial project's revision history, so it has no problems dealing
jerojasro@343 561 with branches, merges, or multiple heads in a repoository. It can
jerojasro@343 562 prune entire branches of history with a single probe, which is how it
jerojasro@343 563 operates so efficiently.
jerojasro@343 564
jerojasro@343 565 \subsection{Using the \hgcmd{bisect} command}
jerojasro@343 566
jerojasro@343 567 Here's an example of \hgcmd{bisect} in action.
jerojasro@343 568
jerojasro@343 569 \begin{note}
jerojasro@343 570 In versions 0.9.5 and earlier of Mercurial, \hgcmd{bisect} was not a
jerojasro@343 571 core command: it was distributed with Mercurial as an extension.
jerojasro@343 572 This section describes the built-in command, not the old extension.
jerojasro@343 573 \end{note}
jerojasro@343 574
jerojasro@343 575 Now let's create a repository, so that we can try out the
jerojasro@343 576 \hgcmd{bisect} command in isolation.
jerojasro@343 577 \interaction{bisect.init}
jerojasro@343 578 We'll simulate a project that has a bug in it in a simple-minded way:
jerojasro@343 579 create trivial changes in a loop, and nominate one specific change
jerojasro@343 580 that will have the ``bug''. This loop creates 35 changesets, each
jerojasro@343 581 adding a single file to the repository. We'll represent our ``bug''
jerojasro@343 582 with a file that contains the text ``i have a gub''.
jerojasro@343 583 \interaction{bisect.commits}
jerojasro@343 584
jerojasro@343 585 The next thing that we'd like to do is figure out how to use the
jerojasro@343 586 \hgcmd{bisect} command. We can use Mercurial's normal built-in help
jerojasro@343 587 mechanism for this.
jerojasro@343 588 \interaction{bisect.help}
jerojasro@343 589
jerojasro@343 590 The \hgcmd{bisect} command works in steps. Each step proceeds as follows.
jerojasro@343 591 \begin{enumerate}
jerojasro@343 592 \item You run your binary test.
jerojasro@343 593 \begin{itemize}
jerojasro@343 594 \item If the test succeeded, you tell \hgcmd{bisect} by running the
jerojasro@343 595 \hgcmdargs{bisect}{good} command.
jerojasro@343 596 \item If it failed, run the \hgcmdargs{bisect}{--bad} command.
jerojasro@343 597 \end{itemize}
jerojasro@343 598 \item The command uses your information to decide which changeset to
jerojasro@343 599 test next.
jerojasro@343 600 \item It updates the working directory to that changeset, and the
jerojasro@343 601 process begins again.
jerojasro@343 602 \end{enumerate}
jerojasro@343 603 The process ends when \hgcmd{bisect} identifies a unique changeset
jerojasro@343 604 that marks the point where your test transitioned from ``succeeding''
jerojasro@343 605 to ``failing''.
jerojasro@343 606
jerojasro@343 607 To start the search, we must run the \hgcmdargs{bisect}{--reset} command.
jerojasro@343 608 \interaction{bisect.search.init}
jerojasro@343 609
jerojasro@343 610 In our case, the binary test we use is simple: we check to see if any
jerojasro@343 611 file in the repository contains the string ``i have a gub''. If it
jerojasro@343 612 does, this changeset contains the change that ``caused the bug''. By
jerojasro@343 613 convention, a changeset that has the property we're searching for is
jerojasro@343 614 ``bad'', while one that doesn't is ``good''.
jerojasro@343 615
jerojasro@343 616 Most of the time, the revision to which the working directory is
jerojasro@343 617 synced (usually the tip) already exhibits the problem introduced by
jerojasro@343 618 the buggy change, so we'll mark it as ``bad''.
jerojasro@343 619 \interaction{bisect.search.bad-init}
jerojasro@343 620
jerojasro@343 621 Our next task is to nominate a changeset that we know \emph{doesn't}
jerojasro@343 622 have the bug; the \hgcmd{bisect} command will ``bracket'' its search
jerojasro@343 623 between the first pair of good and bad changesets. In our case, we
jerojasro@343 624 know that revision~10 didn't have the bug. (I'll have more words
jerojasro@343 625 about choosing the first ``good'' changeset later.)
jerojasro@343 626 \interaction{bisect.search.good-init}
jerojasro@343 627
jerojasro@343 628 Notice that this command printed some output.
jerojasro@343 629 \begin{itemize}
jerojasro@343 630 \item It told us how many changesets it must consider before it can
jerojasro@343 631 identify the one that introduced the bug, and how many tests that
jerojasro@343 632 will require.
jerojasro@343 633 \item It updated the working directory to the next changeset to test,
jerojasro@343 634 and told us which changeset it's testing.
jerojasro@343 635 \end{itemize}
jerojasro@343 636
jerojasro@343 637 We now run our test in the working directory. We use the
jerojasro@343 638 \command{grep} command to see if our ``bad'' file is present in the
jerojasro@343 639 working directory. If it is, this revision is bad; if not, this
jerojasro@343 640 revision is good.
jerojasro@343 641 \interaction{bisect.search.step1}
jerojasro@343 642
jerojasro@343 643 This test looks like a perfect candidate for automation, so let's turn
jerojasro@343 644 it into a shell function.
jerojasro@343 645 \interaction{bisect.search.mytest}
jerojasro@343 646 We can now run an entire test step with a single command,
jerojasro@343 647 \texttt{mytest}.
jerojasro@343 648 \interaction{bisect.search.step2}
jerojasro@343 649 A few more invocations of our canned test step command, and we're
jerojasro@343 650 done.
jerojasro@343 651 \interaction{bisect.search.rest}
jerojasro@343 652
jerojasro@343 653 Even though we had~40 changesets to search through, the \hgcmd{bisect}
jerojasro@343 654 command let us find the changeset that introduced our ``bug'' with
jerojasro@343 655 only five tests. Because the number of tests that the \hgcmd{bisect}
jerojasro@343 656 command performs grows logarithmically with the number of changesets to
jerojasro@343 657 search, the advantage that it has over the ``brute force'' search
jerojasro@343 658 approach increases with every changeset you add.
jerojasro@343 659
jerojasro@343 660 \subsection{Cleaning up after your search}
jerojasro@343 661
jerojasro@343 662 When you're finished using the \hgcmd{bisect} command in a
jerojasro@343 663 repository, you can use the \hgcmdargs{bisect}{reset} command to drop
jerojasro@343 664 the information it was using to drive your search. The command
jerojasro@343 665 doesn't use much space, so it doesn't matter if you forget to run this
jerojasro@343 666 command. However, \hgcmd{bisect} won't let you start a new search in
jerojasro@343 667 that repository until you do a \hgcmdargs{bisect}{reset}.
jerojasro@343 668 \interaction{bisect.search.reset}
jerojasro@343 669
jerojasro@343 670 \section{Tips for finding bugs effectively}
jerojasro@343 671
jerojasro@343 672 \subsection{Give consistent input}
jerojasro@343 673
jerojasro@343 674 The \hgcmd{bisect} command requires that you correctly report the
jerojasro@343 675 result of every test you perform. If you tell it that a test failed
jerojasro@343 676 when it really succeeded, it \emph{might} be able to detect the
jerojasro@343 677 inconsistency. If it can identify an inconsistency in your reports,
jerojasro@343 678 it will tell you that a particular changeset is both good and bad.
jerojasro@343 679 However, it can't do this perfectly; it's about as likely to report
jerojasro@343 680 the wrong changeset as the source of the bug.
jerojasro@343 681
jerojasro@343 682 \subsection{Automate as much as possible}
jerojasro@343 683
jerojasro@343 684 When I started using the \hgcmd{bisect} command, I tried a few times
jerojasro@343 685 to run my tests by hand, on the command line. This is an approach
jerojasro@343 686 that I, at least, am not suited to. After a few tries, I found that I
jerojasro@343 687 was making enough mistakes that I was having to restart my searches
jerojasro@343 688 several times before finally getting correct results.
jerojasro@343 689
jerojasro@343 690 My initial problems with driving the \hgcmd{bisect} command by hand
jerojasro@343 691 occurred even with simple searches on small repositories; if the
jerojasro@343 692 problem you're looking for is more subtle, or the number of tests that
jerojasro@343 693 \hgcmd{bisect} must perform increases, the likelihood of operator
jerojasro@343 694 error ruining the search is much higher. Once I started automating my
jerojasro@343 695 tests, I had much better results.
jerojasro@343 696
jerojasro@343 697 The key to automated testing is twofold:
jerojasro@343 698 \begin{itemize}
jerojasro@343 699 \item always test for the same symptom, and
jerojasro@343 700 \item always feed consistent input to the \hgcmd{bisect} command.
jerojasro@343 701 \end{itemize}
jerojasro@343 702 In my tutorial example above, the \command{grep} command tests for the
jerojasro@343 703 symptom, and the \texttt{if} statement takes the result of this check
jerojasro@343 704 and ensures that we always feed the same input to the \hgcmd{bisect}
jerojasro@343 705 command. The \texttt{mytest} function marries these together in a
jerojasro@343 706 reproducible way, so that every test is uniform and consistent.
jerojasro@343 707
jerojasro@343 708 \subsection{Check your results}
jerojasro@343 709
jerojasro@343 710 Because the output of a \hgcmd{bisect} search is only as good as the
jerojasro@343 711 input you give it, don't take the changeset it reports as the
jerojasro@343 712 absolute truth. A simple way to cross-check its report is to manually
jerojasro@343 713 run your test at each of the following changesets:
jerojasro@343 714 \begin{itemize}
jerojasro@343 715 \item The changeset that it reports as the first bad revision. Your
jerojasro@343 716 test should still report this as bad.
jerojasro@343 717 \item The parent of that changeset (either parent, if it's a merge).
jerojasro@343 718 Your test should report this changeset as good.
jerojasro@343 719 \item A child of that changeset. Your test should report this
jerojasro@343 720 changeset as bad.
jerojasro@343 721 \end{itemize}
jerojasro@343 722
jerojasro@343 723 \subsection{Beware interference between bugs}
jerojasro@343 724
jerojasro@343 725 It's possible that your search for one bug could be disrupted by the
jerojasro@343 726 presence of another. For example, let's say your software crashes at
jerojasro@343 727 revision 100, and worked correctly at revision 50. Unknown to you,
jerojasro@343 728 someone else introduced a different crashing bug at revision 60, and
jerojasro@343 729 fixed it at revision 80. This could distort your results in one of
jerojasro@343 730 several ways.
jerojasro@343 731
jerojasro@343 732 It is possible that this other bug completely ``masks'' yours, which
jerojasro@343 733 is to say that it occurs before your bug has a chance to manifest
jerojasro@343 734 itself. If you can't avoid that other bug (for example, it prevents
jerojasro@343 735 your project from building), and so can't tell whether your bug is
jerojasro@343 736 present in a particular changeset, the \hgcmd{bisect} command cannot
jerojasro@343 737 help you directly. Instead, you can mark a changeset as untested by
jerojasro@343 738 running \hgcmdargs{bisect}{--skip}.
jerojasro@343 739
jerojasro@343 740 A different problem could arise if your test for a bug's presence is
jerojasro@343 741 not specific enough. If you check for ``my program crashes'', then
jerojasro@343 742 both your crashing bug and an unrelated crashing bug that masks it
jerojasro@343 743 will look like the same thing, and mislead \hgcmd{bisect}.
jerojasro@343 744
jerojasro@343 745 Another useful situation in which to use \hgcmdargs{bisect}{--skip} is
jerojasro@343 746 if you can't test a revision because your project was in a broken and
jerojasro@343 747 hence untestable state at that revision, perhaps because someone
jerojasro@343 748 checked in a change that prevented the project from building.
jerojasro@343 749
jerojasro@343 750 \subsection{Bracket your search lazily}
jerojasro@343 751
jerojasro@343 752 Choosing the first ``good'' and ``bad'' changesets that will mark the
jerojasro@343 753 end points of your search is often easy, but it bears a little
jerojasro@343 754 discussion nevertheless. From the perspective of \hgcmd{bisect}, the
jerojasro@343 755 ``newest'' changeset is conventionally ``bad'', and the older
jerojasro@343 756 changeset is ``good''.
jerojasro@343 757
jerojasro@343 758 If you're having trouble remembering when a suitable ``good'' change
jerojasro@343 759 was, so that you can tell \hgcmd{bisect}, you could do worse than
jerojasro@343 760 testing changesets at random. Just remember to eliminate contenders
jerojasro@343 761 that can't possibly exhibit the bug (perhaps because the feature with
jerojasro@343 762 the bug isn't present yet) and those where another problem masks the
jerojasro@343 763 bug (as I discussed above).
jerojasro@343 764
jerojasro@343 765 Even if you end up ``early'' by thousands of changesets or months of
jerojasro@343 766 history, you will only add a handful of tests to the total number that
jerojasro@343 767 \hgcmd{bisect} must perform, thanks to its logarithmic behaviour.
jerojasro@343 768
jerojasro@343 769 %%% Local Variables:
jerojasro@343 770 %%% mode: latex
jerojasro@343 771 %%% TeX-master: "00book"
jerojasro@343 772 %%% End: